@sanity/sdk-react 2.9.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -43,16 +43,14 @@
   "browserslist": "extends @sanity/browserslist-config",
   "prettier": "@sanity/prettier-config",
   "dependencies": {
-    "@sanity/client": "^7.14.1",
-    "@sanity/message-protocol": "^0.18.0",
+    "@sanity/client": "^7.22.0",
+    "@sanity/message-protocol": "^0.23.0",
     "@sanity/types": "^5.2.0",
-    "@types/lodash-es": "^4.17.12",
     "groq": "3.88.1-typegen-experimental.0",
-    "lodash-es": "^4.17.21",
     "react-compiler-runtime": "19.1.0-rc.2",
     "react-error-boundary": "^5.0.0",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "2.9.0"
+    "@sanity/sdk": "2.11.0"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
@@ -65,31 +63,28 @@
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.7.0",
-    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/coverage-v8": "4.1.5",
     "babel-plugin-react-compiler": "19.1.0-rc.1",
     "eslint": "^9.22.0",
     "groq-js": "^1.22.0",
-    "jsdom": "^25.0.1",
+    "jsdom": "^29.0.2",
     "prettier": "^3.7.3",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.0",
-    "vitest": "^3.2.4",
-    "@repo/tsconfig": "0.0.1",
-    "@repo/package.config": "0.0.1",
+    "vitest": "^4.1.4",
     "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/package.config": "0.0.1",
+    "@repo/tsconfig": "0.0.1",
     "@repo/config-eslint": "0.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
-  "engines": {
-    "node": ">=20.19"
-  },
   "publishConfig": {
     "access": "public"
   },

package/src/_exports/index.ts

@@ -1,2 +1,4 @@
 export * from './sdk-react.ts'
 export * from '@sanity/sdk'
+// React-layer handles shadow core equivalents when imported from @sanity/sdk-react
+export type {DocumentHandle, DocumentTypeHandle, ResourceHandle} from './sdk-react.ts'

package/src/_exports/sdk-react.ts

@@ -4,9 +4,14 @@
 export {AuthBoundary, type AuthBoundaryProps} from '../components/auth/AuthBoundary'
 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 {ComlinkTokenRefreshProvider} from '../context/ComlinkTokenRefresh'
 export {renderSanityApp} from '../context/renderSanityApp'
 export {ResourceProvider, type ResourceProviderProps} from '../context/ResourceProvider'
+export {
+  SanityInstanceProvider,
+  type SanityInstanceProviderProps,
+} from '../context/SanityInstanceProvider'
 export {SDKStudioContext, type StudioWorkspaceHandle} from '../context/SDKStudioContext'
 export {
   useAgentGenerate,
@@ -40,6 +45,7 @@ export {
   type WindowConnection,
   type WindowMessageHandler,
 } from '../hooks/comlink/useWindowConnection'
+export {useResource} from '../hooks/context/useResource'
 export {useSanityInstance} from '../hooks/context/useSanityInstance'
 export {useDashboardNavigate} from '../hooks/dashboard/useDashboardNavigate'
 export {useDispatchIntent} from '../hooks/dashboard/useDispatchIntent'
@@ -63,6 +69,8 @@ export {
   type DocumentsResponse,
   useDocuments,
 } from '../hooks/documents/useDocuments'
+export {useOrganization} from '../hooks/organizations/useOrganization'
+export {useOrganizations} from '../hooks/organizations/useOrganizations'
 export {
   type PaginatedDocumentsOptions,
   type PaginatedDocumentsResponse,

package/src/components/SDKProvider.test.tsx

@@ -62,7 +62,7 @@ describe('SDKProvider', () => {
     })
   })
 
-  it('renders nested ResourceProviders with AuthBoundary for multiple configs', () => {
+  it('renders a single ResourceProvider using the first config when multiple configs are provided', () => {
     const configs = [
       {
         projectId: 'project-1',
@@ -80,22 +80,15 @@ describe('SDKProvider', () => {
       </SDKProvider>,
     )
 
-    // Should create two nested ResourceProviders
+    // Should create a single ResourceProvider using the first config
     const providers = getAllByTestId('resource-provider')
-    expect(providers.length).toBe(2)
+    expect(providers.length).toBe(1)
 
-    // Should create an AuthBoundary inside the innermost provider
+    // Should create an AuthBoundary inside
     expect(getByTestId('auth-boundary')).toBeInTheDocument()
 
-    // Verify each provider has the correct config - order is based on how SDKProvider creates nestings
-    // The first provider contains config[1]
+    // Verify the provider uses the first config
     expect(JSON.parse(providers[0].getAttribute('data-config') || '{}')).toEqual({
-      projectId: 'project-2',
-      dataset: 'staging',
-    })
-
-    // The second provider contains config[0]
-    expect(JSON.parse(providers[1].getAttribute('data-config') || '{}')).toEqual({
       projectId: 'project-1',
       dataset: 'production',
     })

package/src/components/SDKProvider.tsx

@@ -1,9 +1,13 @@
-import {type DocumentSource, type SanityConfig} from '@sanity/sdk'
-import {type ReactElement, type ReactNode, useMemo} from 'react'
+import {type DocumentResource, isImportError, type SanityConfig} from '@sanity/sdk'
+import {type ReactElement, type ReactNode, useEffect, useMemo} from 'react'
+import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
+import {DEFAULT_RESOURCE_NAME} from '../constants'
 import {ResourceProvider} from '../context/ResourceProvider'
-import {SourcesContext} from '../context/SourcesContext'
+import {ResourcesContext} from '../context/ResourcesContext'
 import {AuthBoundary, type AuthBoundaryProps} from './auth/AuthBoundary'
+import {ChunkLoadError} from './errors/ChunkLoadError'
+import {clearChunkReloadFlag} from './errors/chunkReloadStorage'
 
 /**
  * @internal
@@ -12,15 +16,25 @@ export interface SDKProviderProps extends AuthBoundaryProps {
   children: ReactNode
   config: SanityConfig | SanityConfig[]
   fallback: ReactNode
-  sources?: Record<string, DocumentSource>
+  resources?: Record<string, DocumentResource>
+}
+
+/**
+ * Clears the chunk-reload flag once children render successfully past the
+ * top-level boundary, so a future incident in the same session can trigger
+ * another automatic reload.
+ */
+function ResetChunkReloadFlagOnMount(): null {
+  useEffect(() => {
+    clearChunkReloadFlag()
+  }, [])
+  return null
 }
 
 /**
  * @internal
  *
  * Top-level context provider that provides access to the Sanity SDK.
- * Creates a hierarchy of ResourceProviders, each providing a SanityInstance that can be
- * accessed by hooks. The first configuration in the array becomes the default instance.
  */
 export function SDKProvider({
   children,
@@ -28,30 +42,46 @@ export function SDKProvider({
   fallback,
   ...props
 }: SDKProviderProps): ReactElement {
-  // reverse because we want the first config to be the default, but the
-  // ResourceProvider nesting makes the last one the default
-  const configs = (Array.isArray(config) ? config : [config]).slice().reverse()
-  const projectIds = configs.map((c) => c.projectId).filter((id): id is string => !!id)
-
-  // Memoize sources to prevent creating a new empty object on every render
-  const sourcesValue = useMemo(() => props.sources ?? {}, [props.sources])
-
-  // Create a nested structure of ResourceProviders for each config
-  const createNestedProviders = (index: number): ReactElement => {
-    if (index >= configs.length) {
-      return (
-        <AuthBoundary {...props} projectIds={projectIds}>
-          <SourcesContext.Provider value={sourcesValue}>{children}</SourcesContext.Provider>
-        </AuthBoundary>
-      )
+  const allConfigs = Array.isArray(config) ? config : [config]
+  const resolvedConfig = allConfigs[0]
+  const projectIds = allConfigs.map((c) => c.projectId).filter((id): id is string => !!id)
+
+  // Extract static fields so the memo below doesn't take a reference dependency
+  // on `config` — inline config objects change identity on every render.
+  const singleConfig = Array.isArray(config) ? null : config
+  const defaultProjectId = singleConfig?.projectId
+  const defaultDataset = singleConfig?.dataset
+
+  // For a single config, synthesize a 'default' resource from its projectId/dataset
+  // so that hooks can resolve it via resourceName: 'default' or fall back to it
+  // automatically when no resource info is provided.
+  const resourcesValue = useMemo(() => {
+    const explicit = props.resources ?? {}
+    if (defaultProjectId && defaultDataset && !Object.hasOwn(explicit, DEFAULT_RESOURCE_NAME)) {
+      return {
+        [DEFAULT_RESOURCE_NAME]: {projectId: defaultProjectId, dataset: defaultDataset},
+        ...explicit,
+      }
     }
+    return explicit
+  }, [defaultProjectId, defaultDataset, props.resources])
 
-    return (
-      <ResourceProvider {...configs[index]} fallback={fallback}>
-        {createNestedProviders(index + 1)}
+  return (
+    <ErrorBoundary FallbackComponent={ChunkAwareFallback}>
+      <ResetChunkReloadFlagOnMount />
+      <ResourceProvider {...resolvedConfig} fallback={fallback}>
+        <AuthBoundary {...props} projectIds={projectIds}>
+          <ResourcesContext.Provider value={resourcesValue}>{children}</ResourcesContext.Provider>
+        </AuthBoundary>
       </ResourceProvider>
-    )
-  }
+    </ErrorBoundary>
+  )
+}
 
-  return createNestedProviders(0)
+function ChunkAwareFallback(fallbackProps: FallbackProps): ReactElement {
+  if (isImportError(fallbackProps.error)) {
+    return <ChunkLoadError {...fallbackProps} />
+  }
+  // Re-throw so downstream boundaries (e.g. AuthBoundary) handle other errors.
+  throw fallbackProps.error
 }

package/src/components/SanityApp.tsx

@@ -1,4 +1,4 @@
-import {type DocumentSource, isStudioConfig, type SanityConfig} from '@sanity/sdk'
+import {type DocumentResource, isStudioConfig, type SanityConfig} from '@sanity/sdk'
 import {type ReactElement, useContext, useEffect, useMemo} from 'react'
 
 import {SDKStudioContext, type StudioWorkspaceHandle} from '../context/SDKStudioContext'
@@ -19,7 +19,7 @@ export interface SanityAppProps {
   config?: SanityConfig | SanityConfig[]
   /** @deprecated use the `config` prop instead. */
   sanityConfigs?: SanityConfig[]
-  sources?: Record<string, DocumentSource>
+  resources?: Record<string, DocumentResource>
   children: React.ReactNode
   /* Fallback content to show when child components are suspending. Same as the `fallback` prop for React Suspense. */
   fallback: React.ReactNode

package/src/components/auth/AuthBoundary.tsx

@@ -1,5 +1,5 @@
 import {CorsOriginError} from '@sanity/client'
-import {AuthStateType, getCorsErrorProjectId, isStudioConfig} from '@sanity/sdk'
+import {AuthStateType, getCorsErrorProjectId, isImportError, isStudioConfig} from '@sanity/sdk'
 import {useEffect, useMemo} from 'react'
 import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
@@ -8,6 +8,7 @@ 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 {ChunkLoadError} from '../errors/ChunkLoadError'
 import {CorsErrorComponent} from '../errors/CorsErrorComponent'
 import {isInIframe} from '../utils'
 import {AuthError} from './AuthError'
@@ -110,6 +111,12 @@ export function AuthBoundary({
 }: AuthBoundaryProps): React.ReactNode {
   const FallbackComponent = useMemo(() => {
     return function LoginComponentWithLayoutProps(fallbackProps: FallbackProps) {
+      // 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.
+      if (isImportError(fallbackProps.error)) {
+        return <ChunkLoadError {...fallbackProps} />
+      }
       if (fallbackProps.error instanceof CorsOriginError) {
         return (
           <CorsErrorComponent

package/src/components/auth/DashboardAccessRequest.tsx

@@ -0,0 +1,37 @@
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {useEffect} from 'react'
+
+import {useWindowConnection} from '../../hooks/comlink/useWindowConnection'
+
+interface DashboardAccessRequestProps {
+  projectId: string
+}
+
+/**
+ * Sends a `dashboard/v1/auth/access/request` message to the dashboard via
+ * comlink so the user can request access to a project they don't belong to.
+ *
+ * This is intentionally isolated in its own component because
+ * `useWindowConnection` suspends until a comlink node is available, which
+ * never happens outside the dashboard. Callers must gate rendering on
+ * `getIsInDashboardState(...).getCurrent()` and wrap this in a
+ * {@link https://react.dev/reference/react/Suspense | Suspense} boundary
+ * so the suspension stays local instead of bubbling up to the app shell.
+ *
+ * @internal
+ */
+export function DashboardAccessRequest({projectId}: DashboardAccessRequestProps): null {
+  const {fetch} = useWindowConnection({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  useEffect(() => {
+    fetch('dashboard/v1/auth/access/request', {
+      resourceType: 'project',
+      resourceId: projectId,
+    })
+  }, [fetch, projectId])
+
+  return null
+}

package/src/components/auth/LoginError.test.tsx

@@ -1,19 +1,51 @@
+import {ClientError} from '@sanity/client'
+import {getIsInDashboardState} from '@sanity/sdk'
 import {fireEvent, render, screen, waitFor} from '@testing-library/react'
-import {describe, expect, it, vi} from 'vitest'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
 import {AuthError} from './AuthError'
 import {LoginError} from './LoginError'
 
+vi.mock('@sanity/sdk', async () => {
+  const actual = await vi.importActual('@sanity/sdk')
+  return {
+    ...actual,
+    getIsInDashboardState: vi.fn(() => ({getCurrent: vi.fn(() => false)})),
+  }
+})
+
+const mockLogout = vi.fn(async () => {})
 vi.mock('../../hooks/auth/useLogOut', () => ({
-  useLogOut: vi.fn(() => async () => {}),
+  useLogOut: vi.fn(() => mockLogout),
 }))
 
+const mockWindowConnectionFetch = vi.fn()
 vi.mock('../../hooks/comlink/useWindowConnection', () => ({
-  useWindowConnection: vi.fn(() => ({fetch: vi.fn()})),
+  useWindowConnection: vi.fn(() => ({fetch: mockWindowConnectionFetch})),
 }))
 
+const mockGetIsInDashboardState = getIsInDashboardState as Mock
+
+function makeClientError(statusCode: number, body: unknown): ClientError {
+  return new ClientError({
+    statusCode,
+    headers: {},
+    body,
+    url: 'https://example.test',
+    method: 'GET',
+  } as ConstructorParameters<typeof ClientError>[0])
+}
+
 describe('LoginError', () => {
+  beforeEach(() => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => false)})
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
   it('shows authentication error and retry button', async () => {
     const mockReset = vi.fn()
     const error = new AuthError(new Error('Test error'))
@@ -38,7 +70,6 @@ describe('LoginError', () => {
     const mockReset = vi.fn()
     const nonAuthError = new Error('Non-auth error')
 
-    // Suppress console.error during this test
     const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
 
     expect(() => {
@@ -49,6 +80,161 @@ describe('LoginError', () => {
       )
     }).toThrow('Non-auth error')
 
-    consoleErrorSpy.mockRestore() // Restore original console.error behavior
+    consoleErrorSpy.mockRestore()
+  })
+
+  // In a standalone app (not embedded in the dashboard) the dashboard access
+  // request path must not render, because useWindowConnection would suspend
+  // waiting for a comlink node that never arrives.
+  it('renders synchronously on a 401 projectUserNotFound error outside the dashboard', async () => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => false)})
+
+    const error = makeClientError(401, {
+      error: {
+        type: 'projectUserNotFoundError',
+        description: 'User is not a member of this project.',
+      },
+    })
+
+    render(
+      <ResourceProvider fallback={<div>SUSPENDED</div>}>
+        <LoginError error={error} resetErrorBoundary={vi.fn()} />
+      </ResourceProvider>,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('User is not a member of this project.')).toBeInTheDocument()
+    })
+    // ClientError must render under the "Authentication Error" heading; it is
+    // not a ConfigurationError.
+    expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+    expect(screen.queryByText('Configuration Error')).not.toBeInTheDocument()
+    expect(screen.queryByText('SUSPENDED')).not.toBeInTheDocument()
+    expect(mockWindowConnectionFetch).not.toHaveBeenCalled()
+  })
+
+  it('fires the dashboard access request on a 401 projectUserNotFound error inside the dashboard', async () => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => true)})
+
+    const error = makeClientError(401, {
+      error: {
+        type: 'projectUserNotFoundError',
+        description: 'User is not a member of this project.',
+      },
+    })
+
+    render(
+      <ResourceProvider projectId="abc123" dataset="production" fallback={<div>SUSPENDED</div>}>
+        <LoginError error={error} resetErrorBoundary={vi.fn()} />
+      </ResourceProvider>,
+    )
+
+    await waitFor(() => {
+      expect(mockWindowConnectionFetch).toHaveBeenCalledWith('dashboard/v1/auth/access/request', {
+        resourceType: 'project',
+        resourceId: 'abc123',
+      })
+    })
+  })
+
+  // Mirrors the real production chain: AuthBoundary wraps the ClientError in
+  // an AuthError before the error boundary hands it to LoginError. The
+  // `.cause` unwrap is what makes the dashboard access request path reachable
+  // at runtime (without it, the previous `error instanceof ClientError` check
+  // was dead code in the dashboard).
+  it('fires the dashboard access request when the projectUserNotFound ClientError is wrapped in an AuthError', async () => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => true)})
+
+    const clientError = makeClientError(401, {
+      error: {
+        type: 'projectUserNotFoundError',
+        description: 'User is not a member of this project.',
+      },
+    })
+    const error = new AuthError(clientError)
+    const mockReset = vi.fn()
+
+    render(
+      <ResourceProvider projectId="abc123" dataset="production" fallback={<div>SUSPENDED</div>}>
+        <LoginError error={error} resetErrorBoundary={mockReset} />
+      </ResourceProvider>,
+    )
+
+    await waitFor(() => {
+      expect(mockWindowConnectionFetch).toHaveBeenCalledWith('dashboard/v1/auth/access/request', {
+        resourceType: 'project',
+        resourceId: 'abc123',
+      })
+    })
+
+    expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+    expect(screen.getByText('User is not a member of this project.')).toBeInTheDocument()
+    // projectUserNotFound intentionally hides the Retry CTA: the user can't
+    // fix it by retrying, only by getting access granted through the
+    // dashboard access request flow above.
+    expect(screen.queryByRole('button', {name: 'Retry'})).not.toBeInTheDocument()
+    // Dashboard flow must never auto-log-out; ComlinkTokenRefreshProvider is
+    // responsible for any token mutation, not LoginError.
+    expect(mockLogout).not.toHaveBeenCalled()
+    expect(mockReset).not.toHaveBeenCalled()
+  })
+
+  // In a standalone app, an invalid-token 401 (anything other than
+  // `projectUserNotFoundError`) should silently log the user out so that
+  // AuthBoundary's LOGGED_OUT effect redirects to the Sanity login URL.
+  // AuthBoundary wraps the real ClientError in an AuthError before it reaches
+  // the error boundary, so the component must unwrap `.cause` to see it.
+  it('auto-logs-out on a non-projectUserNotFound 401 outside the dashboard', async () => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => false)})
+
+    const mockReset = vi.fn()
+    const clientError = makeClientError(401, {
+      error: {type: 'someOther401Type', description: 'Token is invalid'},
+    })
+    const error = new AuthError(clientError)
+
+    render(
+      <ResourceProvider fallback={null}>
+        <LoginError error={error} resetErrorBoundary={mockReset} />
+      </ResourceProvider>,
+    )
+
+    expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+    expect(await screen.findByText('Signing you out and returning to login...')).toBeInTheDocument()
+    await waitFor(() => {
+      expect(mockLogout).toHaveBeenCalled()
+    })
+    await waitFor(() => {
+      expect(mockReset).toHaveBeenCalled()
+    })
+  })
+
+  // In the dashboard we must not auto-log-out on a generic 401.
+  // ComlinkTokenRefreshProvider is responsible for asking the parent window
+  // for a fresh token; the Retry button stays as a manual fallback.
+  it('does not auto-log-out on a non-projectUserNotFound 401 inside the dashboard', async () => {
+    mockGetIsInDashboardState.mockReturnValue({getCurrent: vi.fn(() => true)})
+
+    const mockReset = vi.fn()
+    const clientError = makeClientError(401, {
+      error: {type: 'someOther401Type', description: 'Token is invalid'},
+    })
+    const error = new AuthError(clientError)
+
+    render(
+      <ResourceProvider projectId="abc123" dataset="production" fallback={null}>
+        <LoginError error={error} resetErrorBoundary={mockReset} />
+      </ResourceProvider>,
+    )
+
+    expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+    expect(
+      screen.getByText('Please try again or contact support if the problem persists.'),
+    ).toBeInTheDocument()
+    expect(screen.getByRole('button', {name: 'Retry'})).toBeInTheDocument()
+    expect(mockLogout).not.toHaveBeenCalled()
+    expect(mockReset).not.toHaveBeenCalled()
+    // Generic 401s should not trigger the dashboard access request flow.
+    expect(mockWindowConnectionFetch).not.toHaveBeenCalled()
   })
 })