@sanity/sdk 2.11.1 → 2.13.0

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
+}

package/src/releases/getPerspectiveState.test.ts

@@ -1,3 +1,4 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {filter, firstValueFrom, of, Subject, take} from 'rxjs'
 import {describe, expect, it, vi} from 'vitest'
 
@@ -6,7 +7,6 @@ import {getQueryState} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getPerspectiveState} from './getPerspectiveState'
-import {type ReleaseDocument} from './releasesStore'
 
 vi.mock('../query/queryStore')
 

package/src/releases/releasesStore.test.ts

@@ -1,10 +1,11 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {NEVER, Observable, type Observer, of, Subject} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {getQueryState, resolveQuery} from '../query/queryStore'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
-import {getActiveReleasesState, type ReleaseDocument} from './releasesStore'
+import {getActiveReleasesState, getAllReleasesState} from './releasesStore'
 
 // Mock dependencies
 vi.mock('../query/queryStore')
@@ -167,6 +168,54 @@ describe('releasesStore', () => {
     expect(state.getCurrent()).toEqual([])
   })
 
+  it('exposes archived/published releases through getAllReleasesState but filters them out of getActiveReleasesState', async () => {
+    const subject = new Subject<ReleaseDocument[]>()
+    vi.mocked(getQueryState).mockReturnValue({
+      subscribe: () => () => {},
+      getCurrent: () => undefined,
+      observable: subject.asObservable(),
+    } as StateSource<ReleaseDocument[] | undefined>)
+
+    const active = getActiveReleasesState(instance, {
+      resource: {projectId: 'test', dataset: 'test'},
+    })
+    const all = getAllReleasesState(instance, {resource: {projectId: 'test', dataset: 'test'}})
+
+    const releases: ReleaseDocument[] = [
+      {
+        _id: 'r-active',
+        _type: 'system.release',
+        name: 'r-active',
+        state: 'active',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-archived',
+        _type: 'system.release',
+        name: 'r-archived',
+        state: 'archived',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+      {
+        _id: 'r-published',
+        _type: 'system.release',
+        name: 'r-published',
+        state: 'published',
+        metadata: {releaseType: 'asap'},
+      } as ReleaseDocument,
+    ]
+
+    subject.next(releases)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    const activeNames = active.getCurrent()?.map((r) => r.name) ?? []
+    const allNames = all.getCurrent()?.map((r) => r.name) ?? []
+
+    expect(activeNames).toEqual(['r-active'])
+    expect(allNames).toEqual(expect.arrayContaining(['r-active', 'r-archived', 'r-published']))
+    expect(allNames).toHaveLength(3)
+  })
+
   it('should not crash when the releases query errors', async () => {
     const subject = new Subject<ReleaseDocument[]>()
     vi.mocked(getQueryState).mockReturnValue({

package/src/releases/releasesStore.ts

@@ -1,4 +1,4 @@
-import {type SanityDocument} from '@sanity/types'
+import {type ReleaseDocument} from '@sanity/client'
 import {map} from 'rxjs'
 
 import {type DocumentResource} from '../config/sanityConfig'
@@ -21,23 +21,23 @@ const ARCHIVED_RELEASE_STATES = ['archived', 'published']
 const STABLE_EMPTY_RELEASES: ReleaseDocument[] = []
 
 /**
- * Represents a document in a Sanity dataset that represents release options.
- * @internal
+ * Lifecycle states a release document can be in. Mirrors the server's
+ * `ReleaseState`.
+ * @beta
  */
-export type ReleaseDocument = SanityDocument & {
-  name: string
-  publishAt?: string
-  state: 'active' | 'scheduled'
-  metadata: {
-    title: string
-    releaseType: 'asap' | 'scheduled' | 'undecided'
-    intendedPublishAt?: string
-    description?: string
-  }
-}
+export type ReleaseState =
+  | 'active'
+  | 'archiving'
+  | 'unarchiving'
+  | 'archived'
+  | 'published'
+  | 'publishing'
+  | 'scheduled'
+  | 'scheduling'
 
 export interface ReleasesStoreState {
   activeReleases?: ReleaseDocument[]
+  allReleases?: ReleaseDocument[]
   error?: unknown
 }
 
@@ -45,6 +45,7 @@ export const releasesStore = defineStore<ReleasesStoreState, BoundResourceKey>({
   name: 'Releases',
   getInitialState: (): ReleasesStoreState => ({
     activeReleases: undefined,
+    allReleases: undefined,
   }),
   initialize: (context) => {
     const subscription = subscribeToReleases(context)
@@ -74,6 +75,26 @@ export const getActiveReleasesState = (
   // bindActionByResource keyFn destructures { resource } from the first param, so pass {} when no options
   _getActiveReleasesState(instance, options ?? {})
 
+/**
+ * Get every release in the store, including archived and published.
+ * @internal
+ */
+const _getAllReleasesState = bindActionByResource(
+  releasesStore,
+  createStateSourceAction({
+    selector: ({state}, _?) => state.allReleases,
+  }),
+)
+
+/**
+ * Get every release in the store, including archived and published.
+ * @internal
+ */
+export const getAllReleasesState = (
+  instance: SanityInstance,
+  options?: {resource?: DocumentResource},
+): StateSource<ReleaseDocument[] | undefined> => _getAllReleasesState(instance, options ?? {})
+
 const RELEASES_QUERY = 'releases::all()'
 
 const subscribeToReleases = ({
@@ -92,10 +113,12 @@ const subscribeToReleases = ({
       map((releases) => {
         // logic here mirrors that of studio:
         // https://github.com/sanity-io/sanity/blob/156e8fa482703d99219f08da7bacb384517f1513/packages/sanity/src/core/releases/store/useActiveReleases.ts#L29
-        state.set('setActiveReleases', {
-          activeReleases: sortReleases(releases ?? STABLE_EMPTY_RELEASES)
-            .filter((release) => !ARCHIVED_RELEASE_STATES.includes(release.state))
-            .reverse(),
+        const sorted = sortReleases(releases ?? STABLE_EMPTY_RELEASES).reverse()
+        state.set('setReleases', {
+          allReleases: sorted,
+          activeReleases: sorted.filter(
+            (release) => !ARCHIVED_RELEASE_STATES.includes(release.state),
+          ),
         })
       }),
     )

package/src/releases/utils/sortReleases.test.ts

@@ -1,6 +1,6 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {describe, expect, it} from 'vitest'
 
-import {type ReleaseDocument} from '../releasesStore'
 import {sortReleases} from './sortReleases'
 
 // Mock function to create a release document
@@ -15,7 +15,7 @@ function createReleaseMock(
   return {
     _id: id,
     _rev: 'rev',
-    _type: 'release',
+    _type: 'system.release',
     _createdAt: new Date().toISOString(),
     _updatedAt: new Date().toISOString(),
     state: 'active',

package/src/releases/utils/sortReleases.ts

@@ -1,4 +1,4 @@
-import {type ReleaseDocument} from '../releasesStore'
+import {type ReleaseDocument} from '@sanity/client'
 
 // mirrors the order of the releases in the releases list in Studio
 // https://github.com/sanity-io/sanity/blob/main/packages/sanity/src/core/releases/hooks/utils.ts

package/src/telemetry/environment.test.ts

@@ -0,0 +1,119 @@
+import {afterEach, describe, expect, it, vi} from 'vitest'
+
+import {getTelemetryEnvironment, isTelemetryEnabled} from './environment'
+
+describe('getTelemetryEnvironment', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  describe('browser', () => {
+    it('returns "development" on localhost', () => {
+      vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns "development" on 127.0.0.1', () => {
+      vi.stubGlobal('window', {location: {hostname: '127.0.0.1'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns "production" on *.sanity.studio', () => {
+      vi.stubGlobal('window', {location: {hostname: 'myapp.sanity.studio'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns "production" on www.sanity.io (dashboard)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'www.sanity.io'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns null on *.sanity.work (staging is intentionally not allowlisted)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'www.sanity.work'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on *.sanity.dev (preview hosts are intentionally not allowlisted)', () => {
+      vi.stubGlobal('window', {location: {hostname: 'preview-123.sanity.dev'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('is case-insensitive on hostname', () => {
+      vi.stubGlobal('window', {location: {hostname: 'MyApp.Sanity.Studio'}})
+      expect(getTelemetryEnvironment()).toBe('production')
+    })
+
+    it('returns null on a customer-controlled domain', () => {
+      vi.stubGlobal('window', {location: {hostname: 'myapp.customer.com'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on a lookalike subdomain (suffix match requires a leading dot)', () => {
+      // `evilsanity.studio` ends in `sanity.studio` but not `.sanity.studio`,
+      // so the suffix check rejects it.
+      vi.stubGlobal('window', {location: {hostname: 'evilsanity.studio'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null on the bare apex hostname (sanity.studio with no subdomain)', () => {
+      // The allowlist intentionally only matches subdomains (the leading
+      // `.` in `.sanity.studio` means the apex `sanity.studio` is excluded).
+      vi.stubGlobal('window', {location: {hostname: 'sanity.studio'}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null when hostname is missing', () => {
+      vi.stubGlobal('window', {location: {}})
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns "development" on localhost even when NODE_ENV is production', () => {
+      vi.stubEnv('NODE_ENV', 'production')
+      vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+  })
+
+  describe('node', () => {
+    it('returns "development" when NODE_ENV=development and no window', () => {
+      vi.stubEnv('NODE_ENV', 'development')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBe('development')
+    })
+
+    it('returns null when NODE_ENV=production and no window', () => {
+      vi.stubEnv('NODE_ENV', 'production')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+
+    it('returns null when NODE_ENV=test and no window', () => {
+      vi.stubEnv('NODE_ENV', 'test')
+      vi.stubGlobal('window', undefined)
+      expect(getTelemetryEnvironment()).toBeNull()
+    })
+  })
+})
+
+describe('isTelemetryEnabled', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  it('returns true on a Sanity-controlled domain', () => {
+    vi.stubGlobal('window', {location: {hostname: 'app.sanity.studio'}})
+    expect(isTelemetryEnabled()).toBe(true)
+  })
+
+  it('returns true on localhost', () => {
+    vi.stubGlobal('window', {location: {hostname: 'localhost'}})
+    expect(isTelemetryEnabled()).toBe(true)
+  })
+
+  it('returns false on a customer domain', () => {
+    vi.stubGlobal('window', {location: {hostname: 'myapp.example.com'}})
+    expect(isTelemetryEnabled()).toBe(false)
+  })
+})