@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.2

package/src/config/handles.ts

@@ -1,4 +1,9 @@
-import {type DocumentHandle, type DocumentTypeHandle, type ResourceHandle} from './sanityConfig'
+import {
+  type DatasetHandle,
+  type DocumentHandle,
+  type DocumentTypeHandle,
+  type ProjectHandle,
+} from './sanityConfig'
 
 /**
  * Creates or validates a `DocumentHandle` object.
@@ -35,15 +40,28 @@ export function createDocumentTypeHandle<
 }
 
 /**
- * Creates or validates a `ResourceHandle` object.
- * Ensures the provided object conforms to the `ResourceHandle` interface.
- * @param handle - The object containing resource identification properties.
- * @returns The validated `ResourceHandle` object.
+ * Creates or validates a `ProjectHandle` object.
+ * Ensures the provided object conforms to the `ProjectHandle` interface.
+ * @param handle - The object containing project identification properties.
+ * @returns The validated `ProjectHandle` object.
  * @public
  */
-export function createResourceHandle<
+export function createProjectHandle<TProjectId extends string = string>(
+  handle: ProjectHandle<TProjectId>,
+): ProjectHandle<TProjectId> {
+  return handle
+}
+
+/**
+ * Creates or validates a `DatasetHandle` object.
+ * Ensures the provided object conforms to the `DatasetHandle` interface.
+ * @param handle - The object containing dataset identification properties.
+ * @returns The validated `DatasetHandle` object.
+ * @public
+ */
+export function createDatasetHandle<
   TDataset extends string = string,
   TProjectId extends string = string,
->(handle: ResourceHandle<TProjectId, TDataset>): ResourceHandle<TProjectId, TDataset> {
+>(handle: DatasetHandle<TDataset, TProjectId>): DatasetHandle<TDataset, TProjectId> {
   return handle
 }

package/src/config/sanityConfig.ts

@@ -40,12 +40,14 @@ export interface StudioConfig {
      */
     token?: TokenSource
   }
-  /**
-   * The project ID for this Studio workspace.
-   * Used to derive the localStorage key for studio auth token discovery
-   * (`__studio_auth_token_<projectId>`) and for project-specific API hostname requests.
-   */
-  projectId?: string
+}
+
+/**
+ * Represents the minimal configuration required to identify a Sanity project.
+ * @public
+ */
+export interface ProjectHandle<TProjectId extends string = string> {
+  projectId?: TProjectId
 }
 
 /**
@@ -60,27 +62,22 @@ export type ReleasePerspective = {
  * @public
  */
 export interface PerspectiveHandle {
-  /**
-   * The perspective to use for this operation.
-   * Note that the SDK stacks perspectives for you when querying.
-   * The SDK automatically fetches all of your content releases, and orders them the way the Sanity Studio does: usually by scheduled date, with ASAP releases coming first.
-   * @public
-   */
-  perspective?: Exclude<ClientPerspective, readonly unknown[]> | ReleasePerspective
+  perspective?: ClientPerspective | ReleasePerspective
 }
 
 /**
  * @public
  */
-export interface ResourceHandle<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> extends PerspectiveHandle {
+export interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string>
+  extends ProjectHandle<TProjectId>, PerspectiveHandle {
+  dataset?: TDataset
   /**
-   * Explicit resource object to use for this operation.
-   * @public
+   * @beta
+   * Explicit resource to use. On an individual operation this overrides any default;
+   * on a `SanityConfig` it becomes the instance's default resource. Unlike
+   * `projectId`/`dataset`, this can also be a media library or canvas resource.
    */
-  resource: DocumentResource<TProjectId, TDataset>
+  resource?: DocumentResource
 }
 
 /**
@@ -93,7 +90,7 @@ export interface DocumentTypeHandle<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends ResourceHandle<TDataset, TProjectId> {
+> extends DatasetHandle<TDataset, TProjectId> {
   documentId?: string
   documentType: TDocumentType
   /**
@@ -119,42 +116,22 @@ export interface DocumentHandle<
 }
 
 /**
- * The key used to identify the default resource in a resources map.
- * When no `resource` or `resourceName` is specified, the SDK resolves
- * the resource registered under this name.
- *
- * @public
+ * Identifies a release within a Sanity dataset and project. `releaseId` is the
+ * `name` parameter on the release document (e.g. `{name: 'r41035a4'}`).
+ * The underlying release document ID is `_.releases.<releaseId>`.
+ * It's also the `id` parameter sent to the Actions API.
+ * (This type doesn't need to have ProjectId / Dataset generics since it's always the same shape)
+ * @beta
  */
-export const DEFAULT_RESOURCE_NAME = 'default'
+export interface ReleaseHandle extends DatasetHandle {
+  releaseId: string
+}
 
 /**
- * Represents the complete configuration for a Sanity SDK instance.
- *
- * Most apps configure resources via the `resources` prop on `SanityApp`:
- *
- * @example Typical React usage
- * ```tsx
- * <SanityApp
- *   resources={{ default: { projectId: 'abc123', dataset: 'production' } }}
- *   fallback={<Loading />}
- * >
- *   <App />
- * </SanityApp>
- * ```
- *
- * The `defaultResource` field is set automatically by the React layer from
- * `resources['default']`. It can also be set directly when using the core
- * SDK without React (e.g. in a Node.js script):
- *
- * @example Direct core usage (without React)
- * ```ts
- * const instance = createSanityInstance({
- *   defaultResource: { projectId: 'abc123', dataset: 'production' },
- * })
- * ```
+ * Represents the complete configuration for a Sanity SDK instance
  * @public
  */
-export interface SanityConfig extends PerspectiveHandle {
+export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
   /**
    * Authentication configuration for the instance
    */
@@ -168,58 +145,40 @@ export interface SanityConfig extends PerspectiveHandle {
    * `SDKStudioContext` provider. Can also be set explicitly for programmatic use.
    */
   studio?: StudioConfig
-  /**
-   * The default document resource for this instance. Used by bound actions
-   * when no explicit resource is provided.
-   *
-   * @public
-   */
-  defaultResource?: DocumentResource
 }
 
 /**
- * A document resource identifies where data is stored and queried from.
- * Can be a dataset (project + dataset pair), a media library, or a canvas.
+ * A document resource can be used for querying.
+ * This will soon be the default way to identify where you are querying from.
  *
- * @public
+ * @beta
  */
-export type DocumentResource<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> = DatasetResource<TProjectId, TDataset> | MediaLibraryResource | CanvasResource
+export type DocumentResource = DatasetResource | MediaLibraryResource | CanvasResource
 
 /**
- * A resource that targets a specific project and dataset.
- * @public
+ * @beta
  */
-export type DatasetResource<
-  TProjectId extends string = string,
-  TDataset extends string = string,
-> = {projectId: TProjectId; dataset: TDataset}
+export type DatasetResource = {projectId: string; dataset: string}
 
 /**
- * A resource that targets a media library.
- * @public
+ * @beta
  */
 export type MediaLibraryResource = {mediaLibraryId: string}
 
 /**
- * A resource that targets a canvas.
- * @public
+ * @beta
  */
 export type CanvasResource = {canvasId: string}
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link DatasetResource}.
- * @public
+ * @beta
  */
 export function isDatasetResource(resource: DocumentResource): resource is DatasetResource {
   return 'projectId' in resource && 'dataset' in resource
 }
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link MediaLibraryResource}.
- * @public
+ * @beta
  */
 export function isMediaLibraryResource(
   resource: DocumentResource,
@@ -228,8 +187,7 @@ export function isMediaLibraryResource(
 }
 
 /**
- * Type guard that checks whether a {@link DocumentResource} is a {@link CanvasResource}.
- * @public
+ * @beta
  */
 export function isCanvasResource(resource: DocumentResource): resource is CanvasResource {
   return 'canvasId' in resource

package/src/datasets/datasets.test.ts

@@ -11,7 +11,7 @@ vi.mock('../client/clientStore')
 
 describe('datasets', () => {
   it('calls the `client.observable.datasets.list` method on the client and returns the result', async () => {
-    const instance = createSanityInstance()
+    const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
     const datasets = [{id: 'a'}, {id: 'b'}]
     const list = vi.fn().mockReturnValue(of(datasets))
 
@@ -25,7 +25,7 @@ describe('datasets', () => {
       observable: of(mockClient),
     } as StateSource<SanityClient>)
 
-    const result = await resolveDatasets(instance, {projectId: 'p'})
+    const result = await resolveDatasets(instance)
     expect(result).toEqual(datasets)
     expect(list).toHaveBeenCalled()
   })

package/src/datasets/datasets.ts

@@ -1,6 +1,7 @@
 import {switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
+import {type ProjectHandle} from '../config/sanityConfig'
 import {createFetcherStore} from '../utils/createFetcherStore'
 
 const API_VERSION = 'v2025-02-19'
@@ -8,13 +9,18 @@ const API_VERSION = 'v2025-02-19'
 /** @public */
 export const datasets = createFetcherStore({
   name: 'Datasets',
-  getKey: (_instance, options: {projectId: string}) => {
-    return options.projectId
+  getKey: (instance, options?: ProjectHandle) => {
+    const projectId = options?.projectId ?? instance.config.projectId
+    if (!projectId) {
+      throw new Error('A projectId is required to use the project API.')
+    }
+    return projectId
   },
-  fetcher: (instance) => (options: {projectId: string}) => {
+  fetcher: (instance) => (options?: ProjectHandle) => {
     return getClientState(instance, {
       apiVersion: API_VERSION,
-      projectId: options.projectId,
+      // non-null assertion is fine because we check above
+      projectId: (options?.projectId ?? instance.config.projectId)!,
       useProjectHostname: true,
     }).observable.pipe(switchMap((client) => client.observable.datasets.list()))
   },

package/src/document/actions.test.ts

@@ -1,32 +1,35 @@
+import {type ReleaseDocument} from '@sanity/client'
 import {at, patch, set, setIfMissing} from '@sanity/mutate'
 import {type PatchOperations} from '@sanity/types'
 import {describe, expect, it} from 'vitest'
 
-import {type DocumentHandle, type DocumentResource} from '../config/sanityConfig'
+import {type DocumentHandle, type ReleaseHandle} from '../config/sanityConfig'
 import {
+  archiveRelease,
   createDocument,
+  createRelease,
   deleteDocument,
+  deleteRelease,
   discardDocument,
   editDocument,
+  editRelease,
   publishDocument,
+  publishRelease,
+  scheduleRelease,
+  unarchiveRelease,
   unpublishDocument,
+  unscheduleRelease,
 } from '../document/actions'
 
 const dummyPatch: PatchOperations = {
   diffMatchPatch: {'dummy.path': 'dummy patch'},
 }
-const dummyDocResource: DocumentResource = {projectId: 'test-project', dataset: 'test-dataset'}
 
-const dummyDocHandle: DocumentHandle = {
-  documentId: 'drafts.abc123',
-  documentType: 'testType',
-  resource: dummyDocResource,
-}
-const dummyDocString: DocumentHandle = {
-  documentId: 'drafts.abc123',
-  documentType: 'testType',
-  resource: dummyDocResource,
-}
+const dummyDocHandle: DocumentHandle = {documentId: 'drafts.abc123', documentType: 'testType'}
+const dummyDocString = {documentId: 'drafts.abc123', documentType: 'testType'}
+
+const dummyReleaseHandle: ReleaseHandle = {releaseId: 'my-release'}
+const dummyReleasePatch: PatchOperations = {set: {'metadata.title': 'Updated title'}}
 
 describe('document actions', () => {
   describe('createDocument', () => {
@@ -37,24 +40,18 @@ describe('document actions', () => {
         // getId returns the input if it does not end with a dot.
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
     it('creates a document action from a document type handle', () => {
       // A document type handle is similar to a document handle,
       // but _id is optional.
-      const typeHandle = {
-        documentId: 'abc456',
-        documentType: 'anotherType',
-        resource: dummyDocResource,
-      }
+      const typeHandle = {documentId: 'abc456', documentType: 'anotherType'}
       const action = createDocument(typeHandle)
       expect(action).toEqual({
         type: 'document.create',
         documentId: 'abc456',
         documentType: typeHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -70,7 +67,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         initialValue,
-        resource: dummyDocResource,
       })
     })
 
@@ -80,7 +76,6 @@ describe('document actions', () => {
         type: 'document.create',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -91,7 +86,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         initialValue: {},
-        resource: dummyDocResource,
       })
     })
   })
@@ -104,7 +98,6 @@ describe('document actions', () => {
         type: 'document.delete',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -114,7 +107,6 @@ describe('document actions', () => {
         type: 'document.delete',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -127,7 +119,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
         patches: [dummyPatch],
-        resource: dummyDocResource,
       })
     })
 
@@ -138,7 +129,6 @@ describe('document actions', () => {
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
         patches: [dummyPatch],
-        resource: dummyDocResource,
       })
     })
 
@@ -165,7 +155,6 @@ describe('document actions', () => {
           {ifRevisionID: 'txn0', set: {'address.city': 'Oslo'}},
         ],
         type: 'document.edit',
-        resource: dummyDocResource,
       })
     })
   })
@@ -177,7 +166,6 @@ describe('document actions', () => {
         type: 'document.publish',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -187,7 +175,6 @@ describe('document actions', () => {
         type: 'document.publish',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -199,7 +186,6 @@ describe('document actions', () => {
         type: 'document.unpublish',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -209,7 +195,6 @@ describe('document actions', () => {
         type: 'document.unpublish',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
@@ -221,7 +206,6 @@ describe('document actions', () => {
         type: 'document.discard',
         documentId: 'abc123',
         documentType: dummyDocString.documentType,
-        resource: dummyDocResource,
       })
     })
 
@@ -231,8 +215,106 @@ describe('document actions', () => {
         type: 'document.discard',
         documentId: 'abc123',
         documentType: dummyDocHandle.documentType,
-        resource: dummyDocResource,
       })
     })
   })
 })
+
+describe('release actions', () => {
+  describe('createRelease', () => {
+    it('creates a release action from a release handle', () => {
+      const action = createRelease(dummyReleaseHandle)
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        metadata: {releaseType: 'undecided'},
+      })
+    })
+
+    it('creates a release action with metadata', () => {
+      const metadata: ReleaseDocument['metadata'] = {
+        title: 'My release',
+        description: 'Some description',
+        releaseType: 'scheduled',
+        intendedPublishAt: '2026-01-01T00:00:00.000Z',
+      }
+      const action = createRelease(dummyReleaseHandle, metadata)
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        metadata,
+      })
+    })
+
+    it('preserves resource fields from the handle', () => {
+      const action = createRelease({
+        releaseId: 'my-release',
+        resource: {dataset: 'production', projectId: 'abc123'},
+      })
+      expect(action).toEqual({
+        type: 'release.create',
+        releaseId: 'my-release',
+        resource: {dataset: 'production', projectId: 'abc123'},
+        metadata: {releaseType: 'undecided'},
+      })
+    })
+  })
+
+  describe('editRelease', () => {
+    it('creates a release.edit action with a patch', () => {
+      const action = editRelease(dummyReleaseHandle, dummyReleasePatch)
+      expect(action).toEqual({
+        type: 'release.edit',
+        releaseId: 'my-release',
+        patch: dummyReleasePatch,
+      })
+    })
+  })
+
+  describe('publishRelease', () => {
+    it('creates a release.publish action from a release handle', () => {
+      const action = publishRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.publish', releaseId: 'my-release'})
+    })
+  })
+
+  describe('scheduleRelease', () => {
+    it('creates a release.schedule action with publishAt', () => {
+      const publishAt = '2026-01-01T00:00:00.000Z'
+      const action = scheduleRelease(dummyReleaseHandle, publishAt)
+      expect(action).toEqual({
+        type: 'release.schedule',
+        releaseId: 'my-release',
+        publishAt,
+      })
+    })
+  })
+
+  describe('unscheduleRelease', () => {
+    it('creates a release.unschedule action from a release handle', () => {
+      const action = unscheduleRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.unschedule', releaseId: 'my-release'})
+    })
+  })
+
+  describe('archiveRelease', () => {
+    it('creates a release.archive action from a release handle', () => {
+      const action = archiveRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.archive', releaseId: 'my-release'})
+    })
+  })
+
+  describe('unarchiveRelease', () => {
+    it('creates a release.unarchive action from a release handle', () => {
+      const action = unarchiveRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.unarchive', releaseId: 'my-release'})
+    })
+  })
+
+  describe('deleteRelease', () => {
+    it('creates a release.delete action from a release handle', () => {
+      const action = deleteRelease(dummyReleaseHandle)
+      expect(action).toEqual({type: 'release.delete', releaseId: 'my-release'})
+    })
+  })
+})