@sanity/sdk 2.8.0 → 3.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.8.0",
+  "version": "3.0.0-rc.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -49,11 +49,11 @@
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
     "@sanity/id-utils": "^1.0.0",
+    "@sanity/image-url": "^2.0.3",
     "@sanity/json-match": "^1.0.5",
     "@sanity/message-protocol": "^0.18.0",
     "@sanity/mutate": "^0.12.4",
     "@sanity/types": "^5.2.0",
-    "groq": "3.88.1-typegen-experimental.0",
     "groq-js": "^1.19.0",
     "lodash-es": "^4.17.21",
     "reselect": "^5.1.1",
@@ -75,8 +75,8 @@
     "@repo/config-eslint": "0.0.0",
     "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
-    "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/tsconfig": "0.0.1",
+    "@repo/package.config": "0.0.1"
   },
   "engines": {
     "node": ">=20.19"

package/src/_exports/index.ts

@@ -12,6 +12,7 @@ export type {
   AgentPatchResult,
   AgentPromptOptions,
   AgentPromptResult,
+  AgentResourceOptions,
   AgentTransformOptions,
   AgentTransformResult,
   AgentTranslateOptions,
@@ -71,10 +72,9 @@ export {
 } from '../comlink/types'
 export {type AuthConfig, type AuthProvider} from '../config/authConfig'
 export {
-  createDatasetHandle,
   createDocumentHandle,
   createDocumentTypeHandle,
-  createProjectHandle,
+  createResourceHandle,
 } from '../config/handles'
 export {
   configureLogging,
@@ -86,19 +86,19 @@ export {
   type LogNamespace,
 } from '../config/loggingConfig'
 export {
-  type CanvasSource,
-  type DatasetHandle,
-  type DatasetSource,
+  type CanvasResource,
+  type DatasetResource,
+  DEFAULT_RESOURCE_NAME,
   type DocumentHandle,
-  type DocumentSource,
+  type DocumentResource,
   type DocumentTypeHandle,
-  isCanvasSource,
-  isDatasetSource,
-  isMediaLibrarySource,
-  type MediaLibrarySource,
+  isCanvasResource,
+  isDatasetResource,
+  isMediaLibraryResource,
+  type MediaLibraryResource,
   type PerspectiveHandle,
-  type ProjectHandle,
   type ReleasePerspective,
+  type ResourceHandle,
   type SanityConfig,
   type StudioConfig,
   type TokenSource,
@@ -145,7 +145,6 @@ export {
   type TransactionAcceptedEvent,
   type TransactionRevertedEvent,
 } from '../document/events'
-export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'
 export type {FavoriteStatusResponse} from '../favorites/favorites'
 export {getFavoritesState, resolveFavoritesState} from '../favorites/favorites'
@@ -158,14 +157,14 @@ export type {
   TransportEvent,
   UserPresence,
 } from '../presence/types'
-export {getPreviewState, type GetPreviewStateOptions} from '../preview/getPreviewState'
-export type {PreviewStoreState, PreviewValue, ValuePending} from '../preview/previewStore'
-export {resolvePreview, type ResolvePreviewOptions} from '../preview/resolvePreview'
+export {PREVIEW_PROJECTION} from '../preview/previewConstants'
+export {transformProjectionToPreview} from '../preview/previewProjectionUtils'
+export type {PreviewMedia, PreviewQueryResult, PreviewValue, ValuePending} from '../preview/types'
 export {type OrgVerificationResult} from '../project/organizationVerification'
-export {getProjectState, resolveProject} from '../project/project'
+export {getProjectState, type ProjectHandle, resolveProject} from '../project/project'
 export {getProjectionState} from '../projection/getProjectionState'
 export {resolveProjection} from '../projection/resolveProjection'
-export {type ProjectionValuePending, type ValidProjection} from '../projection/types'
+export {type ProjectionValuePending} from '../projection/types'
 export {getProjectsState, resolveProjects} from '../projects/projects'
 export {
   getQueryKey,

package/src/agent/agentActions.test.ts

@@ -11,13 +11,16 @@ import {
 } from './agentActions'
 
 let mockClient: any
+const mockGetClientState = vi.fn()
 
 vi.mock('../client/clientStore', () => {
   return {
-    getClientState: () => ({observable: of(mockClient)}),
+    getClientState: (...args: unknown[]) => mockGetClientState(...args),
   }
 })
 
+const testResource = {projectId: 'p', dataset: 'd'}
+
 describe('agent actions', () => {
   beforeEach(() => {
     mockClient = {
@@ -37,45 +40,86 @@ describe('agent actions', () => {
         },
       },
     }
+    mockGetClientState.mockReturnValue({observable: of(mockClient)})
   })
 
-  it('agentGenerate returns observable from client', async () => {
+  it('agentGenerate passes resource to getClientState and strips it from agent options', async () => {
     mockClient.observable.agent.action.generate.mockReturnValue(of('gen'))
-    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
-    const value = await firstValueFrom(agentGenerate(instance, {foo: 'bar'} as any))
+    const instance = {config: {}} as any
+    const value = await firstValueFrom(
+      agentGenerate(instance, {foo: 'bar', resource: testResource} as any),
+    )
     expect(value).toBe('gen')
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: testResource,
+    })
     expect(mockClient.observable.agent.action.generate).toHaveBeenCalledWith({foo: 'bar'})
   })
 
-  it('agentTransform returns observable from client', async () => {
+  it('agentTransform passes resource to getClientState and strips it from agent options', async () => {
     mockClient.observable.agent.action.transform.mockReturnValue(of('xform'))
-    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
-    const value = await firstValueFrom(agentTransform(instance, {a: 1} as any))
+    const instance = {config: {}} as any
+    const value = await firstValueFrom(
+      agentTransform(instance, {a: 1, resource: testResource} as any),
+    )
     expect(value).toBe('xform')
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: testResource,
+    })
     expect(mockClient.observable.agent.action.transform).toHaveBeenCalledWith({a: 1})
   })
 
-  it('agentTranslate returns observable from client', async () => {
+  it('agentTranslate passes resource to getClientState and strips it from agent options', async () => {
     mockClient.observable.agent.action.translate.mockReturnValue(of('xlate'))
-    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
-    const value = await firstValueFrom(agentTranslate(instance, {b: 2} as any))
+    const instance = {config: {}} as any
+    const value = await firstValueFrom(
+      agentTranslate(instance, {b: 2, resource: testResource} as any),
+    )
     expect(value).toBe('xlate')
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: testResource,
+    })
     expect(mockClient.observable.agent.action.translate).toHaveBeenCalledWith({b: 2})
   })
 
-  it('agentPrompt wraps promise into observable', async () => {
+  it('agentPrompt passes resource to getClientState and strips it from agent options', async () => {
     mockClient.agent.action.prompt.mockResolvedValue('prompted')
-    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
-    const value = await firstValueFrom(agentPrompt(instance, {p: true} as any))
+    const instance = {config: {}} as any
+    const value = await firstValueFrom(
+      agentPrompt(instance, {p: true, resource: testResource} as any),
+    )
     expect(value).toBe('prompted')
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: testResource,
+    })
     expect(mockClient.agent.action.prompt).toHaveBeenCalledWith({p: true})
   })
 
-  it('agentPatch wraps promise into observable', async () => {
+  it('agentPatch passes resource to getClientState and strips it from agent options', async () => {
     mockClient.agent.action.patch.mockResolvedValue('patched')
-    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
-    const value = await firstValueFrom(agentPatch(instance, {q: false} as any))
+    const instance = {config: {}} as any
+    const value = await firstValueFrom(
+      agentPatch(instance, {q: false, resource: testResource} as any),
+    )
     expect(value).toBe('patched')
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: testResource,
+    })
     expect(mockClient.agent.action.patch).toHaveBeenCalledWith({q: false})
   })
+
+  it('works without an explicit resource (falls back via getClientState)', async () => {
+    mockClient.observable.agent.action.generate.mockReturnValue(of('gen'))
+    const instance = {config: {}} as any
+    await firstValueFrom(agentGenerate(instance, {foo: 'bar'} as any))
+    expect(mockGetClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      resource: undefined,
+    })
+  })
 })

package/src/agent/agentActions.ts

@@ -2,10 +2,19 @@ import {type SanityClient} from '@sanity/client'
 import {from, Observable, switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
+import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
 
 const API_VERSION = 'vX'
 
+/**
+ * Options that all agent actions accept for targeting a specific resource.
+ * @alpha
+ */
+export interface AgentResourceOptions {
+  resource: DocumentResource
+}
+
 /** @alpha */
 export type AgentGenerateOptions = Parameters<
   SanityClient['observable']['agent']['action']['generate']
@@ -57,13 +66,13 @@ export type AgentPatchResult = Awaited<ReturnType<SanityClient['agent']['action'
  */
 export function agentGenerate(
   instance: SanityInstance,
-  options: AgentGenerateOptions,
+  options: AgentGenerateOptions & AgentResourceOptions,
 ): AgentGenerateResult {
+  const {resource, ...agentOptions} = options
   return getClientState(instance, {
     apiVersion: API_VERSION,
-    projectId: instance.config.projectId,
-    dataset: instance.config.dataset,
-  }).observable.pipe(switchMap((client) => client.observable.agent.action.generate(options)))
+    resource,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.generate(agentOptions)))
 }
 
 /**
@@ -75,13 +84,13 @@ export function agentGenerate(
  */
 export function agentTransform(
   instance: SanityInstance,
-  options: AgentTransformOptions,
+  options: AgentTransformOptions & AgentResourceOptions,
 ): AgentTransformResult {
+  const {resource, ...agentOptions} = options
   return getClientState(instance, {
     apiVersion: API_VERSION,
-    projectId: instance.config.projectId,
-    dataset: instance.config.dataset,
-  }).observable.pipe(switchMap((client) => client.observable.agent.action.transform(options)))
+    resource,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.transform(agentOptions)))
 }
 
 /**
@@ -93,13 +102,13 @@ export function agentTransform(
  */
 export function agentTranslate(
   instance: SanityInstance,
-  options: AgentTranslateOptions,
+  options: AgentTranslateOptions & AgentResourceOptions,
 ): AgentTranslateResult {
+  const {resource, ...agentOptions} = options
   return getClientState(instance, {
     apiVersion: API_VERSION,
-    projectId: instance.config.projectId,
-    dataset: instance.config.dataset,
-  }).observable.pipe(switchMap((client) => client.observable.agent.action.translate(options)))
+    resource,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.translate(agentOptions)))
 }
 
 /**
@@ -111,13 +120,13 @@ export function agentTranslate(
  */
 export function agentPrompt(
   instance: SanityInstance,
-  options: AgentPromptOptions,
+  options: AgentPromptOptions & AgentResourceOptions,
 ): Observable<AgentPromptResult> {
+  const {resource, ...agentOptions} = options
   return getClientState(instance, {
     apiVersion: API_VERSION,
-    projectId: instance.config.projectId,
-    dataset: instance.config.dataset,
-  }).observable.pipe(switchMap((client) => from(client.agent.action.prompt(options))))
+    resource,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.prompt(agentOptions))))
 }
 
 /**
@@ -129,11 +138,11 @@ export function agentPrompt(
  */
 export function agentPatch(
   instance: SanityInstance,
-  options: AgentPatchOptions,
+  options: AgentPatchOptions & AgentResourceOptions,
 ): Observable<AgentPatchResult> {
+  const {resource, ...agentOptions} = options
   return getClientState(instance, {
     apiVersion: API_VERSION,
-    projectId: instance.config.projectId,
-    dataset: instance.config.dataset,
-  }).observable.pipe(switchMap((client) => from(client.agent.action.patch(options))))
+    resource,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.patch(agentOptions))))
 }

package/src/auth/authMode.test.ts

@@ -9,11 +9,6 @@ describe('resolveAuthMode', () => {
     expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
   })
 
-  it('returns "studio" when deprecated studioMode.enabled is true', () => {
-    const config: SanityConfig = {studioMode: {enabled: true}}
-    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
-  })
-
   it('returns "dashboard" when _context URL param has a non-empty JSON object', () => {
     const context = encodeURIComponent(JSON.stringify({orgId: '123'}))
     const href = `https://example.com?_context=${context}`
@@ -23,14 +18,6 @@ describe('resolveAuthMode', () => {
   it('returns "standalone" by default', () => {
     expect(resolveAuthMode({}, 'https://example.com')).toBe('standalone')
   })
-
-  it('prefers studio config over studioMode', () => {
-    const config: SanityConfig = {
-      studio: {},
-      studioMode: {enabled: true},
-    }
-    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
-  })
 })
 
 describe('isStudioConfig', () => {
@@ -38,19 +25,7 @@ describe('isStudioConfig', () => {
     expect(isStudioConfig({studio: {}})).toBe(true)
   })
 
-  it('returns true when deprecated studioMode.enabled is true', () => {
-    expect(isStudioConfig({studioMode: {enabled: true}})).toBe(true)
-  })
-
-  it('returns false when studioMode.enabled is false', () => {
-    expect(isStudioConfig({studioMode: {enabled: false}})).toBe(false)
-  })
-
   it('returns false for empty config', () => {
     expect(isStudioConfig({})).toBe(false)
   })
-
-  it('returns true when both studio and studioMode are present', () => {
-    expect(isStudioConfig({studio: {}, studioMode: {enabled: true}})).toBe(true)
-  })
 })

package/src/auth/authMode.ts

@@ -20,9 +20,8 @@ type AuthMode = 'studio' | 'dashboard' | 'standalone'
  *
  * Priority:
  * 1. `studio` config provided → `'studio'`
- * 2. `studioMode.enabled` in config (deprecated) → `'studio'`
- * 3. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
- * 4. Otherwise → `'standalone'`
+ * 2. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
+ * 3. Otherwise → `'standalone'`
  *
  * @internal
  */
@@ -34,13 +33,11 @@ export function resolveAuthMode(config: SanityConfig, locationHref: string): Aut
 
 /**
  * Returns `true` when the config indicates the SDK is running inside a Studio.
- * Checks the new `studio` field first, then falls back to the deprecated
- * `studioMode.enabled` for backwards compatibility.
  *
  * @internal
  */
 export function isStudioConfig(config: SanityConfig): boolean {
-  return !!config.studio || !!config.studioMode?.enabled
+  return !!config.studio
 }
 
 /**