@sanity/sdk-react 2.3.1 → 2.5.0

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/client/useClient.test.tsx

@@ -0,0 +1,42 @@
+import {renderHook} from '@testing-library/react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useClient} from './useClient'
+
+describe('useClient', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
+  it('should throw a helpful error when called without options', () => {
+    // Suppress console.error for this test since we expect an error to be thrown
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      // @ts-expect-error Testing missing options
+      renderHook(() => useClient(), {wrapper})
+    }).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should throw a helpful error when called with undefined', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      // @ts-expect-error Testing undefined options
+      renderHook(() => useClient(undefined), {wrapper})
+    }).toThrowError(/requires a configuration object with at least an "apiVersion" property/)
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should return a client when called with valid options', () => {
+    const {result} = renderHook(() => useClient({apiVersion: '2024-11-12'}), {wrapper})
+    expect(result.current).toBeDefined()
+    expect(result.current.fetch).toBeDefined()
+  })
+})

package/src/hooks/client/useClient.ts

@@ -1,5 +1,4 @@
-import {getClientState} from '@sanity/sdk'
-import {identity} from 'rxjs'
+import {type ClientOptions, getClientState, type SanityInstance} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
@@ -31,6 +30,14 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * @function
  */
 export const useClient = createStateSourceHook({
-  getState: getClientState,
-  getConfig: identity,
+  getState: (instance: SanityInstance, options: ClientOptions) => {
+    if (!options || typeof options !== 'object') {
+      throw new Error(
+        'useClient() requires a configuration object with at least an "apiVersion" property. ' +
+          'Example: useClient({ apiVersion: "2024-11-12" })',
+      )
+    }
+    return getClientState(instance, options)
+  },
+  getConfig: (options: ClientOptions) => options,
 })

package/src/hooks/dashboard/types.ts

@@ -0,0 +1,12 @@
+import {type DocumentHandle, type DocumentSource} from '@sanity/sdk'
+/**
+ * Document handle that optionally includes a source (e.g., media library source)
+ * or projectId and dataset for traditional dataset sources
+ * (but now marked optional since it's valid to just use a source)
+ * @beta
+ */
+export interface DocumentHandleWithSource extends Omit<DocumentHandle, 'projectId' | 'dataset'> {
+  source?: DocumentSource
+  projectId?: string
+  dataset?: string
+}

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

@@ -0,0 +1,239 @@
+import {canvasSource, type DocumentHandle, mediaLibrarySource} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {type DocumentHandleWithSource} from './types'
+import {useDispatchIntent} from './useDispatchIntent'
+
+// Mock the useWindowConnection hook
+const mockSendMessage = vi.fn()
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(() => ({
+    sendMessage: mockSendMessage,
+  })),
+}))
+
+describe('useDispatchIntent', () => {
+  const mockDocumentHandle: DocumentHandle = {
+    documentId: 'test-document-id',
+    documentType: 'test-document-type',
+    projectId: 'test-project-id',
+    dataset: 'test-dataset',
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Reset mock implementation to default behavior
+    mockSendMessage.mockImplementation(() => {})
+  })
+
+  it('should return dispatchIntent function', () => {
+    const {result} = renderHook(() =>
+      useDispatchIntent({action: 'edit', documentHandle: mockDocumentHandle}),
+    )
+
+    expect(result.current).toEqual({
+      dispatchIntent: expect.any(Function),
+    })
+  })
+
+  it('should throw error when neither action nor intentId is provided', () => {
+    const {result} = renderHook(() => useDispatchIntent({documentHandle: mockDocumentHandle}))
+
+    expect(() => result.current.dispatchIntent()).toThrow(
+      'useDispatchIntent: Either `action` or `intentId` must be provided.',
+    )
+  })
+
+  it('should handle errors gracefully', () => {
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockSendMessage.mockImplementation(() => {
+      throw new Error('Test error')
+    })
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({action: 'edit', documentHandle: mockDocumentHandle}),
+    )
+
+    expect(() => result.current.dispatchIntent()).toThrow('Test error')
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to dispatch intent:', expect.any(Error))
+
+    consoleErrorSpy.mockRestore()
+  })
+
+  it('should use memoized dispatchIntent function', () => {
+    const {result, rerender} = renderHook(({params}) => useDispatchIntent(params), {
+      initialProps: {params: {action: 'edit' as const, documentHandle: mockDocumentHandle}},
+    })
+
+    const firstDispatchIntent = result.current.dispatchIntent
+
+    // Rerender with the same params
+    rerender({params: {action: 'edit' as const, documentHandle: mockDocumentHandle}})
+
+    expect(result.current.dispatchIntent).toBe(firstDispatchIntent)
+  })
+
+  it('should create new dispatchIntent function when documentHandle changes', () => {
+    const {result, rerender} = renderHook(({params}) => useDispatchIntent(params), {
+      initialProps: {params: {action: 'edit' as const, documentHandle: mockDocumentHandle}},
+    })
+
+    const firstDispatchIntent = result.current.dispatchIntent
+
+    const newDocumentHandle: DocumentHandle = {
+      documentId: 'new-document-id',
+      documentType: 'new-document-type',
+      projectId: 'new-project-id',
+      dataset: 'new-dataset',
+    }
+
+    rerender({params: {action: 'edit' as const, documentHandle: newDocumentHandle}})
+
+    expect(result.current.dispatchIntent).not.toBe(firstDispatchIntent)
+  })
+
+  it('should warn if both action and intentId are provided', () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit' as const,
+        intentId: 'custom-intent' as never, // test runtime error when both are provided
+        documentHandle: mockDocumentHandle,
+      }),
+    )
+    result.current.dispatchIntent()
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'useDispatchIntent: Both `action` and `intentId` were provided. Using `intentId` and ignoring `action`.',
+    )
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('should send intent message with action and params when both are provided', () => {
+    const intentParams = {view: 'editor', tab: 'content'}
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockDocumentHandle,
+        parameters: intentParams,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-document-id',
+        type: 'test-document-type',
+      },
+      resource: {
+        id: 'test-project-id.test-dataset',
+      },
+      parameters: intentParams,
+    })
+  })
+
+  it('should send intent message with intentId and params when both are provided', () => {
+    const intentParams = {view: 'editor', tab: 'content'}
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        intentId: 'custom-intent',
+        documentHandle: mockDocumentHandle,
+        parameters: intentParams,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      intentId: 'custom-intent',
+      document: {
+        id: 'test-document-id',
+        type: 'test-document-type',
+      },
+      resource: {
+        id: 'test-project-id.test-dataset',
+      },
+      parameters: intentParams,
+    })
+  })
+
+  it('should send intent message with media library source', () => {
+    const mockMediaLibraryHandle: DocumentHandleWithSource = {
+      documentId: 'test-asset-id',
+      documentType: 'sanity.asset',
+      source: mediaLibrarySource('mlPGY7BEqt52'),
+    }
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockMediaLibraryHandle,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-asset-id',
+        type: 'sanity.asset',
+      },
+      resource: {
+        id: 'mlPGY7BEqt52',
+        type: 'media-library',
+      },
+    })
+  })
+
+  it('should send intent message with canvas source', () => {
+    const mockCanvasHandle: DocumentHandleWithSource = {
+      documentId: 'test-canvas-document-id',
+      documentType: 'sanity.canvas.document',
+      source: canvasSource('canvas123'),
+    }
+
+    const {result} = renderHook(() =>
+      useDispatchIntent({
+        action: 'edit',
+        documentHandle: mockCanvasHandle,
+      }),
+    )
+
+    result.current.dispatchIntent()
+
+    expect(mockSendMessage).toHaveBeenCalledWith('dashboard/v1/events/intents/dispatch-intent', {
+      action: 'edit',
+      document: {
+        id: 'test-canvas-document-id',
+        type: 'sanity.canvas.document',
+      },
+      resource: {
+        id: 'canvas123',
+        type: 'canvas',
+      },
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw error when neither source nor projectId/dataset is provided', () => {
+      const invalidHandle = {
+        documentId: 'test-document-id',
+        documentType: 'test-document-type',
+      }
+
+      const {result} = renderHook(() =>
+        useDispatchIntent({
+          action: 'edit',
+          documentHandle: invalidHandle as unknown as DocumentHandleWithSource,
+        }),
+      )
+
+      expect(() => result.current.dispatchIntent()).toThrow(
+        'useDispatchIntent: Either `source` or both `projectId` and `dataset` must be provided in documentHandle.',
+      )
+    })
+  })
+})