@sanity/sdk-react 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -51,33 +51,34 @@
     "react-compiler-runtime": "19.1.0-rc.2",
     "react-error-boundary": "^5.0.0",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "2.3.0"
+    "@sanity/sdk": "2.4.0"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/comlink": "^3.0.4",
+    "@sanity/comlink": "^3.1.1",
     "@sanity/pkg-utils": "^7.2.2",
-    "@sanity/prettier-config": "^1.0.3",
-    "@testing-library/jest-dom": "^6.6.3",
+    "@sanity/prettier-config": "^1.0.6",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.0",
-    "@types/react": "^19.1.2",
-    "@types/react-dom": "^19.1.3",
-    "@vitejs/plugin-react": "^4.4.1",
-    "@vitest/coverage-v8": "3.1.2",
+    "@types/node": "^22.19.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/coverage-v8": "3.2.4",
     "babel-plugin-react-compiler": "19.1.0-rc.1",
     "eslint": "^9.22.0",
-    "groq-js": "^1.19.0",
+    "groq-js": "^1.22.0",
     "jsdom": "^25.0.1",
-    "prettier": "^3.5.3",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "prettier": "^3.7.3",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.4",
-    "vitest": "^3.1.2",
+    "vitest": "^3.2.4",
     "@repo/config-eslint": "0.0.0",
-    "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
     "@repo/tsconfig": "0.0.1"
   },

package/src/_exports/sdk-react.ts

@@ -6,6 +6,13 @@ export {SanityApp, type SanityAppProps} from '../components/SanityApp'
 export {SDKProvider, type SDKProviderProps} from '../components/SDKProvider'
 export {ComlinkTokenRefreshProvider} from '../context/ComlinkTokenRefresh'
 export {ResourceProvider, type ResourceProviderProps} from '../context/ResourceProvider'
+export {
+  useAgentGenerate,
+  useAgentPatch,
+  useAgentPrompt,
+  useAgentTransform,
+  useAgentTranslate,
+} from '../hooks/agent/agentActions'
 export {useAuthState} from '../hooks/auth/useAuthState'
 export {useAuthToken} from '../hooks/auth/useAuthToken'
 export {useCurrentUser} from '../hooks/auth/useCurrentUser'
@@ -29,6 +36,7 @@ export {
 } from '../hooks/comlink/useWindowConnection'
 export {useSanityInstance} from '../hooks/context/useSanityInstance'
 export {useDashboardNavigate} from '../hooks/dashboard/useDashboardNavigate'
+export {useDispatchIntent} from '../hooks/dashboard/useDispatchIntent'
 export {useManageFavorite} from '../hooks/dashboard/useManageFavorite'
 export {
   type NavigateToStudioResult,

package/src/components/auth/AuthBoundary.tsx

@@ -7,6 +7,7 @@ import {ComlinkTokenRefreshProvider} from '../../context/ComlinkTokenRefresh'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
+import {useSanityInstance} from '../../hooks/context/useSanityInstance'
 import {CorsErrorComponent} from '../errors/CorsErrorComponent'
 import {isInIframe} from '../utils'
 import {AuthError} from './AuthError'
@@ -154,17 +155,21 @@ function AuthSwitch({
   ...props
 }: AuthSwitchProps) {
   const authState = useAuthState()
-  const orgError = useVerifyOrgProjects(!verifyOrganization, projectIds)
+  const instance = useSanityInstance()
+  const studioModeEnabled = instance.config.studioMode?.enabled
+  const disableVerifyOrg =
+    !verifyOrganization || studioModeEnabled || authState.type !== AuthStateType.LOGGED_IN
+  const orgError = useVerifyOrgProjects(disableVerifyOrg, projectIds)
 
   const isLoggedOut = authState.type === AuthStateType.LOGGED_OUT && !authState.isDestroyingSession
   const loginUrl = useLoginUrl()
 
   useEffect(() => {
-    if (isLoggedOut && !isInIframe()) {
-      // We don't want to redirect to login if we're in the Dashboard
+    if (isLoggedOut && !isInIframe() && !studioModeEnabled) {
+      // We don't want to redirect to login if we're in the Dashboard nor in studio mode
       window.location.href = loginUrl
     }
-  }, [isLoggedOut, loginUrl])
+  }, [isLoggedOut, loginUrl, studioModeEnabled])
 
   // Only check the error if verification is enabled
   if (verifyOrganization && orgError) {

package/src/components/auth/LoginError.tsx

@@ -1,5 +1,10 @@
 import {ClientError} from '@sanity/client'
-import {AuthStateType} from '@sanity/sdk'
+import {
+  AuthStateType,
+  getClientErrorApiBody,
+  getClientErrorApiDescription,
+  isProjectUserNotFoundClientError,
+} from '@sanity/sdk'
 import {useCallback, useEffect, useState} from 'react'
 import {type FallbackProps} from 'react-error-boundary'
 
@@ -35,6 +40,7 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
   const [authErrorMessage, setAuthErrorMessage] = useState(
     'Please try again or contact support if the problem persists.',
   )
+  const [showRetryCta, setShowRetryCta] = useState(true)
 
   const handleRetry = useCallback(async () => {
     await logout()
@@ -44,18 +50,28 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
   useEffect(() => {
     if (error instanceof ClientError) {
       if (error.statusCode === 401) {
-        handleRetry()
+        // Surface a friendly message for projectUserNotFoundError (do not logout/refresh)
+        if (isProjectUserNotFoundClientError(error)) {
+          const description = getClientErrorApiDescription(error)
+          if (description) setAuthErrorMessage(description)
+          setShowRetryCta(false)
+        } else {
+          setShowRetryCta(true)
+          handleRetry()
+        }
       } else if (error.statusCode === 404) {
-        const errorMessage = error.response.body.message || ''
+        const errorMessage = getClientErrorApiBody(error)?.message || ''
         if (errorMessage.startsWith('Session with sid') && errorMessage.endsWith('not found')) {
           setAuthErrorMessage('The session ID is invalid or expired.')
         } else {
           setAuthErrorMessage('The login link is invalid or expired. Please try again.')
         }
+        setShowRetryCta(true)
       }
     }
     if (authState.type !== AuthStateType.ERROR && error instanceof ConfigurationError) {
       setAuthErrorMessage(error.message)
+      setShowRetryCta(true)
     }
   }, [authState, handleRetry, error])
 
@@ -63,10 +79,14 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
     <Error
       heading={error instanceof AuthError ? 'Authentication Error' : 'Configuration Error'}
       description={authErrorMessage}
-      cta={{
-        text: 'Retry',
-        onClick: handleRetry,
-      }}
+      cta={
+        showRetryCta
+          ? {
+              text: 'Retry',
+              onClick: handleRetry,
+            }
+          : undefined
+      }
     />
   )
 }

package/src/context/ComlinkTokenRefresh.test.tsx

@@ -89,7 +89,8 @@ describe('ComlinkTokenRefresh', () => {
         mockGetIsInDashboardState.mockReturnValue({getCurrent: () => true})
       })
 
-      it('should initialize useWindowConnection with correct parameters', () => {
+      it('should initialize useWindowConnection with correct parameters when not in studio mode', () => {
+        // Simulate studio mode disabled by default
         render(
           <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
@@ -106,13 +107,22 @@ describe('ComlinkTokenRefresh', () => {
         )
       })
 
-      it('should handle received token', async () => {
+      it('should handle received token when not in studio mode', async () => {
         mockUseAuthState.mockReturnValue({
           type: AuthStateType.ERROR,
           error: {statusCode: 401, message: 'Unauthorized'},
         })
         mockFetch.mockResolvedValueOnce({token: 'new-token'})
 
+        // Insert an Unauthorized error container that should be removed on success
+        const errorContainer = document.createElement('div')
+        errorContainer.id = '__sanityError'
+        const child = document.createElement('div')
+        child.textContent =
+          'Uncaught error: Unauthorized - A valid session is required for this endpoint'
+        errorContainer.appendChild(child)
+        document.body.appendChild(errorContainer)
+
         render(
           <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
             <ComlinkTokenRefreshProvider>
@@ -127,9 +137,17 @@ describe('ComlinkTokenRefresh', () => {
 
         expect(mockSetAuthToken).toHaveBeenCalledWith(expect.any(Object), 'new-token')
         expect(mockFetch).toHaveBeenCalledTimes(1)
+        expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/auth/tokens/create')
+        // Assert setAuthToken was called with instance matching provider config
+        const instanceArg = mockSetAuthToken.mock.calls[0][0]
+        expect(instanceArg.config).toEqual(
+          expect.objectContaining({projectId: 'test-project', dataset: 'test-dataset'}),
+        )
+        // Unauthorized error container should be removed
+        expect(document.getElementById('__sanityError')).toBeNull()
       })
 
-      it('should not set auth token if received token is null', async () => {
+      it('should not set auth token if received token is null when not in studio mode', async () => {
         mockUseAuthState.mockReturnValue({
           type: AuthStateType.ERROR,
           error: {statusCode: 401, message: 'Unauthorized'},
@@ -151,7 +169,7 @@ describe('ComlinkTokenRefresh', () => {
         expect(mockSetAuthToken).not.toHaveBeenCalled()
       })
 
-      it('should handle fetch errors gracefully', async () => {
+      it('should handle fetch errors gracefully when not in studio mode', async () => {
         mockUseAuthState.mockReturnValue({
           type: AuthStateType.ERROR,
           error: {statusCode: 401, message: 'Unauthorized'},
@@ -174,7 +192,7 @@ describe('ComlinkTokenRefresh', () => {
       })
 
       describe('Automatic token refresh', () => {
-        it('should not request new token for non-401 errors', async () => {
+        it('should not request new token for non-401 errors when not in studio mode', async () => {
           mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
           const {rerender} = render(
             <ResourceProvider fallback={null}>
@@ -205,7 +223,7 @@ describe('ComlinkTokenRefresh', () => {
           expect(mockFetch).not.toHaveBeenCalled()
         })
 
-        it('should request new token on LOGGED_OUT state', async () => {
+        it('should request new token on LOGGED_OUT state when not in studio mode', async () => {
           mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
           const {rerender} = render(
             <ResourceProvider fallback={null}>
@@ -228,6 +246,108 @@ describe('ComlinkTokenRefresh', () => {
 
           expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/auth/tokens/create')
         })
+
+        it('dedupes multiple 401 errors while a refresh is in progress', async () => {
+          mockUseAuthState.mockReturnValue({
+            type: AuthStateType.ERROR,
+            error: {statusCode: 401, message: 'Unauthorized'},
+          })
+          // Return a promise we resolve later to keep in-progress true for a bit
+          let resolveFetch: (v: {token: string | null}) => void
+          mockFetch.mockImplementation(
+            () =>
+              new Promise<{token: string | null}>((resolve) => {
+                resolveFetch = resolve
+              }),
+          )
+
+          const {rerender} = render(
+            <ResourceProvider fallback={null}>
+              <ComlinkTokenRefreshProvider>
+                <div>Test</div>
+              </ComlinkTokenRefreshProvider>
+            </ResourceProvider>,
+          )
+
+          // Trigger a second 401 while the first request is still in progress
+          mockUseAuthState.mockReturnValue({
+            type: AuthStateType.ERROR,
+            error: {statusCode: 401, message: 'Unauthorized again'},
+          })
+          act(() => {
+            rerender(
+              <ResourceProvider fallback={null}>
+                <ComlinkTokenRefreshProvider>
+                  <div>Test</div>
+                </ComlinkTokenRefreshProvider>
+              </ResourceProvider>,
+            )
+          })
+
+          // Only one fetch should be in-flight
+          expect(mockFetch).toHaveBeenCalledTimes(1)
+
+          // Finish the first fetch
+          await act(async () => {
+            resolveFetch!({token: null})
+          })
+        })
+
+        it('requests again after timeout if previous request did not resolve', async () => {
+          mockUseAuthState.mockReturnValue({
+            type: AuthStateType.ERROR,
+            error: {statusCode: 401, message: 'Unauthorized'},
+          })
+          // First call never resolves
+          mockFetch.mockImplementationOnce(() => new Promise(() => {}))
+
+          const {rerender} = render(
+            <ResourceProvider fallback={null}>
+              <ComlinkTokenRefreshProvider>
+                <div>Test</div>
+              </ComlinkTokenRefreshProvider>
+            </ResourceProvider>,
+          )
+
+          expect(mockFetch).toHaveBeenCalledTimes(1)
+
+          // After timeout elapses, a subsequent 401 should trigger another fetch
+          await act(async () => {
+            await vi.advanceTimersByTimeAsync(10000)
+          })
+
+          mockUseAuthState.mockReturnValue({
+            type: AuthStateType.ERROR,
+            error: {statusCode: 401, message: 'Unauthorized again'},
+          })
+          act(() => {
+            rerender(
+              <ResourceProvider fallback={null}>
+                <ComlinkTokenRefreshProvider>
+                  <div>Test</div>
+                </ComlinkTokenRefreshProvider>
+              </ResourceProvider>,
+            )
+          })
+
+          expect(mockFetch).toHaveBeenCalledTimes(2)
+        })
+
+        describe('when in studio mode', () => {
+          it('should not render DashboardTokenRefresh when studio mode enabled', () => {
+            render(
+              <ResourceProvider fallback={null} studioMode={{enabled: true}}>
+                <ComlinkTokenRefreshProvider>
+                  <div>Test</div>
+                </ComlinkTokenRefreshProvider>
+              </ResourceProvider>,
+            )
+
+            // In studio mode, provider should return children directly
+            // So window connection should not be initialized
+            expect(mockUseWindowConnection).not.toHaveBeenCalled()
+          })
+        })
       })
     })
   })

package/src/context/ComlinkTokenRefresh.tsx

@@ -130,8 +130,9 @@ function DashboardTokenRefresh({children}: PropsWithChildren) {
 export const ComlinkTokenRefreshProvider: React.FC<PropsWithChildren> = ({children}) => {
   const instance = useSanityInstance()
   const isInDashboard = useMemo(() => getIsInDashboardState(instance).getCurrent(), [instance])
+  const studioModeEnabled = !!instance.config.studioMode?.enabled
 
-  if (isInDashboard) {
+  if (isInDashboard && !studioModeEnabled) {
     return <DashboardTokenRefresh>{children}</DashboardTokenRefresh>
   }
 

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

@@ -0,0 +1,78 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {renderHook} from '@testing-library/react'
+import {of} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {
+  useAgentGenerate,
+  useAgentPatch,
+  useAgentPrompt,
+  useAgentTransform,
+  useAgentTranslate,
+} from './agentActions'
+
+vi.mock('@sanity/sdk', async (orig) => {
+  const actual = await orig()
+  return {
+    ...(actual as Record<string, any>),
+    agentGenerate: vi.fn(() => of('gen')),
+    agentTransform: vi.fn(() => of('xform')),
+    agentTranslate: vi.fn(() => of('xlate')),
+    agentPrompt: vi.fn(() => of('prompted')),
+    agentPatch: vi.fn(() => of('patched')),
+  }
+})
+
+describe('agent action hooks', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      {children}
+    </ResourceProvider>
+  )
+
+  it('useAgentGenerate returns a callable that delegates to core', async () => {
+    const {result} = renderHook(() => useAgentGenerate(), {wrapper})
+    const value = await new Promise<any>((resolve, reject) => {
+      result.current({} as any).subscribe({
+        next: (v) => resolve(v),
+        error: reject,
+      })
+    })
+    expect(value).toBe('gen')
+  })
+
+  it('useAgentTransform returns a callable that delegates to core', async () => {
+    const {result} = renderHook(() => useAgentTransform(), {wrapper})
+    const value = await new Promise<any>((resolve, reject) => {
+      result.current({} as any).subscribe({
+        next: (v) => resolve(v),
+        error: reject,
+      })
+    })
+    expect(value).toBe('xform')
+  })
+
+  it('useAgentTranslate returns a callable that delegates to core', async () => {
+    const {result} = renderHook(() => useAgentTranslate(), {wrapper})
+    const value = await new Promise<any>((resolve, reject) => {
+      result.current({} as any).subscribe({
+        next: (v) => resolve(v),
+        error: reject,
+      })
+    })
+    expect(value).toBe('xlate')
+  })
+
+  it('useAgentPrompt returns a callable that delegates to core', async () => {
+    const {result} = renderHook(() => useAgentPrompt(), {wrapper})
+    const value = await result.current({} as any)
+    expect(value).toBe('prompted')
+  })
+
+  it('useAgentPatch returns a callable that delegates to core', async () => {
+    const {result} = renderHook(() => useAgentPatch(), {wrapper})
+    const value = await result.current({} as any)
+    expect(value).toBe('patched')
+  })
+})

package/src/hooks/agent/agentActions.ts

@@ -0,0 +1,136 @@
+import {
+  agentGenerate,
+  type AgentGenerateOptions,
+  agentPatch,
+  type AgentPatchOptions,
+  type AgentPatchResult,
+  agentPrompt,
+  type AgentPromptOptions,
+  type AgentPromptResult,
+  agentTransform,
+  type AgentTransformOptions,
+  agentTranslate,
+  type AgentTranslateOptions,
+  type SanityInstance,
+} from '@sanity/sdk'
+import {firstValueFrom} from 'rxjs'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+interface Subscription {
+  unsubscribe(): void
+}
+
+interface Observer<T> {
+  next?: (value: T) => void
+  error?: (err: unknown) => void
+  complete?: () => void
+}
+
+interface Subscribable<T> {
+  subscribe(observer: Observer<T>): Subscription
+  subscribe(
+    next: (value: T) => void,
+    error?: (err: unknown) => void,
+    complete?: () => void,
+  ): Subscription
+}
+
+/**
+ * @alpha
+ * Generates content for a document (or specific fields) via Sanity Agent Actions.
+ * - Uses instruction templates with `$variables` and supports `instructionParams` (constants, fields, documents, GROQ queries).
+ * - Can target specific paths/fields; supports image generation when targeting image fields.
+ * - Supports optional `temperature`, `async`, `noWrite`, and `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export const useAgentGenerate: () => (options: AgentGenerateOptions) => Subscribable<unknown> =
+  createCallbackHook(agentGenerate) as unknown as () => (
+    options: AgentGenerateOptions,
+  ) => Subscribable<unknown>
+
+/**
+ * @alpha
+ * Transforms an existing document or selected fields using Sanity Agent Actions.
+ * - Accepts `instruction` and `instructionParams` (constants, fields, documents, GROQ queries).
+ * - Can write to the same or a different `targetDocument` (create/edit), and target specific paths.
+ * - Supports per-path image transform instructions and image description operations.
+ * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export const useAgentTransform: () => (options: AgentTransformOptions) => Subscribable<unknown> =
+  createCallbackHook(agentTransform) as unknown as () => (
+    options: AgentTransformOptions,
+  ) => Subscribable<unknown>
+
+/**
+ * @alpha
+ * Translates documents or fields using Sanity Agent Actions.
+ * - Configure `fromLanguage`/`toLanguage`, optional `styleGuide`, and `protectedPhrases`.
+ * - Can write into a different `targetDocument`, and/or store language in a field.
+ * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export const useAgentTranslate: () => (options: AgentTranslateOptions) => Subscribable<unknown> =
+  createCallbackHook(agentTranslate) as unknown as () => (
+    options: AgentTranslateOptions,
+  ) => Subscribable<unknown>
+
+/**
+ * @alpha
+ * Prompts the LLM using the same instruction template format as other actions.
+ * - `format`: 'string' or 'json' (instruction must contain the word "json" for JSON responses).
+ * - Optional `temperature`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the prompt result.
+ */
+function promptAdapter(
+  instance: SanityInstance,
+  options: AgentPromptOptions,
+): Promise<AgentPromptResult> {
+  return firstValueFrom(agentPrompt(instance, options))
+}
+
+/**
+ * @alpha
+ * Prompts the LLM using the same instruction template format as other actions.
+ * - `format`: 'string' or 'json' (instruction must contain the word "json" for JSON responses).
+ * - Optional `temperature`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the prompt result.
+ */
+export const useAgentPrompt: () => (options: AgentPromptOptions) => Promise<AgentPromptResult> =
+  createCallbackHook(promptAdapter)
+
+/**
+ * @alpha
+ * Schema-aware patching with Sanity Agent Actions.
+ * - Validates provided paths/values against the document schema and merges object values safely.
+ * - Prevents duplicate keys and supports array appends (including after a specific keyed item).
+ * - Accepts `documentId` or `targetDocument` (mutually exclusive).
+ * - Optional `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the patch result.
+ */
+function patchAdapter(
+  instance: SanityInstance,
+  options: AgentPatchOptions,
+): Promise<AgentPatchResult> {
+  return firstValueFrom(agentPatch(instance, options))
+}
+
+/**
+ * @alpha
+ * Schema-aware patching with Sanity Agent Actions.
+ * - Validates provided paths/values against the document schema and merges object values safely.
+ * - Prevents duplicate keys and supports array appends (including after a specific keyed item).
+ * - Accepts `documentId` or `targetDocument` (mutually exclusive).
+ * - Optional `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the patch result.
+ */
+export const useAgentPatch: () => (options: AgentPatchOptions) => Promise<AgentPatchResult> =
+  createCallbackHook(patchAdapter)

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,
 })