@sanity/sdk-react 3.12.0 → 3.13.0-app-functions.20261106191857

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "3.12.0",
+  "version": "3.13.0-app-functions.20261106191857",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -43,10 +43,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@module-federation/runtime": "^2.9.2",
+    "@module-federation/runtime": "^2.9.3",
     "@sanity/client": "^8.14.1",
     "@sanity/message-protocol": "^0.24.0",
-    "@sanity/sdk": "3.12.0",
+    "@sanity/sdk": "3.13.0-app-functions.20261106191857",
     "@sanity/types": "^6.21.0",
     "react-compiler-runtime": "^1.0.0",
     "react-error-boundary": "^6.1.6",
@@ -66,10 +66,10 @@
     "@types/node": "^24.19.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^6.1.2",
-    "@vitest/coverage-v8": "^5.0.5",
+    "@vitejs/plugin-react": "^6.2.1",
+    "@vitest/coverage-v8": "^5.1.0",
     "babel-plugin-react-compiler": "^1.0.0",
-    "groq": "^6.21.0",
+    "groq": "^6.22.0",
     "groq-js": "^2.0.1",
     "jsdom": "^30.1.3",
     "oxfmt": "^0.75.0",
@@ -78,8 +78,8 @@
     "react-dom": "^19.3.1",
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vite": "^8.3.5",
-    "vitest": "^5.0.5",
+    "vite": "^8.3.6",
+    "vitest": "^5.1.0",
     "xstate": "5.33.3"
   },
   "peerDependencies": {

package/src/_exports/sdk-react.ts

@@ -5,6 +5,11 @@ export {AuthBoundary, type AuthBoundaryProps} from '../components/auth/AuthBound
 export {SanityApp, type SanityAppProps} from '../components/SanityApp'
 export {SDKProvider, type SDKProviderProps} from '../components/SDKProvider'
 export {type DocumentHandle, type DocumentTypeHandle, type ResourceHandle} from '../config/handles'
+export {
+  type AppFunctionsConfig,
+  AppFunctionsProvider,
+  type AppFunctionsProviderProps,
+} from '../context/AppFunctionsProvider'
 export {ComlinkTokenRefreshProvider} from '../context/ComlinkTokenRefresh'
 export {renderSanityApp} from '../context/renderSanityApp'
 export {ResourceProvider, type ResourceProviderProps} from '../context/ResourceProvider'
@@ -73,6 +78,7 @@ export {
   type DocumentsResponse,
   useDocuments,
 } from '../hooks/documents/useDocuments'
+export {useFunctions} from '../hooks/functions/useFunctions'
 export {type FetcherHookResult} from '../hooks/helpers/createFetcherHook'
 export {type MutationHookResult} from '../hooks/helpers/createMutationHook'
 export {useInstallation} from '../hooks/installations/useInstallation'

package/src/components/SDKProvider.reporting.test.tsx

@@ -0,0 +1,69 @@
+import {reportError} from '@sanity/sdk/_internal'
+import {render, screen} from '@testing-library/react'
+import {Component, type ReactNode} from 'react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {SDKProvider} from './SDKProvider'
+
+// Renders the real `react-error-boundary`, which skips `onError` when the fallback rethrows.
+vi.mock('@sanity/sdk/_internal', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  reportError: vi.fn(),
+}))
+vi.mock('../context/ResourceProvider', () => ({
+  ResourceProvider: ({children}: {children: ReactNode}) => children,
+}))
+vi.mock('./auth/AuthBoundary', () => ({
+  AuthBoundary: ({children}: {children: ReactNode}) => children,
+}))
+vi.mock('../context/OrganizationResourcesProvider', () => ({
+  OrganizationResourcesProvider: ({children}: {children: ReactNode}) => children,
+}))
+
+class AppBoundary extends Component<{children: ReactNode}, {caught: boolean}> {
+  override state = {caught: false}
+  static getDerivedStateFromError() {
+    return {caught: true}
+  }
+  override render() {
+    return this.state.caught ? 'app boundary caught it' : this.props.children
+  }
+}
+
+function Thrower({error}: {error: Error}): never {
+  throw error
+}
+
+describe('SDKProvider error reporting', () => {
+  beforeEach(() => {
+    vi.mocked(reportError).mockClear()
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  it('reports an error it rethrows, and the app boundary still receives it', () => {
+    const error = new TypeError('sdk bug')
+    render(
+      <AppBoundary>
+        <SDKProvider config={{projectId: 'p', dataset: 'd'}} fallback={null}>
+          <Thrower error={error} />
+        </SDKProvider>
+      </AppBoundary>,
+    )
+
+    expect(screen.getByText('app boundary caught it')).toBeInTheDocument()
+    expect(reportError).toHaveBeenCalledWith(error, {errorBoundary: 'SDKProvider'})
+  })
+
+  it('does not report a chunk load error, which it renders itself', () => {
+    const error = Object.assign(new Error('Loading chunk 5 failed.'), {name: 'ChunkLoadError'})
+    render(
+      <AppBoundary>
+        <SDKProvider config={{projectId: 'p', dataset: 'd'}} fallback={null}>
+          <Thrower error={error} />
+        </SDKProvider>
+      </AppBoundary>,
+    )
+
+    expect(reportError).not.toHaveBeenCalled()
+  })
+})

package/src/components/SDKProvider.tsx

@@ -13,6 +13,9 @@ import {ResourceProvider} from '../context/ResourceProvider'
 import {AuthBoundary, type AuthBoundaryProps} from './auth/AuthBoundary'
 import {ChunkLoadError} from './errors/ChunkLoadError'
 import {clearChunkReloadFlag} from './errors/chunkReloadStorage'
+import {reportBoundaryError} from './errors/reportBoundaryError'
+
+const reportSDKProviderError = reportBoundaryError('SDKProvider')
 
 /**
  * @internal
@@ -119,6 +122,8 @@ function ChunkAwareFallback(fallbackProps: FallbackProps): ReactElement {
   if (isImportError(fallbackProps.error)) {
     return <ChunkLoadError {...fallbackProps} />
   }
+  // Report here, not in `onError`: React skips `onError` on a boundary whose fallback rethrows
+  reportSDKProviderError(fallbackProps.error)
   // Re-throw so downstream boundaries (e.g. AuthBoundary) handle other errors.
   throw fallbackProps.error
 }

package/src/components/auth/AuthBoundary.reporting.test.tsx

@@ -0,0 +1,80 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {reportError} from '@sanity/sdk/_internal'
+import {render, screen} from '@testing-library/react'
+import {Component, type ReactNode} from 'react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {AuthBoundary} from './AuthBoundary'
+import {AuthError} from './AuthError'
+
+// These tests render the real `react-error-boundary`. `AuthBoundary.test.tsx` replaces it with a
+// mock that always calls `componentDidCatch`, which React does not do for a boundary whose
+// fallback rethrows.
+vi.mock('@sanity/sdk/_internal', async (importOriginal) => ({
+  ...(await importOriginal<object>()),
+  reportError: vi.fn(),
+}))
+vi.mock('../../hooks/auth/useAuthState', () => ({
+  useAuthState: vi.fn(() => ({type: 'logged-in', token: 'token', currentUser: null})),
+}))
+const instance = createSanityInstance()
+vi.mock('../../hooks/context/useSanityInstance', () => ({useSanityInstance: () => instance}))
+vi.mock('../../hooks/auth/useLoginUrl')
+vi.mock('../../hooks/auth/useOAuthAuthorize', () => ({useOAuthAuthorize: vi.fn(() => vi.fn())}))
+vi.mock('../../hooks/auth/useVerifyOrgProjects')
+vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
+  useHandleAuthCallback: vi.fn(() => async () => {}),
+}))
+vi.mock('../../hooks/auth/useLogOut', () => ({useLogOut: vi.fn(() => async () => {})}))
+vi.mock('../../hooks/comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(() => ({fetch: vi.fn()})),
+}))
+vi.mock('../utils', () => ({isInIframe: vi.fn(() => false)}))
+
+/** Stands in for the app's own boundary that receives errors the SDK rethrows. */
+class AppBoundary extends Component<{children: ReactNode}, {caught: boolean}> {
+  override state = {caught: false}
+  static getDerivedStateFromError() {
+    return {caught: true}
+  }
+  override render() {
+    return this.state.caught ? 'app boundary caught it' : this.props.children
+  }
+}
+
+function Thrower({error}: {error: Error}): never {
+  throw error
+}
+
+describe('AuthBoundary error reporting', () => {
+  beforeEach(() => {
+    vi.mocked(reportError).mockClear()
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  it('reports a plain error from a child and still rethrows it to the app boundary', () => {
+    const error = new TypeError('sdk bug')
+    render(
+      <AppBoundary>
+        <AuthBoundary>
+          <Thrower error={error} />
+        </AuthBoundary>
+      </AppBoundary>,
+    )
+
+    expect(screen.getByText('app boundary caught it')).toBeInTheDocument()
+    expect(reportError).toHaveBeenCalledWith(error, {errorBoundary: 'AuthBoundary'})
+  })
+
+  it('does not report an auth error, which the boundary renders itself', () => {
+    render(
+      <AppBoundary>
+        <AuthBoundary>
+          <Thrower error={new AuthError(new Error('login failed'))} />
+        </AuthBoundary>
+      </AppBoundary>,
+    )
+
+    expect(reportError).not.toHaveBeenCalled()
+  })
+})

package/src/components/auth/AuthBoundary.tsx

@@ -13,6 +13,7 @@ import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
 import {useSanityInstance} from '../../hooks/context/useSanityInstance'
 import {ChunkLoadError} from '../errors/ChunkLoadError'
 import {CorsErrorComponent} from '../errors/CorsErrorComponent'
+import {reportBoundaryError} from '../errors/reportBoundaryError'
 import {isInIframe} from '../utils'
 import {AuthError} from './AuthError'
 import {ConfigurationError} from './ConfigurationError'
@@ -34,6 +35,8 @@ if (isInIframe() && !document.querySelector('[data-sanity-core]')) {
   document.head.appendChild(script)
 }
 
+const reportAuthBoundaryError = reportBoundaryError('AuthBoundary')
+
 /**
  * @internal
  */
@@ -124,6 +127,9 @@ export function AuthBoundary({
 
   const FallbackComponent = useMemo(() => {
     return function LoginComponentWithLayoutProps(fallbackProps: FallbackProps) {
+      // `LoginError` rethrows errors it does not render, and React skips `onError` on a boundary
+      // whose fallback throws, so the report has to happen here
+      reportAuthBoundaryError(fallbackProps.error)
       // Chunk-load errors from any lazy-loaded code beneath this boundary
       // (typically the consumer's app) get the chunk-aware fallback instead
       // of being misreported as auth errors.

package/src/components/errors/reportBoundaryError.test.ts

@@ -0,0 +1,38 @@
+import {CorsOriginError} from '@sanity/client'
+import {reportError} from '@sanity/sdk/_internal'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {AuthError} from '../auth/AuthError'
+import {ConfigurationError} from '../auth/ConfigurationError'
+import {reportBoundaryError} from './reportBoundaryError'
+
+vi.mock('@sanity/sdk/_internal', () => ({reportError: vi.fn()}))
+
+describe('reportBoundaryError', () => {
+  beforeEach(() => {
+    vi.mocked(reportError).mockClear()
+  })
+
+  it('reports an unexpected error with the boundary name', () => {
+    const error = new TypeError('boom')
+    reportBoundaryError('AuthBoundary')(error)
+    expect(reportError).toHaveBeenCalledWith(error, {errorBoundary: 'AuthBoundary'})
+  })
+
+  it.each([
+    ['AuthError', new AuthError(new Error('login failed'))],
+    ['ConfigurationError', new ConfigurationError({message: 'bad config'})],
+    ['CorsOriginError', new CorsOriginError({projectId: 'abc'})],
+    [
+      'a CorsOriginError from another copy of @sanity/client',
+      Object.assign(new Error('CorsOriginError'), {name: 'CorsOriginError'}),
+    ],
+    [
+      'a chunk load error',
+      Object.assign(new Error('Loading chunk 5 failed.'), {name: 'ChunkLoadError'}),
+    ],
+  ])('does not report %s', (_name, error) => {
+    reportBoundaryError('AuthBoundary')(error)
+    expect(reportError).not.toHaveBeenCalled()
+  })
+})

package/src/components/errors/reportBoundaryError.ts

@@ -0,0 +1,33 @@
+import {CorsOriginError} from '@sanity/client'
+import {isImportError} from '@sanity/sdk'
+import {reportError} from '@sanity/sdk/_internal'
+
+import {AuthError} from '../auth/AuthError'
+import {ConfigurationError} from '../auth/ConfigurationError'
+
+/**
+ * Creates a function that reports an error an `ErrorBoundary` caught to Sentry. Call it from the
+ * boundary's `FallbackComponent`, not from `onError`: the SDK fallbacks rethrow errors they do not
+ * render, and React skips `onError` on a boundary whose fallback throws. Fallbacks render more
+ * than once for one error, which the reporter's deduplication absorbs.
+ *
+ * The boundaries also catch errors thrown by the app rendered beneath them, so the reporter keeps
+ * only errors whose throwing frame is in the SDK. Auth, configuration, CORS, and chunk load errors
+ * are expected states and are never reported.
+ */
+export function reportBoundaryError(errorBoundary: string) {
+  return (error: unknown): void => {
+    if (
+      error instanceof AuthError ||
+      error instanceof ConfigurationError ||
+      // The module bundle can hold a second copy of `@sanity/client`, so `instanceof` alone can
+      // miss an error thrown by the other copy
+      error instanceof CorsOriginError ||
+      (error instanceof Error && error.name === 'CorsOriginError') ||
+      isImportError(error)
+    ) {
+      return
+    }
+    reportError(error, {errorBoundary})
+  }
+}

package/src/context/AppFunctionsContext.ts

@@ -0,0 +1,13 @@
+import {type AppFunctionContract} from '@sanity/sdk/_internal'
+import {createContext} from 'react'
+
+/** Function stack binding supplied by the CLI-generated app entry. @internal */
+export interface AppFunctionsConfig {
+  /** Generated client contracts, supplied by the CLI. */
+  functions?: Record<string, AppFunctionContract>
+  stackId: string
+  organizationId: string
+}
+
+/** App-local defaults for authenticated function clients. @internal */
+export const AppFunctionsContext = createContext<AppFunctionsConfig | undefined>(undefined)

package/src/context/AppFunctionsProvider.tsx

@@ -0,0 +1,20 @@
+import {type ReactNode} from 'react'
+
+import {type AppFunctionsConfig, AppFunctionsContext} from './AppFunctionsContext'
+
+export type {AppFunctionsConfig} from './AppFunctionsContext'
+
+/** Props for the CLI's function binding provider. @internal */
+export interface AppFunctionsProviderProps {
+  value: AppFunctionsConfig
+  children: ReactNode
+}
+
+/**
+ * Provide a function stack to useClient within this application's React tree.
+ * Authentication stays with the SDK instance. The CLI supplies stack IDs and contracts.
+ * @internal
+ */
+export function AppFunctionsProvider({value, children}: AppFunctionsProviderProps): ReactNode {
+  return <AppFunctionsContext.Provider value={value}>{children}</AppFunctionsContext.Provider>
+}

package/src/hooks/client/useClient.ts

@@ -1,7 +1,15 @@
-import {type ClientOptions, getClientState, type SanityInstance} from '@sanity/sdk'
+import {type SanityClient} from '@sanity/client'
+import {type ClientOptions, getClientState} from '@sanity/sdk'
+import {useContext} from 'react'
 
+import {AppFunctionsContext} from '../../context/AppFunctionsContext'
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
+const useClientState = createStateSourceHook({
+  getState: getClientState,
+  getConfig: (options: ClientOptions) => options,
+})
+
 /**
  * A React hook that provides a client that subscribes to changes in your application,
  *
@@ -29,15 +37,21 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * @public
  * @function
  */
-export const useClient = createStateSourceHook({
-  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,
-})
+export function useClient(options: ClientOptions): SanityClient {
+  const binding = useContext(AppFunctionsContext)
+  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 useClientState(
+    binding
+      ? {
+          ...options,
+          stackId: options.stackId ?? binding.stackId,
+          organizationId: options.organizationId ?? binding.organizationId,
+        }
+      : options,
+  )
+}

package/src/hooks/functions/useFunctions.ts

@@ -0,0 +1,28 @@
+import {type AppFunctions} from '@sanity/sdk'
+import {createAppFunctions} from '@sanity/sdk/_internal'
+import {useContext, useMemo} from 'react'
+
+import {AppFunctionsContext} from '../../context/AppFunctionsContext'
+import {useClient} from '../client/useClient'
+
+/**
+ * Return the app's typed, authenticated functions. Types are generated by Sanity CLI.
+ * Each call waits for the function's result and validates it against the generated contract.
+ * @example
+ * ```tsx
+ * const functions = useFunctions()
+ * const page = await functions.callWikipedia({timeout: 30_000})
+ * ```
+ * @public
+ */
+export function useFunctions(): AppFunctions {
+  const binding = useContext(AppFunctionsContext)
+  const client = useClient({apiVersion: '2026-06-15', scope: 'global'})
+  const contracts = binding?.functions
+  return useMemo(() => {
+    if (!contracts) {
+      throw new Error('App function contracts are missing. Build the app with Sanity CLI.')
+    }
+    return createAppFunctions(client, contracts)
+  }, [client, contracts])
+}