@sanity/sdk-react 2.4.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -18,7 +18,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/sanity-io/sdk.git"
+    "url": "git+https://github.com/sanity-io/sdk.git",
+    "directory": "packages/react"
   },
   "license": "MIT",
   "author": "Sanity <developers@sanity.io>",
@@ -43,7 +44,7 @@
   "prettier": "@sanity/prettier-config",
   "dependencies": {
     "@sanity/client": "^7.12.0",
-    "@sanity/message-protocol": "^0.12.0",
+    "@sanity/message-protocol": "^0.18.0",
     "@sanity/types": "^3.83.0",
     "@types/lodash-es": "^4.17.12",
     "groq": "3.88.1-typegen-experimental.0",
@@ -51,12 +52,12 @@
     "react-compiler-runtime": "19.1.0-rc.2",
     "react-error-boundary": "^5.0.0",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "2.4.0"
+    "@sanity/sdk": "2.5.0"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/comlink": "^3.1.1",
-    "@sanity/pkg-utils": "^7.2.2",
+    "@sanity/pkg-utils": "^8.1.29",
     "@sanity/prettier-config": "^1.0.6",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
@@ -77,17 +78,17 @@
     "vite": "^6.3.4",
     "vitest": "^3.2.4",
     "@repo/config-eslint": "0.0.0",
-    "@repo/package.bundle": "3.82.0",
     "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/tsconfig": "0.0.1",
+    "@repo/package.bundle": "3.82.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19"
   },
   "publishConfig": {
     "access": "public"

package/src/_exports/sdk-react.ts

@@ -13,6 +13,10 @@ export {
   useAgentTransform,
   useAgentTranslate,
 } from '../hooks/agent/agentActions'
+export {
+  type AgentResourceContextOptions,
+  useAgentResourceContext,
+} from '../hooks/agent/useAgentResourceContext'
 export {useAuthState} from '../hooks/auth/useAuthState'
 export {useAuthToken} from '../hooks/auth/useAuthToken'
 export {useCurrentUser} from '../hooks/auth/useCurrentUser'

package/src/hooks/agent/useAgentResourceContext.test.tsx

@@ -0,0 +1,245 @@
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {AppProviders} from '../../../test/test-utils'
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useAgentResourceContext} from './useAgentResourceContext'
+
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+describe('useAgentResourceContext', () => {
+  let mockSendMessage = vi.fn()
+
+  beforeEach(() => {
+    mockSendMessage = vi.fn()
+    vi.mocked(useWindowConnection).mockImplementation(() => {
+      return {
+        sendMessage: mockSendMessage,
+        fetch: vi.fn(),
+      }
+    })
+  })
+
+  it('should send context update on mount', () => {
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+  })
+
+  it('should send context update without documentId', () => {
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: undefined,
+    })
+  })
+
+  it('should send context update when context changes', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+
+    // Change documentId
+    rerender({documentId: 'doc-456'})
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+    expect(mockSendMessage).toHaveBeenLastCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-456',
+    })
+  })
+
+  it('should not send duplicate updates for the same context', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+
+    // Re-render with the same documentId
+    rerender({documentId: 'doc-123'})
+
+    // Should still only be called once
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+  })
+
+  it('should warn when projectId is missing', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: '',
+          dataset: 'production',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] projectId and dataset are required',
+      {projectId: '', dataset: 'production'},
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should warn when dataset is missing', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    renderHook(
+      () =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: '',
+          documentId: 'doc-123',
+        }),
+      {wrapper: AppProviders},
+    )
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] projectId and dataset are required',
+      {projectId: 'test-project', dataset: ''},
+    )
+    expect(mockSendMessage).not.toHaveBeenCalled()
+
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should handle errors when sending messages', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockSendMessage.mockImplementation(() => {
+      throw new Error('Failed to send message')
+    })
+
+    // Should not throw, but should log error
+    expect(() =>
+      renderHook(
+        () =>
+          useAgentResourceContext({
+            projectId: 'test-project',
+            dataset: 'production',
+            documentId: 'doc-123',
+          }),
+        {wrapper: AppProviders},
+      ),
+    ).not.toThrow()
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '[useAgentResourceContext] Failed to update context:',
+      expect.any(Error),
+    )
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should update context when switching between documents', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123'},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(1)
+
+    // Switch to document 456
+    rerender({documentId: 'doc-456'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+
+    // Switch to document 789
+    rerender({documentId: 'doc-789'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(3)
+
+    // Switch back to document 123
+    rerender({documentId: 'doc-123'})
+    expect(mockSendMessage).toHaveBeenCalledTimes(4)
+  })
+
+  it('should update context when document is cleared', () => {
+    const {rerender} = renderHook(
+      ({documentId}: {documentId: string | undefined}) =>
+        useAgentResourceContext({
+          projectId: 'test-project',
+          dataset: 'production',
+          documentId,
+        }),
+      {
+        wrapper: AppProviders,
+        initialProps: {documentId: 'doc-123' as string | undefined},
+      },
+    )
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: 'doc-123',
+    })
+
+    // Clear documentId
+    rerender({documentId: undefined})
+
+    expect(mockSendMessage).toHaveBeenCalledTimes(2)
+    expect(mockSendMessage).toHaveBeenLastCalledWith('dashboard/v1/events/agent/resource/update', {
+      projectId: 'test-project',
+      dataset: 'production',
+      documentId: undefined,
+    })
+  })
+})

package/src/hooks/agent/useAgentResourceContext.ts

@@ -0,0 +1,106 @@
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type FrameMessage} from '@sanity/sdk'
+import {useCallback, useEffect, useRef} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+
+/**
+ * @public
+ */
+export interface AgentResourceContextOptions {
+  /**
+   * The project ID of the current context
+   */
+  projectId: string
+  /**
+   * The dataset of the current context
+   */
+  dataset: string
+  /**
+   * Optional document ID if the user is viewing/editing a specific document
+   */
+  documentId?: string
+}
+
+/**
+ * @public
+ * Hook for emitting agent resource context updates to the Dashboard.
+ * This allows the Agent to understand what resource the user is currently
+ * interacting with (e.g., which document they're editing).
+ *
+ * The hook will automatically emit the context when it changes, and also
+ * emit the initial context when the hook is first mounted.
+ *
+ * @category Agent
+ * @param options - The resource context options containing projectId, dataset, and optional documentId
+ *
+ * @example
+ * ```tsx
+ * import {useAgentResourceContext} from '@sanity/sdk-react'
+ *
+ * function MyComponent() {
+ *   const documentId = 'my-document-id'
+ *
+ *   // Automatically updates the Agent's context whenever the document changes
+ *   useAgentResourceContext({
+ *     projectId: 'my-project',
+ *     dataset: 'production',
+ *     documentId,
+ *   })
+ *
+ *   return <div>Editing document: {documentId}</div>
+ * }
+ * ```
+ */
+export function useAgentResourceContext(options: AgentResourceContextOptions): void {
+  const {projectId, dataset, documentId} = options
+  const {sendMessage} = useWindowConnection<Events.AgentResourceUpdateMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  // Track the last sent context to avoid duplicate updates
+  const lastContextRef = useRef<string | null>(null)
+
+  const updateContext = useCallback(() => {
+    // Validate required fields
+    if (!projectId || !dataset) {
+      // eslint-disable-next-line no-console
+      console.warn('[useAgentResourceContext] projectId and dataset are required', {
+        projectId,
+        dataset,
+      })
+      return
+    }
+
+    // Create a stable key for the current context
+    const contextKey = `${projectId}:${dataset}:${documentId || ''}`
+
+    // Skip if context hasn't changed
+    if (lastContextRef.current === contextKey) {
+      return
+    }
+
+    try {
+      const message: Events.AgentResourceUpdateMessage = {
+        type: 'dashboard/v1/events/agent/resource/update',
+        data: {
+          projectId,
+          dataset,
+          documentId,
+        },
+      }
+
+      sendMessage(message.type, message.data)
+      lastContextRef.current = contextKey
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[useAgentResourceContext] Failed to update context:', error)
+    }
+  }, [projectId, dataset, documentId, sendMessage])
+
+  // Update context whenever it changes
+  useEffect(() => {
+    updateContext()
+  }, [updateContext])
+}

package/src/hooks/dashboard/useDispatchIntent.test.ts

@@ -38,10 +38,7 @@ describe('useDispatchIntent', () => {
   })
 
   it('should throw error when neither action nor intentId is provided', () => {
-    const {result} = renderHook(() =>
-      // @ts-expect-error - Testing runtime error when neither is provided
-      useDispatchIntent({documentHandle: mockDocumentHandle}),
-    )
+    const {result} = renderHook(() => useDispatchIntent({documentHandle: mockDocumentHandle}))
 
     expect(() => result.current.dispatchIntent()).toThrow(
       'useDispatchIntent: Either `action` or `intentId` must be provided.',

package/src/hooks/document/useApplyDocumentActions.test.ts

@@ -1,20 +1,135 @@
-import {applyDocumentActions} from '@sanity/sdk'
+import {applyDocumentActions, type SanityInstance} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
-import {createCallbackHook} from '../helpers/createCallbackHook'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useApplyDocumentActions} from './useApplyDocumentActions'
 
-vi.mock('../helpers/createCallbackHook', () => ({
-  createCallbackHook: vi.fn((cb) => () => cb),
-}))
 vi.mock('@sanity/sdk', async (importOriginal) => {
   const original = await importOriginal<typeof import('@sanity/sdk')>()
   return {...original, applyDocumentActions: vi.fn()}
 })
 
+vi.mock('../context/useSanityInstance')
+
+// These are quite fragile mocks, but they are useful enough for now.
+const instances: Record<string, SanityInstance | undefined> = {
+  'p123.d': {__id: 'p123.d'} as unknown as SanityInstance,
+  'p.d123': {__id: 'p.d123'} as unknown as SanityInstance,
+  'p123.d123': {__id: 'p123.d123'} as unknown as SanityInstance,
+}
+
+const instance = {
+  match({projectId = 'p', dataset = 'd'}): SanityInstance | undefined {
+    return instances[`${projectId}.${dataset}`]
+  },
+} as unknown as SanityInstance
+
 describe('useApplyDocumentActions', () => {
-  it('calls `createCallbackHook` with `applyActions`', async () => {
-    expect(createCallbackHook).not.toHaveBeenCalled()
-    await import('./useApplyDocumentActions')
-    expect(createCallbackHook).toHaveBeenCalledWith(applyDocumentActions)
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValueOnce(instance)
+  })
+
+  it('uses the SanityInstance', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance.match when projectId is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      projectId: 'p123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instances['p123.d'], {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          projectId: 'p123',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance when dataset is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      dataset: 'd123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instance, {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          dataset: 'd123',
+        },
+      ],
+    })
+  })
+
+  it('uses SanityInstance.amcth when projectId and dataset is overrideen', async () => {
+    const apply = useApplyDocumentActions()
+    apply({
+      type: 'document.edit',
+      documentType: 'post',
+      documentId: 'abc',
+
+      projectId: 'p123',
+      dataset: 'd123',
+    })
+
+    expect(applyDocumentActions).toHaveBeenCalledExactlyOnceWith(instances['p123.d123'], {
+      actions: [
+        {
+          type: 'document.edit',
+          documentType: 'post',
+          documentId: 'abc',
+
+          projectId: 'p123',
+          dataset: 'd123',
+        },
+      ],
+    })
+  })
+
+  it("throws if SanityInstance.match doesn't find anything", async () => {
+    const apply = useApplyDocumentActions()
+    expect(() => {
+      apply({
+        type: 'document.edit',
+        documentType: 'post',
+        documentId: 'abc',
+
+        projectId: 'other',
+      })
+    }).toThrow()
   })
 })

package/src/hooks/document/useApplyDocumentActions.ts

@@ -6,7 +6,7 @@ import {
 } from '@sanity/sdk'
 import {type SanityDocument} from 'groq'
 
-import {createCallbackHook} from '../helpers/createCallbackHook'
+import {useSanityInstance} from '../context/useSanityInstance'
 // this import is used in an `{@link useEditDocument}`
 // eslint-disable-next-line unused-imports/no-unused-imports, import/consistent-type-specifier-style
 import type {useEditDocument} from './useEditDocument'
@@ -150,6 +150,46 @@ interface UseApplyDocumentActions {
  * }
  * ```
  */
-export const useApplyDocumentActions = createCallbackHook(
-  applyDocumentActions,
-) as UseApplyDocumentActions
+export const useApplyDocumentActions: UseApplyDocumentActions = () => {
+  const instance = useSanityInstance()
+
+  return (actionOrActions, options) => {
+    const actions = Array.isArray(actionOrActions) ? actionOrActions : [actionOrActions]
+
+    let projectId
+    let dataset
+    for (const action of actions) {
+      if (action.projectId) {
+        if (!projectId) projectId = action.projectId
+        if (action.projectId !== projectId) {
+          throw new Error(
+            `Mismatched project IDs found in actions. All actions must belong to the same project. Found "${action.projectId}" but expected "${projectId}".`,
+          )
+        }
+
+        if (action.dataset) {
+          if (!dataset) dataset = action.dataset
+          if (action.dataset !== dataset) {
+            throw new Error(
+              `Mismatched datasets found in actions. All actions must belong to the same dataset. Found "${action.dataset}" but expected "${dataset}".`,
+            )
+          }
+        }
+      }
+    }
+
+    if (projectId || dataset) {
+      const actualInstance = instance.match({projectId, dataset})
+      if (!actualInstance) {
+        throw new Error(
+          `Could not find a matching Sanity instance for the requested action: ${JSON.stringify({projectId, dataset}, null, 2)}.
+  Please ensure there is a ResourceProvider component with a matching configuration in the component hierarchy.`,
+        )
+      }
+
+      return applyDocumentActions(actualInstance, {actions, ...options})
+    }
+
+    return applyDocumentActions(instance, {actions, ...options})
+  }
+}

package/src/hooks/document/useDocumentPermissions.test.tsx

@@ -97,7 +97,7 @@ describe('usePermissions', () => {
     })
 
     // ResourceProvider handles the instance configuration
-    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), mockAction)
+    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions: [mockAction]})
     expect(result.current).toEqual(mockPermissionAllowed)
   })
 
@@ -140,7 +140,7 @@ describe('usePermissions', () => {
       ),
     })
 
-    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), actions)
+    expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions})
   })
 
   it('should throw an error if actions have mismatched project IDs', () => {
@@ -226,7 +226,7 @@ describe('usePermissions', () => {
 
     // Now it should render properly
     await waitFor(() => {
-      expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), mockAction)
+      expect(getPermissionsState).toHaveBeenCalledWith(expect.any(Object), {actions: [mockAction]})
     })
   })