@sanity/sdk 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -61,18 +61,18 @@
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/pkg-utils": "^7.9.6",
-    "@sanity/prettier-config": "^1.0.3",
+    "@sanity/prettier-config": "^1.0.6",
     "@types/lodash-es": "^4.17.12",
-    "@vitest/coverage-v8": "3.1.2",
+    "@vitest/coverage-v8": "3.2.4",
     "eslint": "^9.22.0",
-    "prettier": "^3.5.3",
+    "prettier": "^3.7.3",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.4",
-    "vitest": "^3.1.2",
-    "@repo/config-eslint": "0.0.0",
+    "vitest": "^3.2.4",
     "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/config-eslint": "0.0.0",
     "@repo/tsconfig": "0.0.1",
     "@repo/package.config": "0.0.1"
   },

package/src/_exports/index.ts

@@ -5,6 +5,25 @@ import {type SanityProject as _SanityProject} from '@sanity/client'
  */
 export type SanityProject = _SanityProject
 
+export type {
+  AgentGenerateOptions,
+  AgentGenerateResult,
+  AgentPatchOptions,
+  AgentPatchResult,
+  AgentPromptOptions,
+  AgentPromptResult,
+  AgentTransformOptions,
+  AgentTransformResult,
+  AgentTranslateOptions,
+  AgentTranslateResult,
+} from '../agent/agentActions'
+export {
+  agentGenerate,
+  agentPatch,
+  agentPrompt,
+  agentTransform,
+  agentTranslate,
+} from '../agent/agentActions'
 export {AuthStateType} from '../auth/authStateType'
 export {
   type AuthState,
@@ -24,6 +43,13 @@ export {
 export {observeOrganizationVerificationState} from '../auth/getOrganizationVerificationState'
 export {handleAuthCallback} from '../auth/handleAuthCallback'
 export {logout} from '../auth/logout'
+export {
+  type ApiErrorBody,
+  getClientErrorApiBody,
+  getClientErrorApiDescription,
+  getClientErrorApiType,
+  isProjectUserNotFoundClientError,
+} from '../auth/utils'
 export type {ClientStoreState as ClientState} from '../client/clientStore'
 export {type ClientOptions, getClient, getClientState} from '../client/clientStore'
 export {
@@ -50,9 +76,13 @@ export {
   createProjectHandle,
 } from '../config/handles'
 export {
+  canvasSource,
   type DatasetHandle,
+  datasetSource,
   type DocumentHandle,
+  type DocumentSource,
   type DocumentTypeHandle,
+  mediaLibrarySource,
   type PerspectiveHandle,
   type ProjectHandle,
   type ReleasePerspective,

package/src/agent/agentActions.test.ts

@@ -0,0 +1,81 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {firstValueFrom, of} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {
+  agentGenerate,
+  agentPatch,
+  agentPrompt,
+  agentTransform,
+  agentTranslate,
+} from './agentActions'
+
+let mockClient: any
+
+vi.mock('../client/clientStore', () => {
+  return {
+    getClientState: () => ({observable: of(mockClient)}),
+  }
+})
+
+describe('agent actions', () => {
+  beforeEach(() => {
+    mockClient = {
+      observable: {
+        agent: {
+          action: {
+            generate: vi.fn(),
+            transform: vi.fn(),
+            translate: vi.fn(),
+          },
+        },
+      },
+      agent: {
+        action: {
+          prompt: vi.fn(),
+          patch: vi.fn(),
+        },
+      },
+    }
+  })
+
+  it('agentGenerate returns observable from client', async () => {
+    mockClient.observable.agent.action.generate.mockReturnValue(of('gen'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentGenerate(instance, {foo: 'bar'} as any))
+    expect(value).toBe('gen')
+    expect(mockClient.observable.agent.action.generate).toHaveBeenCalledWith({foo: 'bar'})
+  })
+
+  it('agentTransform returns observable from client', async () => {
+    mockClient.observable.agent.action.transform.mockReturnValue(of('xform'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentTransform(instance, {a: 1} as any))
+    expect(value).toBe('xform')
+    expect(mockClient.observable.agent.action.transform).toHaveBeenCalledWith({a: 1})
+  })
+
+  it('agentTranslate returns observable from client', async () => {
+    mockClient.observable.agent.action.translate.mockReturnValue(of('xlate'))
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentTranslate(instance, {b: 2} as any))
+    expect(value).toBe('xlate')
+    expect(mockClient.observable.agent.action.translate).toHaveBeenCalledWith({b: 2})
+  })
+
+  it('agentPrompt wraps promise into observable', async () => {
+    mockClient.agent.action.prompt.mockResolvedValue('prompted')
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentPrompt(instance, {p: true} as any))
+    expect(value).toBe('prompted')
+    expect(mockClient.agent.action.prompt).toHaveBeenCalledWith({p: true})
+  })
+
+  it('agentPatch wraps promise into observable', async () => {
+    mockClient.agent.action.patch.mockResolvedValue('patched')
+    const instance = {config: {projectId: 'p', dataset: 'd'}} as any
+    const value = await firstValueFrom(agentPatch(instance, {q: false} as any))
+    expect(value).toBe('patched')
+    expect(mockClient.agent.action.patch).toHaveBeenCalledWith({q: false})
+  })
+})

package/src/agent/agentActions.ts

@@ -0,0 +1,139 @@
+import {type SanityClient} from '@sanity/client'
+import {from, Observable, switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {type SanityInstance} from '../store/createSanityInstance'
+
+const API_VERSION = 'vX'
+
+/** @alpha */
+export type AgentGenerateOptions = Parameters<
+  SanityClient['observable']['agent']['action']['generate']
+>[0]
+
+/** @alpha */
+export type AgentTransformOptions = Parameters<
+  SanityClient['observable']['agent']['action']['transform']
+>[0]
+
+/** @alpha */
+export type AgentTranslateOptions = Parameters<
+  SanityClient['observable']['agent']['action']['translate']
+>[0]
+
+/** @alpha */
+export type AgentPromptOptions = Parameters<SanityClient['agent']['action']['prompt']>[0]
+
+/** @alpha */
+export type AgentPatchOptions = Parameters<SanityClient['agent']['action']['patch']>[0]
+
+/** @alpha */
+export type AgentGenerateResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['generate']>
+>
+
+/** @alpha */
+export type AgentTransformResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['transform']>
+>
+
+/** @alpha */
+export type AgentTranslateResult = Awaited<
+  ReturnType<SanityClient['observable']['agent']['action']['translate']>
+>
+
+/** @alpha */
+export type AgentPromptResult = Awaited<ReturnType<SanityClient['agent']['action']['prompt']>>
+
+/** @alpha */
+export type AgentPatchResult = Awaited<ReturnType<SanityClient['agent']['action']['patch']>>
+
+/**
+ * Generates a new document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent generate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent generate action.
+ * @alpha
+ */
+export function agentGenerate(
+  instance: SanityInstance,
+  options: AgentGenerateOptions,
+): AgentGenerateResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.generate(options)))
+}
+
+/**
+ * Transforms a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent transform action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent transform action.
+ * @alpha
+ */
+export function agentTransform(
+  instance: SanityInstance,
+  options: AgentTransformOptions,
+): AgentTransformResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.transform(options)))
+}
+
+/**
+ * Translates a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent translate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent translate action.
+ * @alpha
+ */
+export function agentTranslate(
+  instance: SanityInstance,
+  options: AgentTranslateOptions,
+): AgentTranslateResult {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => client.observable.agent.action.translate(options)))
+}
+
+/**
+ * Prompts the agent using the same instruction template format as the other actions, but returns text or json instead of acting on a document.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent prompt action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent prompt action.
+ * @alpha
+ */
+export function agentPrompt(
+  instance: SanityInstance,
+  options: AgentPromptOptions,
+): Observable<AgentPromptResult> {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.prompt(options))))
+}
+
+/**
+ * Patches a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent patch action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent patch action.
+ * @alpha
+ */
+export function agentPatch(
+  instance: SanityInstance,
+  options: AgentPatchOptions,
+): Observable<AgentPatchResult> {
+  return getClientState(instance, {
+    apiVersion: API_VERSION,
+    projectId: instance.config.projectId,
+    dataset: instance.config.dataset,
+  }).observable.pipe(switchMap((client) => from(client.agent.action.patch(options))))
+}

package/src/auth/authStore.test.ts

@@ -237,6 +237,7 @@ describe('authStore', () => {
     it('sets to logged in using studio token when studio mode is enabled and token exists', () => {
       const studioToken = 'studio-token'
       const projectId = 'studio-project'
+      const studioStorageKey = `__studio_auth_token_${projectId}`
       const mockStorage = {
         getItem: vi.fn(),
         setItem: vi.fn(),
@@ -252,40 +253,38 @@ describe('authStore', () => {
       })
 
       const {authState, options} = authStore.getInitialState(instance)
-      expect(getStudioTokenFromLocalStorage).toHaveBeenCalledWith(mockStorage, projectId)
+      expect(getStudioTokenFromLocalStorage).toHaveBeenCalledWith(mockStorage, studioStorageKey)
       expect(authState).toMatchObject({type: AuthStateType.LOGGED_IN, token: studioToken})
       expect(options.authMethod).toBe('localstorage')
     })
 
-    it('checks for cookie auth when studio mode is enabled and no studio token exists', async () => {
-      vi.useFakeTimers()
+    it('checks for cookie auth during initialize when studio mode is enabled and no studio token exists', () => {
       const projectId = 'studio-project'
+      const studioStorageKey = `__studio_auth_token_${projectId}`
       const mockStorage = {
         getItem: vi.fn(),
         setItem: vi.fn(),
         removeItem: vi.fn(),
       } as unknown as Storage // Mock storage
       vi.mocked(getStudioTokenFromLocalStorage).mockReturnValue(null)
-      // Mock cookie check to return true asynchronously
       vi.mocked(checkForCookieAuth).mockResolvedValue(true)
 
       instance = createSanityInstance({
         projectId,
         dataset: 'd',
         studioMode: {enabled: true},
-        auth: {storageArea: mockStorage}, // Provide mock storage
+        auth: {storageArea: mockStorage},
       })
 
-      // Initial state might be logged out before the async check completes
+      // Verify initial state without async cookie probe
       const {authState: initialAuthState} = authStore.getInitialState(instance)
-      expect(initialAuthState.type).toBe(AuthStateType.LOGGED_OUT) // Or potentially logging in depending on other factors
-      expect(getStudioTokenFromLocalStorage).toHaveBeenCalledWith(mockStorage, projectId)
-      expect(checkForCookieAuth).toHaveBeenCalledWith(projectId, expect.any(Function))
+      expect(initialAuthState.type).toBe(AuthStateType.LOGGED_OUT)
+      expect(getStudioTokenFromLocalStorage).toHaveBeenCalledWith(mockStorage, studioStorageKey)
 
-      // Wait for the promise in getInitialState to resolve
-      await vi.runAllTimersAsync()
+      // Trigger store creation + initialize
+      getAuthState(instance)
 
-      vi.useRealTimers()
+      expect(checkForCookieAuth).toHaveBeenCalledWith(projectId, expect.any(Function))
     })
 
     it('falls back to default auth (storage token) when studio mode is disabled', () => {
@@ -573,14 +572,7 @@ describe('authStore', () => {
       expect(initialOrgId.getCurrent()).toBe('initial-org-id')
 
       // Call handleCallback with the callback URL
-      await handleAuthCallback(instance, callbackUrl) // Use await as handleAuthCallback is async
-
-      // Wait for the state update to be reflected in the selector
-      await vi.waitUntil(
-        () => getDashboardOrganizationId(instance).getCurrent() === 'callback-org-id',
-      )
-      // Add a microtask yield just in case
-      await new Promise((resolve) => setTimeout(resolve, 0))
+      await handleAuthCallback(instance, callbackUrl)
 
       // Check that the orgId from the callback context is now set
       const finalOrgId = getDashboardOrganizationId(instance)

package/src/auth/authStore.ts

@@ -67,7 +67,11 @@ export interface DashboardContext {
   orgId?: string
 }
 
-type AuthMethodOptions = 'localstorage' | 'cookie' | undefined
+/**
+ * The method of authentication used.
+ * @internal
+ */
+export type AuthMethodOptions = 'localstorage' | 'cookie' | undefined
 
 let tokenRefresherRunning = false
 
@@ -105,7 +109,8 @@ export const authStore = defineStore<AuthStoreState>({
     } = instance.config.auth ?? {}
     let storageArea = instance.config.auth?.storageArea
 
-    const storageKey = `__sanity_auth_token`
+    let storageKey = `__sanity_auth_token`
+    const studioModeEnabled = instance.config.studioMode?.enabled
 
     // This login URL will only be used for local development
     let loginDomain = 'https://www.sanity.io'
@@ -149,23 +154,21 @@ export const authStore = defineStore<AuthStoreState>({
       console.error('Failed to parse dashboard context from initial location:', err)
     }
 
-    if (!isInDashboard) {
+    if (!isInDashboard || studioModeEnabled) {
       // If not in dashboard, use the storage area from the config
+      // If studio mode is enabled, use the local storage area (default)
       storageArea = storageArea ?? getDefaultStorage()
     }
 
     let token: string | null
     let authMethod: AuthMethodOptions
-    if (instance.config.studioMode?.enabled) {
-      token = getStudioTokenFromLocalStorage(storageArea, instance.config.projectId)
+    if (studioModeEnabled) {
+      // In studio mode, always use the studio-specific storage key and subscribe to it
+      const studioStorageKey = `__studio_auth_token_${instance.config.projectId ?? ''}`
+      storageKey = studioStorageKey
+      token = getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
       if (token) {
         authMethod = 'localstorage'
-      } else {
-        checkForCookieAuth(instance.config.projectId, clientFactory).then((isCookieAuthEnabled) => {
-          if (isCookieAuthEnabled) {
-            authMethod = 'cookie'
-          }
-        })
       }
     } else {
       token = getTokenFromStorage(storageArea, storageKey)
@@ -177,14 +180,16 @@ export const authStore = defineStore<AuthStoreState>({
     let authState: AuthState
     if (providedToken) {
       authState = {type: AuthStateType.LOGGED_IN, token: providedToken, currentUser: null}
+    } else if (token && studioModeEnabled) {
+      authState = {type: AuthStateType.LOGGED_IN, token: token ?? '', currentUser: null}
     } else if (
       getAuthCode(callbackUrl, initialLocationHref) ||
       getTokenFromLocation(initialLocationHref)
     ) {
       authState = {type: AuthStateType.LOGGING_IN, isExchangingToken: false}
       // Note: dashboardContext from the callback URL can be set later in handleAuthCallback too
-    } else if (token && !isInDashboard) {
-      // Only use token from storage if NOT running in dashboard
+    } else if (token && !isInDashboard && !studioModeEnabled) {
+      // Only use token from storage if NOT running in dashboard and studio mode is not enabled
       authState = {type: AuthStateType.LOGGED_IN, token, currentUser: null}
     } else {
       // Default to logged out if no provided token, not handling callback,
@@ -212,11 +217,37 @@ export const authStore = defineStore<AuthStoreState>({
   initialize(context) {
     const subscriptions: Subscription[] = []
     subscriptions.push(subscribeToStateAndFetchCurrentUser(context))
-
-    if (context.state.get().options?.storageArea) {
+    const storageArea = context.state.get().options?.storageArea
+    if (storageArea) {
       subscriptions.push(subscribeToStorageEventsAndSetToken(context))
     }
 
+    // If in Studio mode with no local token, resolve cookie auth asynchronously
+    try {
+      const {instance, state} = context
+      const studioModeEnabled = !!instance.config.studioMode?.enabled
+      const token: string | null =
+        state.get().authState?.type === AuthStateType.LOGGED_IN
+          ? (state.get().authState as LoggedInAuthState).token
+          : null
+      if (studioModeEnabled && !token) {
+        const projectId = instance.config.projectId
+        const clientFactory = state.get().options.clientFactory
+        checkForCookieAuth(projectId, clientFactory).then((isCookieAuthEnabled) => {
+          if (!isCookieAuthEnabled) return
+          state.set('enableCookieAuth', (prev) => ({
+            options: {...prev.options, authMethod: 'cookie'},
+            authState:
+              prev.authState.type === AuthStateType.LOGGED_IN
+                ? prev.authState
+                : {type: AuthStateType.LOGGED_IN, token: '', currentUser: null},
+          }))
+        })
+      }
+    } catch {
+      // best-effort cookie detection
+    }
+
     if (!tokenRefresherRunning) {
       tokenRefresherRunning = true
       subscriptions.push(refreshStampedToken(context))

package/src/auth/studioModeAuth.test.ts

@@ -96,7 +96,7 @@ describe('getStudioTokenFromLocalStorage', () => {
     expect(getTokenFromStorageSpy).not.toHaveBeenCalled()
   })
 
-  it('should return null if projectId is undefined', () => {
+  it('should return null if storageKey is undefined', () => {
     const result = getStudioTokenFromLocalStorage(storageArea, undefined)
     expect(result).toBeNull()
     expect(getTokenFromStorageSpy).not.toHaveBeenCalled()
@@ -104,19 +104,19 @@ describe('getStudioTokenFromLocalStorage', () => {
 
   it('should call getTokenFromStorage with correct key', () => {
     getTokenFromStorageSpy.mockReturnValue(null) // Assume token not found for this test
-    getStudioTokenFromLocalStorage(storageArea, projectId)
+    getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
     expect(getTokenFromStorageSpy).toHaveBeenCalledWith(storageArea, studioStorageKey)
   })
 
   it('should return the token if found in storage', () => {
     getTokenFromStorageSpy.mockReturnValue(mockToken)
-    const result = getStudioTokenFromLocalStorage(storageArea, projectId)
+    const result = getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
     expect(result).toBe(mockToken)
   })
 
   it('should return null if token is not found in storage', () => {
     getTokenFromStorageSpy.mockReturnValue(null)
-    const result = getStudioTokenFromLocalStorage(storageArea, projectId)
+    const result = getStudioTokenFromLocalStorage(storageArea, studioStorageKey)
     expect(result).toBeNull()
   })
 })

package/src/auth/studioModeAuth.ts

@@ -33,17 +33,16 @@ export async function checkForCookieAuth(
 /**
  * Attempts to retrieve a studio token from local storage.
  * @param storageArea - The storage area to retrieve the token from.
- * @param projectId - The project ID to retrieve the token for.
+ * @param storageKey - The storage key to retrieve the token from.
  * @returns The studio token or null if it does not exist.
  * @internal
  */
 export function getStudioTokenFromLocalStorage(
   storageArea: Storage | undefined,
-  projectId: string | undefined,
+  storageKey: string | undefined,
 ): string | null {
-  if (!storageArea || !projectId) return null
-  const studioStorageKey = `__studio_auth_token_${projectId}`
-  const token = getTokenFromStorage(storageArea, studioStorageKey)
+  if (!storageArea || !storageKey) return null
+  const token = getTokenFromStorage(storageArea, storageKey)
   if (token) {
     return token
   }

package/src/auth/subscribeToStateAndFetchCurrentUser.ts

@@ -4,32 +4,43 @@ import {distinctUntilChanged, filter, map, type Subscription, switchMap} from 'r
 import {type StoreContext} from '../store/defineStore'
 import {DEFAULT_API_VERSION, REQUEST_TAG_PREFIX} from './authConstants'
 import {AuthStateType} from './authStateType'
-import {type AuthState, type AuthStoreState} from './authStore'
+import {type AuthMethodOptions, type AuthState, type AuthStoreState} from './authStore'
 
 export const subscribeToStateAndFetchCurrentUser = ({
   state,
+  instance,
 }: StoreContext<AuthStoreState>): Subscription => {
   const {clientFactory, apiHost} = state.get().options
+  const useProjectHostname = !!instance.config.studioMode?.enabled
+  const projectId = instance.config.projectId
 
   const currentUser$ = state.observable
     .pipe(
-      map(({authState}) => authState),
+      map(({authState, options}) => ({authState, authMethod: options.authMethod})),
       filter(
-        (authState): authState is Extract<AuthState, {type: AuthStateType.LOGGED_IN}> =>
-          authState.type === AuthStateType.LOGGED_IN && !authState.currentUser,
+        (
+          value,
+        ): value is {
+          authState: Extract<AuthState, {type: AuthStateType.LOGGED_IN}>
+          authMethod: AuthMethodOptions
+        } => value.authState.type === AuthStateType.LOGGED_IN && !value.authState.currentUser,
+      ),
+      map((value) => ({token: value.authState.token, authMethod: value.authMethod})),
+      distinctUntilChanged(
+        (prev, curr) => prev.token === curr.token && prev.authMethod === curr.authMethod,
       ),
-      map((authState) => authState.token),
-      distinctUntilChanged(),
     )
     .pipe(
-      map((token) =>
+      map(({token, authMethod}) =>
         clientFactory({
           apiVersion: DEFAULT_API_VERSION,
           requestTagPrefix: REQUEST_TAG_PREFIX,
-          token,
+          token: authMethod === 'cookie' ? undefined : token,
           ignoreBrowserTokenWarning: true,
-          useProjectHostname: false,
+          useProjectHostname,
           useCdn: false,
+          ...(authMethod === 'cookie' ? {withCredentials: true} : {}),
+          ...(useProjectHostname && projectId ? {projectId} : {}),
           ...(apiHost && {apiHost}),
         }),
       ),

package/src/auth/utils.ts

@@ -1,3 +1,4 @@
+import {type ClientError} from '@sanity/client'
 import {EMPTY, fromEvent, Observable} from 'rxjs'
 
 import {AUTH_CODE_PARAM, DEFAULT_BASE} from './authConstants'
@@ -134,3 +135,38 @@ export function getCleanedUrl(locationUrl: string): string {
   loc.searchParams.delete('url')
   return loc.toString()
 }
+
+// -----------------------------------------------------------------------------
+// ClientError helpers (shared)
+// -----------------------------------------------------------------------------
+
+/** @internal */
+export type ApiErrorBody = {
+  error?: {type?: string; description?: string}
+  type?: string
+  description?: string
+  message?: string
+}
+
+/** @internal Extracts the structured API error body from a ClientError, if present. */
+export function getClientErrorApiBody(error: ClientError): ApiErrorBody | undefined {
+  const body: unknown = (error as ClientError).response?.body
+  return body && typeof body === 'object' ? (body as ApiErrorBody) : undefined
+}
+
+/** @internal Returns the error type string from an API error body, if available. */
+export function getClientErrorApiType(error: ClientError): string | undefined {
+  const body = getClientErrorApiBody(error)
+  return body?.error?.type ?? body?.type
+}
+
+/** @internal Returns the error description string from an API error body, if available. */
+export function getClientErrorApiDescription(error: ClientError): string | undefined {
+  const body = getClientErrorApiBody(error)
+  return body?.error?.description ?? body?.description
+}
+
+/** @internal True if the error represents a projectUserNotFoundError. */
+export function isProjectUserNotFoundClientError(error: ClientError): boolean {
+  return getClientErrorApiType(error) === 'projectUserNotFoundError'
+}