@sanity/sdk 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -37,46 +37,47 @@
     "./package.json": "./package.json",
     "./_internal": "./dist/_exports/_internal.js",
     "./agent": "./dist/_exports/agent.js",
-    "./comlink": "./dist/_exports/comlink.js"
+    "./comlink": "./dist/_exports/comlink.js",
+    "./dashboard": "./dist/_exports/dashboard.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@sanity/bifur-client": "^1.0.0",
-    "@sanity/client": "^8.4.0",
+    "@sanity/client": "^8.6.1",
     "@sanity/comlink": "^4.0.3",
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
-    "@sanity/id-utils": "^1.0.0",
+    "@sanity/id-utils": "^1.1.0",
     "@sanity/image-url": "^2.1.1",
     "@sanity/json-match": "^1.0.5",
     "@sanity/message-protocol": "^0.24.0",
     "@sanity/mutate": "^0.18.1",
     "@sanity/telemetry": "^1.1.0",
-    "@sanity/types": "^6.12.0",
-    "groq": "3.88.1-typegen-experimental.0",
+    "@sanity/types": "^6.13.0",
+    "groq": "^6.13.2",
     "groq-js": "^2.0.0",
     "reselect": "^5.1.1",
     "rxjs": "^7.8.2",
-    "zustand": "^5.0.13"
+    "zustand": "^5.0.15"
   },
   "devDependencies": {
-    "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/pkg-utils": "^12.1.0",
-    "@types/node": "^24.13.3",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.6.0",
-    "oxfmt": "^0.58.0",
-    "rolldown": "^1.2.3",
-    "typescript": "^6.0.3",
-    "vite": "^8.1.5",
-    "vitest": "^4.1.10",
     "@repo/config-eslint": "0.0.0",
     "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
     "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/tsconfig": "0.0.1",
+    "@sanity/browserslist-config": "^1.0.5",
+    "@sanity/pkg-utils": "^13.0.0",
+    "@types/node": "^24.13.4",
+    "@vitest/coverage-v8": "^5.0.0",
+    "eslint": "^10.10.0",
+    "oxfmt": "^0.67.0",
+    "rolldown": "^1.2.8",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.0"
   },
   "browserslist": "extends @sanity/browserslist-config",
   "scripts": {

package/src/_exports/_internal.ts

@@ -7,6 +7,17 @@ export {
   isProjectUserNotFoundClientError,
 } from '../auth/utils'
 export {getCommentsOptionsKey, parseCommentsOptionsKey} from '../comments/commentsStore' // only used for memoizing in React, not needed for actual functionality
+export {
+  installMessageBus,
+  type InstallMessageBusOptions,
+  resetMessageBus,
+} from '../dashboard/messageBus/bus'
+export {
+  getDashboardMessageBus,
+  isDashboardEnvironment,
+  requireDashboardMessageBus,
+} from '../dashboard/messageBus/store'
+export {getTopicState, resolveTopic} from '../dashboard/messageBus/topicStore'
 export {PREVIEW_PROJECTION} from '../preview/previewConstants'
 export {transformProjectionToPreview} from '../preview/previewProjectionUtils'
 export {getQueryKey, parseQueryKey} from '../query/queryStore' // only used for memoizing in React, not needed for actual functionality
@@ -25,4 +36,5 @@ export {getTelemetryManager, initTelemetry, trackHookMounted} from '../telemetry
 export {getUsersKey, parseUsersKey} from '../users/reducers' // only used for memoizing in React, not needed for actual functionality
 export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'
 export {randomId, randomUuid} from '../utils/ids'
+export {createLogger} from '../utils/logger'
 export {isDeepEqual, pickProperties} from '../utils/object'

package/src/_exports/dashboard.ts

@@ -0,0 +1,36 @@
+export type {
+  ConnectMessageBusOptions,
+  MessageBus,
+  MessageBusAbortOptions,
+  MessageBusClient,
+  MessageBusConnection,
+  MessageBusEmitOptions,
+  MessageBusEmitResult,
+  MessageBusErrorCode,
+  MessageBusHost,
+  MessageBusMessage,
+  MessageBusMeta,
+  MessageBusQueryOptions,
+  MessageBusStateSource,
+} from '../dashboard/messageBus/bus'
+export {connectMessageBus} from '../dashboard/messageBus/bus'
+export {MessageBusError} from '../dashboard/messageBus/bus'
+export type {
+  ApplicationConfig,
+  ApplicationConfigAppType,
+  DashboardTopics,
+  EventTopic,
+  EventTopicDef,
+  NavigationLocation,
+  NavigationTarget,
+  PayloadOf,
+  RemoteModuleRef,
+  ReplyOf,
+  StateTopic,
+  StateTopicDef,
+  TopicName,
+  TopicResult,
+  Topics,
+  ValueOf,
+} from '../dashboard/messageBus/topics'
+export {type TopicData, TopicError} from '../dashboard/messageBus/topicStore'

package/src/_exports/index.ts

@@ -20,6 +20,7 @@ export {
   type ApplicationDeployment,
   type ApplicationInclude,
   type ApplicationInterface,
+  type ApplicationInterfacePlacementMetadata,
   type ApplicationsOptions,
   type ApplicationsResponse,
   type ApplicationStudioConfig,
@@ -48,6 +49,14 @@ export {
 export {observeOrganizationVerificationState} from '../auth/getOrganizationVerificationState'
 export {handleAuthCallback} from '../auth/handleAuthCallback'
 export {logout} from '../auth/logout'
+export {
+  getOAuthTokensState,
+  handleOAuthCallback,
+  refreshOAuthTokens,
+  revokeOAuthTokens,
+  startOAuthAuthorization,
+} from '../auth/oauth/oauthActions'
+export {type OAuthTokens} from '../auth/oauth/types'
 export type {ClientStoreState as ClientState} from '../client/clientStore'
 export {type ClientOptions, getClient, getClientState} from '../client/clientStore'
 export {
@@ -181,6 +190,12 @@ export {
 export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'
 export {getReleaseDocumentId} from '../document/processActions/releaseUtil'
+export {
+  type DocumentSet,
+  patchOperations,
+  processMutations,
+  type ProcessMutationsOptions,
+} from '../document/processMutations'
 export type {
   FavoriteDocumentContext,
   FavoriteStatusResponse,
@@ -194,7 +209,6 @@ export {
   type InstallationActiveConfig,
   type InstallationBase,
   type InstallationInclude,
-  type InstallationInterface,
   type InstallationsOptions,
   type InstallationsResponse,
 } from '../installations/installations'
@@ -244,6 +258,8 @@ export type {ReleaseState} from '../releases/releasesStore'
 export {getActiveReleasesState, getAllReleasesState} from '../releases/releasesStore'
 export {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 export {type Selector, type StateSource} from '../store/createStateSourceAction'
+export {defineProjection} from '../typegen/defineProjection'
+export type {ResolveDocument, ResolveProjectionResult, ResolveQueryResult} from '../typegen/resolve'
 export {
   type GetUserOptions,
   type GetUsersOptions,

package/src/applications/applications.test-d.ts

@@ -10,6 +10,7 @@ import {
   type ApplicationDeployment,
   type ApplicationInclude,
   type ApplicationInterface,
+  type ApplicationInterfacePlacementMetadata,
   applications,
   type ApplicationsResponse,
   type ApplicationStudioConfig,
@@ -35,10 +36,30 @@ test('ApplicationBase — carries name and reference as strings', () => {
   expectTypeOf<ApplicationBase['reference']>().toEqualTypeOf<string>()
 })
 
-test('Application — config.studio adds a required config.studio', () => {
+test('ApplicationInterface — matches the interface response', () => {
+  expectTypeOf<ApplicationInterface['type']>().toEqualTypeOf<
+    'app' | 'worker' | 'asset_source' | 'panel' | 'tile'
+  >()
+  expectTypeOf<ApplicationInterfacePlacementMetadata>().toEqualTypeOf<{
+    dock?: {group?: string; order?: number}
+  }>()
+  expectTypeOf<
+    Extract<ApplicationInterface, {type: 'app'}>['metadata']
+  >().toEqualTypeOf<ApplicationInterfacePlacementMetadata | null>()
   expectTypeOf<
-    Application<'config.studio'>['config']['studio']
-  >().toEqualTypeOf<ApplicationStudioConfig>()
+    Extract<ApplicationInterface, {type: 'panel'}>['metadata']
+  >().toEqualTypeOf<ApplicationInterfacePlacementMetadata | null>()
+  expectTypeOf<Extract<ApplicationInterface, {type: 'worker'}>['metadata']>().toEqualTypeOf<null>()
+  expectTypeOf<Extract<ApplicationInterface, {type: 'tile'}>['metadata']>().toEqualTypeOf<{
+    order?: number
+    size: 'small' | 'large' | 'banner'
+  }>()
+})
+
+test('Application — config.studio adds config with an optional stored value', () => {
+  expectTypeOf<Application<'config.studio'>['config']['studio']>().toEqualTypeOf<
+    ApplicationStudioConfig | undefined
+  >()
   // mfManifest not requested → not present under config
   expectTypeOf<
     Extract<keyof Application<'config.studio'>['config'], 'mfManifest'>
@@ -51,7 +72,7 @@ test('Application — config.studio adds a required config.studio', () => {
 
 test('Application — both config tokens merge under a single config', () => {
   type Config = Application<'config.studio' | 'config.mfManifest'>['config']
-  expectTypeOf<Config['studio']>().toEqualTypeOf<ApplicationStudioConfig>()
+  expectTypeOf<Config['studio']>().toEqualTypeOf<ApplicationStudioConfig | undefined>()
   expectTypeOf<Config['mfManifest']>().toEqualTypeOf<unknown>()
 })
 
@@ -73,6 +94,9 @@ test('Application — a wide include array makes config and activeDeployment opt
   type Wide = Application<ApplicationInclude>
   expectTypeOf<KeyModifier<Wide, 'activeDeployment'>>().toEqualTypeOf<'optional'>()
   expectTypeOf<KeyModifier<Wide, 'config'>>().toEqualTypeOf<'optional'>()
+  type Config = NonNullable<Wide['config']>
+  expectTypeOf<Config['studio']>().toEqualTypeOf<ApplicationStudioConfig | undefined>()
+  expectTypeOf<Config['mfManifest']>().toEqualTypeOf<unknown>()
 })
 
 test('applications.resolveState — resolves the wide list envelope', () => {

package/src/applications/applications.ts

@@ -25,23 +25,40 @@ export type ApplicationInclude =
   | 'config.mfManifest'
   | 'activeDeployment'
 
-/**
- * An interface exposed by a deployment, embedded when `interfaces` is included.
- *
- * @see https://www.sanity.io/docs/http-reference/applications-api
- * @public
- */
-export interface ApplicationInterface {
+type ApplicationInterfaceBase = {
   id: string
-  type: 'app' | 'worker' | 'asset_source' | 'panel'
   name: string
   title: string
   version: string
   /** Module federation module ID; resolved from the host mf-manifest at runtime */
   moduleId: string
-  metadata: {group?: string; priority?: number} | null
 }
 
+/**
+ * Placement metadata for application and panel interfaces.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export type ApplicationInterfacePlacementMetadata = {
+  dock?: {group?: string; order?: number}
+}
+
+/**
+ * An interface exposed by a deployment, embedded when `interfaces` is included.
+ *
+ * @see https://www.sanity.io/docs/http-reference/applications-api
+ * @public
+ */
+export type ApplicationInterface = ApplicationInterfaceBase &
+  (
+    | {type: 'app'; metadata: ApplicationInterfacePlacementMetadata | null}
+    | {type: 'panel'; metadata: ApplicationInterfacePlacementMetadata | null}
+    | {type: 'asset_source'; metadata: null}
+    | {type: 'worker'; metadata: null}
+    | {type: 'tile'; metadata: {order?: number; size: 'small' | 'large' | 'banner'}}
+  )
+
 /**
  * A studio workspace of a deployment, embedded when `workspaces` is included.
  * Studio applications only.
@@ -136,16 +153,24 @@ export interface ApplicationBase {
 
 // Requesting any of these tokens forces the deployment summary into the response.
 type DeploymentToken = 'activeDeployment' | 'interfaces' | 'workspaces' | 'access'
+type ConfigToken = 'config.studio' | 'config.mfManifest'
 
-// `config` is present when either config child was requested; each child is
-// gated on its own token.
-type ApplicationConfigShape<Include extends ApplicationInclude> = Included<
+type ApplicationConfig<Include extends ApplicationInclude> = Included<
   ApplicationInclude,
   'config.studio',
   Include,
-  {config: {studio: ApplicationStudioConfig}}
+  {studio?: ApplicationStudioConfig}
 > &
-  Included<ApplicationInclude, 'config.mfManifest', Include, {config: {mfManifest: unknown}}>
+  Included<ApplicationInclude, 'config.mfManifest', Include, {mfManifest?: unknown}>
+
+// Brett returns `config: {}` when a requested config value is not stored.
+type ApplicationConfigShape<Include extends ApplicationInclude> = [ApplicationInclude] extends [
+  Include,
+]
+  ? {config?: ApplicationConfig<Include>}
+  : IncludesAny<Include, ConfigToken> extends true
+    ? {config: ApplicationConfig<Include>}
+    : unknown
 
 // `activeDeployment` is present when any deployment-related token was requested;
 // a wide include array makes it optional.

package/src/auth/authMode.test.ts

@@ -18,6 +18,30 @@ describe('resolveAuthMode', () => {
   it('returns "standalone" by default', () => {
     expect(resolveAuthMode({}, 'https://example.com')).toBe('standalone')
   })
+
+  it('returns "oauth" when auth.oauth config is provided', () => {
+    const config: SanityConfig = {
+      auth: {oauth: {clientId: 'c', redirectUri: 'https://app/cb', organizationId: 'o'}},
+    }
+    expect(resolveAuthMode(config, 'https://example.com')).toBe('oauth')
+  })
+
+  it('prefers "oauth" over dashboard context detection', () => {
+    const context = encodeURIComponent(JSON.stringify({orgId: '123'}))
+    const href = `https://example.com?_context=${context}`
+    const config: SanityConfig = {
+      auth: {oauth: {clientId: 'c', redirectUri: 'https://app/cb', organizationId: 'o'}},
+    }
+    expect(resolveAuthMode(config, href)).toBe('oauth')
+  })
+
+  it('prefers "studio" over oauth config', () => {
+    const config: SanityConfig = {
+      studio: {},
+      auth: {oauth: {clientId: 'c', redirectUri: 'https://app/cb', organizationId: 'o'}},
+    }
+    expect(resolveAuthMode(config, 'https://example.com')).toBe('studio')
+  })
 })
 
 describe('isStudioConfig', () => {

package/src/auth/authMode.ts

@@ -6,6 +6,8 @@ import {DEFAULT_BASE} from './authConstants'
  *
  * - `studio`     — Running inside Sanity Studio. Token is discovered from
  *                  Studio's localStorage entry or via cookie auth.
+ * - `oauth`      — Configured with `auth.oauth`. Authenticates via Sanity's
+ *                  OAuth 2.0 authorization-code + PKCE flow.
  * - `dashboard`  — Running inside the Sanity Dashboard iframe. Token is
  *                  provided by the parent frame via Comlink.
  * - `standalone` — Running as an independent app. Token comes from
@@ -13,20 +15,23 @@ import {DEFAULT_BASE} from './authConstants'
  *
  * @internal
  */
-type AuthMode = 'studio' | 'dashboard' | 'standalone'
+type AuthMode = 'studio' | 'oauth' | 'dashboard' | 'standalone'
 
 /**
  * Determines the auth mode from instance config and environment.
  *
  * Priority:
  * 1. `studio` config provided → `'studio'`
- * 2. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
- * 3. Otherwise → `'standalone'`
+ * 2. `auth.oauth` config provided → `'oauth'` (explicit config wins over
+ *    environment detection)
+ * 3. Dashboard context detected (`_context` URL param with content) → `'dashboard'`
+ * 4. Otherwise → `'standalone'`
  *
  * @internal
  */
 export function resolveAuthMode(config: SanityConfig, locationHref: string): AuthMode {
   if (isStudioConfig(config)) return 'studio'
+  if (config.auth?.oauth) return 'oauth'
   if (detectDashboardContext(locationHref)) return 'dashboard'
   return 'standalone'
 }

package/src/auth/authStore.ts

@@ -11,6 +11,8 @@ import {resolveAuthMode} from './authMode'
 import {AuthStateType} from './authStateType'
 import {type AuthStrategyOptions} from './authStrategy'
 import {getDashboardInitialState, initializeDashboardAuth} from './dashboardAuth'
+import {getOauthInitialState, initializeOauthAuth} from './oauth/oauthAuth'
+import {type OAuthTokens} from './oauth/types'
 import {getStandaloneInitialState, initializeStandaloneAuth} from './standaloneAuth'
 import {getStudioInitialState, initializeStudioAuth} from './studioAuth'
 import {createLoggedInAuthState, getCleanedUrl, getDefaultLocation} from './utils'
@@ -91,8 +93,10 @@ export interface AuthStoreState {
     callbackUrl: string | undefined
     providedToken: string | undefined
     authMethod: AuthMethodOptions
+    oauth: AuthConfig['oauth']
   }
   dashboardContext?: DashboardContext
+  oauthTokens?: OAuthTokens
 }
 
 // ---------------------------------------------------------------------------
@@ -155,6 +159,9 @@ export const authStore = defineStore<AuthStoreState>({
       case 'studio':
         result = getStudioInitialState(strategyOptions)
         break
+      case 'oauth':
+        result = getOauthInitialState(strategyOptions)
+        break
       case 'dashboard':
         result = getDashboardInitialState(strategyOptions)
         break
@@ -172,6 +179,7 @@ export const authStore = defineStore<AuthStoreState>({
     return {
       authState: result.authState,
       dashboardContext: result.dashboardContext,
+      oauthTokens: result.oauthTokens,
       options: {
         apiHost,
         loginUrl: loginUrl.toString(),
@@ -183,6 +191,7 @@ export const authStore = defineStore<AuthStoreState>({
         storageKey: result.storageKey,
         storageArea: result.storageArea,
         authMethod: result.authMethod,
+        oauth: authConfig.oauth,
       },
     }
   },
@@ -201,6 +210,9 @@ export const authStore = defineStore<AuthStoreState>({
       case 'studio':
         initResult = initializeStudioAuth(context, tokenRefresherRunning)
         break
+      case 'oauth':
+        initResult = initializeOauthAuth(context)
+        break
       case 'dashboard':
         initResult = initializeDashboardAuth(context, tokenRefresherRunning)
         break

package/src/auth/authStrategy.ts

@@ -3,6 +3,7 @@ import {type ClientConfig, type SanityClient} from '@sanity/client'
 import {type AuthConfig} from '../config/authConfig'
 import {type TokenSource} from '../config/sanityConfig'
 import {type AuthMethodOptions, type AuthState, type DashboardContext} from './authStore'
+import {type OAuthTokens} from './oauth/types'
 
 /**
  * The result returned by each auth strategy's `getInitialState` function.
@@ -17,6 +18,7 @@ export interface AuthStrategyResult {
   storageArea: Storage | undefined
   authMethod: AuthMethodOptions
   dashboardContext: DashboardContext
+  oauthTokens?: OAuthTokens
 }
 
 /**

package/src/auth/logout.test.ts

@@ -5,6 +5,9 @@ import {createSanityInstance, type SanityInstance} from '../store/createSanityIn
 import {AuthStateType} from './authStateType'
 import {getAuthState} from './authStore'
 import {logout} from './logout'
+import {getOAuthTokensState, serializeTokens} from './oauth/oauthActions'
+import {OAUTH_TOKENS_KEY} from './oauth/oauthAuth'
+import {type OAuthTokens} from './oauth/types'
 import {subscribeToStateAndFetchCurrentUser} from './subscribeToStateAndFetchCurrentUser'
 import {subscribeToStorageEventsAndSetToken} from './subscribeToStorageEventsAndSetToken'
 import {getTokenFromStorage} from './utils'
@@ -166,6 +169,48 @@ describe('logout', () => {
     expect(removeItem).toHaveBeenCalledWith('__sanity_auth_token')
   })
 
+  it('clears the OAuth tokens from the store on logout', async () => {
+    const oauthTokens: OAuthTokens = {
+      accessToken: 'oauth-access',
+      tokenType: 'bearer',
+      expiresIn: 3600,
+      expiresAt: new Date('2030-01-01T00:00:00.000Z'),
+      refreshToken: 'oauth-refresh',
+    }
+    const map = new Map<string, string>([[OAUTH_TOKENS_KEY, serializeTokens(oauthTokens)]])
+    const storageArea = {
+      getItem: (k: string) => map.get(k) ?? null,
+      setItem: (k: string, v: string) => void map.set(k, v),
+      removeItem: (k: string) => void map.delete(k),
+    } as Storage
+
+    const mockRequest = vi.fn().mockResolvedValue(undefined)
+    const clientFactory = vi.fn().mockReturnValue({request: mockRequest})
+
+    instance = createSanityInstance({
+      projectId: 'p',
+      dataset: 'd',
+      auth: {
+        clientFactory,
+        storageArea,
+        oauth: {
+          clientId: 'client-abc',
+          redirectUri: 'https://app.example.com/callback',
+          organizationId: 'org123',
+        },
+      },
+    })
+
+    // Boots logged in with the persisted OAuth tokens exposed on the store.
+    expect(getOAuthTokensState(instance).getCurrent()).toMatchObject({accessToken: 'oauth-access'})
+
+    await logout(instance)
+
+    expect(getOAuthTokensState(instance).getCurrent()).toBeNull()
+    expect(getAuthState(instance).getCurrent()).toMatchObject({type: AuthStateType.LOGGED_OUT})
+    expect(map.get(OAUTH_TOKENS_KEY)).toBeUndefined()
+  })
+
   it('cleans up storage even if logout request fails', async () => {
     vi.mocked(getTokenFromStorage).mockReturnValue('token')
     const error = new Error('Logout request failed')

package/src/auth/logout.ts

@@ -57,6 +57,7 @@ export const logout = bindActionGlobally(authStore, async ({state, instance}) =>
     logger.info('User logged out, clearing stored tokens')
     state.set('logoutSuccess', {
       authState: {type: AuthStateType.LOGGED_OUT, isDestroyingSession: false},
+      oauthTokens: undefined,
     })
     storageArea?.removeItem(storageKey)
     storageArea?.removeItem(`${storageKey}_last_refresh`)