@sanity/sdk 2.18.0 → 3.0.0-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.18.0",
+  "version": "3.0.0-rc.1",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@sanity/bifur-client": "^1.0.0",
-    "@sanity/client": "^7.23.1",
+    "@sanity/client": "^7.23.2",
     "@sanity/comlink": "^4.0.1",
     "@sanity/diff-match-patch": "^3.2.0",
     "@sanity/diff-patch": "^6.0.0",
@@ -60,26 +60,26 @@
     "@sanity/message-protocol": "^0.23.0",
     "@sanity/mutate": "^0.18.1",
     "@sanity/telemetry": "^1.1.0",
-    "@sanity/types": "^6.2.0",
+    "@sanity/types": "^6.5.0",
     "groq": "3.88.1-typegen-experimental.0",
-    "groq-js": "^1.30.3",
+    "groq-js": "^2.0.0",
     "reselect": "^5.1.1",
     "rxjs": "^7.8.2",
     "zustand": "^5.0.13"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
-    "@sanity/pkg-utils": "^10.5.8",
+    "@sanity/pkg-utils": "^10.9.2",
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^10.6.0",
     "oxfmt": "^0.58.0",
     "rollup-plugin-visualizer": "^7.0.1",
     "typescript": "^6.0.3",
-    "vite": "^8.1.4",
+    "vite": "^8.1.5",
     "vitest": "^4.1.10",
-    "@repo/config-test": "0.0.1",
     "@repo/config-eslint": "0.0.0",
+    "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
     "@repo/tsconfig": "0.0.1",
     "@repo/package.bundle": "3.82.0"

package/src/_exports/_internal.ts

@@ -9,6 +9,17 @@ export {
 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
+export {
+  type CacheTag,
+  type CacheWriter,
+  defineFetcher,
+  defineMutation,
+  type Fetcher,
+  type FetcherDefinition,
+  type FetcherSnapshot,
+  type MutationDefinition,
+  type MutationResult,
+} from '../store/fetcherStore'
 export {getTelemetryManager, initTelemetry, trackHookMounted} from '../telemetry/initTelemetry'
 export {getUsersKey, parseUsersKey} from '../users/reducers' // only used for memoizing in React, not needed for actual functionality
 export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'

package/src/_exports/index.ts

@@ -5,6 +5,8 @@ import {type SanityProject as _SanityProject} from '@sanity/client'
  */
 export type SanityProject = _SanityProject
 
+export {checkPermissions} from '../access/checkPermissions'
+export {type AccessResourceType} from '../access/checkPermissions'
 export type {
   AgentGenerateOptions,
   AgentGenerateResult,
@@ -24,6 +26,44 @@ export {
   agentTransform,
   agentTranslate,
 } from '../agent/agentActions'
+export {
+  application,
+  applications,
+  deleteApplication,
+  updateApplication,
+} from '../applications/applications'
+export {
+  type Application,
+  type ApplicationAccess,
+  type ApplicationBase,
+  type ApplicationDeployment,
+  type ApplicationInclude,
+  type ApplicationInterface,
+  type ApplicationsOptions,
+  type ApplicationsResponse,
+  type ApplicationStudioConfig,
+  type ApplicationVisibility,
+  type ApplicationWorkspace,
+  type DeleteApplicationInput,
+  type DeletedResult,
+  type UpdateApplicationInput,
+} from '../applications/applications'
+export {
+  createUserApplication,
+  deleteUserApplication,
+  updateUserApplication,
+  userApplication,
+  userApplications,
+} from '../applications/userApplications'
+export {
+  type CreateUserApplicationInput,
+  type DeleteUserApplicationInput,
+  type UpdateUserApplicationInput,
+  type UserApplication,
+  type UserApplicationDeployment,
+  type UserApplicationsOptions,
+  type UserApplicationWriteFields,
+} from '../applications/userApplications'
 export {isStudioConfig} from '../auth/authMode'
 export {AuthStateType} from '../auth/authStateType'
 export {
@@ -179,20 +219,26 @@ export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../do
 export {getReleaseDocumentId} from '../document/processActions/releaseUtil'
 export type {FavoriteStatusResponse} from '../favorites/favorites'
 export {getFavoritesState, resolveFavoritesState} from '../favorites/favorites'
+export {installation, installations} from '../installations/installations'
+export {
+  type Installation,
+  type InstallationAccess,
+  type InstallationActiveConfig,
+  type InstallationBase,
+  type InstallationInclude,
+  type InstallationInterface,
+  type InstallationsOptions,
+  type InstallationsResponse,
+} from '../installations/installations'
+export {organization} from '../organization/organization'
 export {
-  getOrganizationState,
   type Organization,
   type OrganizationBase,
   type OrganizationMember,
   type OrganizationOptions,
-  resolveOrganization,
 } from '../organization/organization'
-export {
-  getOrganizationsState,
-  type Organizations,
-  type OrganizationsOptions,
-  resolveOrganizations,
-} from '../organizations/organizations'
+export {organizations} from '../organizations/organizations'
+export {type Organizations, type OrganizationsOptions} from '../organizations/organizations'
 export {getPresence} from '../presence/presenceStore'
 export type {
   DisconnectEvent,
@@ -214,20 +260,20 @@ export type {
   ValuePending,
 } from '../preview/types'
 export {type OrgVerificationResult} from '../project/organizationVerification'
+export {project} from '../project/project'
 export {
-  getProjectState,
   type Project,
   type ProjectBase,
   type ProjectMember,
   type ProjectMemberRole,
   type ProjectMetadata,
   type ProjectOptions,
-  resolveProject,
 } from '../project/project'
 export {getProjectionState} from '../projection/getProjectionState'
 export {resolveProjection} from '../projection/resolveProjection'
 export {type ProjectionValuePending, type ValidProjection} from '../projection/types'
-export {getProjectsState, type ProjectsOptions, resolveProjects} from '../projects/projects'
+export {projects} from '../projects/projects'
+export {type ProjectsOptions} from '../projects/projects'
 export {
   getQueryKey,
   getQueryState,
@@ -262,7 +308,6 @@ export {
 } from '../users/usersStore'
 export {type FetcherStore, type FetcherStoreState} from '../utils/createFetcherStore'
 export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'
-export {defineIntent, type Intent, type IntentFilter} from '../utils/defineIntent'
 export {getCorsErrorProjectId} from '../utils/getCorsErrorProjectId'
 export {isImportError} from '../utils/isImportError'
 export {CORE_SDK_VERSION} from '../version'

package/src/access/checkPermissions.test.ts

@@ -0,0 +1,55 @@
+import {type SanityClient} from '@sanity/client'
+import {of} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {checkPermissions} from './checkPermissions'
+
+vi.mock('../client/clientStore')
+
+describe('checkPermissions', () => {
+  let instance: SanityInstance
+  const request = vi.fn()
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    request.mockReset()
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of({observable: {request}} as unknown as SanityClient),
+    } as StateSource<SanityClient>)
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('checks permissions on the global client and unwraps the data envelope', async () => {
+    request.mockReturnValue(of({data: {'sanity.project.read': true}}))
+
+    const result = await checkPermissions.resolveState(instance, 'project', 'p1', [
+      'sanity.project.read',
+    ])
+
+    expect(result).toEqual({'sanity.project.read': true})
+    expect(getClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'v2025-07-11',
+      scope: 'global',
+    })
+    expect(request).toHaveBeenCalledWith({
+      uri: '/access/project/p1/user-permissions/me/check',
+      query: {permissions: ['sanity.project.read']},
+      tag: 'access.check',
+    })
+  })
+
+  it('does not create distinct cache entries for different permission orderings', async () => {
+    request.mockReturnValue(of({data: {a: true, b: false}}))
+
+    await checkPermissions.resolveState(instance, 'organization', 'org1', ['b', 'a'])
+    await checkPermissions.resolveState(instance, 'organization', 'org1', ['a', 'b'])
+
+    expect(request).toHaveBeenCalledTimes(1)
+  })
+})

package/src/access/checkPermissions.ts

@@ -0,0 +1,54 @@
+import {map, switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {defineFetcher} from '../store/fetcherStore'
+
+const API_VERSION = 'v2025-07-11'
+
+/**
+ * The resource types the Access API can scope a permission check to.
+ *
+ * @see https://www.sanity.io/docs/http-reference/access-api
+ * @public
+ */
+export type AccessResourceType =
+  | 'organization'
+  | 'project'
+  | 'media-library'
+  | 'canvas'
+  | 'dashboard'
+  | 'view'
+
+/**
+ * Fetcher checking whether the current user holds the given permissions on a
+ * resource (`GET /access/:resourceType/:resourceId/user-permissions/me/check`),
+ * on the shared fetcher cache. Resolves to a map of each requested permission
+ * to whether the user has it. The key sorts the permission list, so permission
+ * order doesn't create distinct cache entries.
+ *
+ * @see https://www.sanity.io/docs/http-reference/access-api
+ * @internal
+ */
+export const checkPermissions = defineFetcher<
+  [resourceType: AccessResourceType, resourceId: string, permissions: string[]],
+  Record<string, boolean>
+>({
+  name: 'checkPermissions',
+  getKey: (_instance, resourceType, resourceId, permissions) =>
+    `${resourceType}:${resourceId}:${[...permissions].sort().join(',')}`,
+  fetch: (instance) => (resourceType, resourceId, permissions) =>
+    getClientState(instance, {apiVersion: API_VERSION, scope: 'global'}).observable.pipe(
+      switchMap((client) =>
+        client.observable
+          .request<{data: Record<string, boolean>}>({
+            uri: `/access/${resourceType}/${resourceId}/user-permissions/me/check`,
+            query: {permissions},
+            tag: 'access.check',
+          })
+          .pipe(map((response) => response.data)),
+      ),
+    ),
+  tags: (_data, resourceType, resourceId) => [
+    {type: 'access', id: `${resourceType}:${resourceId}`},
+  ],
+})

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

@@ -0,0 +1,83 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {type FetcherSnapshot} from '../store/fetcherStore'
+import {
+  type Application,
+  application,
+  type ApplicationBase,
+  type ApplicationDeployment,
+  type ApplicationInclude,
+  type ApplicationInterface,
+  applications,
+  type ApplicationsResponse,
+  type ApplicationStudioConfig,
+} from './applications'
+
+const instance = {} as SanityInstance
+
+type ChildKeys = 'config' | 'activeDeployment'
+type DeploymentChildKeys = 'interfaces' | 'workspaces' | 'access'
+
+// Whether key `K` of `T` is optional, without an `{}`-based check.
+type KeyModifier<T, K extends keyof T> =
+  Pick<T, K> extends Required<Pick<T, K>> ? 'required' : 'optional'
+
+test('Application — no includes: only the base shape, no config or activeDeployment', () => {
+  expectTypeOf<Application>().toEqualTypeOf<ApplicationBase>()
+  expectTypeOf<Application<never>>().toEqualTypeOf<ApplicationBase>()
+  expectTypeOf<Extract<keyof Application, ChildKeys>>().toEqualTypeOf<never>()
+})
+
+test('Application — config.studio adds a required config.studio', () => {
+  expectTypeOf<
+    Application<'config.studio'>['config']['studio']
+  >().toEqualTypeOf<ApplicationStudioConfig>()
+  // mfManifest not requested → not present under config
+  expectTypeOf<
+    Extract<keyof Application<'config.studio'>['config'], 'mfManifest'>
+  >().toEqualTypeOf<never>()
+  // requesting only config does not pull in the deployment
+  expectTypeOf<
+    Extract<keyof Application<'config.studio'>, 'activeDeployment'>
+  >().toEqualTypeOf<never>()
+})
+
+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['mfManifest']>().toEqualTypeOf<unknown>()
+})
+
+test('Application — activeDeployment token adds the deployment summary, no children', () => {
+  expectTypeOf<
+    Application<'activeDeployment'>['activeDeployment']
+  >().toEqualTypeOf<ApplicationDeployment<'activeDeployment'> | null>()
+  type Deployment = NonNullable<Application<'activeDeployment'>['activeDeployment']>
+  expectTypeOf<Extract<keyof Deployment, DeploymentChildKeys>>().toEqualTypeOf<never>()
+})
+
+test('Application — a child token forces the deployment in and adds only that child', () => {
+  type Deployment = NonNullable<Application<'interfaces'>['activeDeployment']>
+  expectTypeOf<Deployment['interfaces']>().toEqualTypeOf<ApplicationInterface[]>()
+  expectTypeOf<Extract<keyof Deployment, 'workspaces' | 'access'>>().toEqualTypeOf<never>()
+})
+
+test('Application — a wide include array makes config and activeDeployment optional', () => {
+  type Wide = Application<ApplicationInclude>
+  expectTypeOf<KeyModifier<Wide, 'activeDeployment'>>().toEqualTypeOf<'optional'>()
+  expectTypeOf<KeyModifier<Wide, 'config'>>().toEqualTypeOf<'optional'>()
+})
+
+test('applications.resolveState — resolves the wide list envelope', () => {
+  expectTypeOf(
+    applications.resolveState(instance, {organizationId: 'org_1'}),
+  ).resolves.toEqualTypeOf<ApplicationsResponse<ApplicationInclude>>()
+})
+
+test('application.getState — exposes the snapshot envelope', () => {
+  expectTypeOf(application.getState(instance, 'app_1')).toEqualTypeOf<
+    StateSource<FetcherSnapshot<Application<ApplicationInclude>>>
+  >()
+})

package/src/applications/applications.test.ts

@@ -0,0 +1,130 @@
+import {type SanityClient} from '@sanity/client'
+import {of} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {defineMutation} from '../store/fetcherStore'
+import {application, applications, deleteApplication, updateApplication} from './applications'
+
+vi.mock('../client/clientStore')
+
+describe('applications', () => {
+  let instance: SanityInstance
+  const request = vi.fn()
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    request.mockReset()
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of({observable: {request}} as unknown as SanityClient),
+    } as StateSource<SanityClient>)
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('lists applications for an organization, serialising include as a sorted CSV', async () => {
+    const response = {nextCursor: null, data: [{id: 'app1'}]}
+    request.mockReturnValue(of(response))
+
+    const result = await applications.resolveState(instance, {
+      organizationId: 'org1',
+      include: ['workspaces', 'access'],
+      limit: 'none',
+    })
+
+    expect(result).toEqual(response)
+    expect(getClientState).toHaveBeenCalledWith(instance, {
+      apiVersion: 'vX',
+      scope: 'global',
+    })
+    expect(request).toHaveBeenCalledWith({
+      uri: '/applications',
+      query: {organizationId: 'org1', include: 'access,workspaces', limit: 'none'},
+      tag: 'applications.list',
+    })
+  })
+
+  it('fetches a single application by id', async () => {
+    const app = {id: 'app1', title: 'One'}
+    request.mockReturnValue(of(app))
+
+    const result = await application.resolveState(instance, 'app1')
+
+    expect(result).toEqual(app)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/applications/app1',
+      query: {},
+      tag: 'applications.get',
+    })
+  })
+
+  it('refetches the list when a mutation invalidates the LIST tag', async () => {
+    let n = 0
+    request.mockImplementation(() => of({nextCursor: null, data: [{id: `app-${++n}`}]}))
+
+    const source = applications.getState(instance, {organizationId: 'org1'})
+    const unsubscribe = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().status).toBe('success'))
+    expect(request).toHaveBeenCalledTimes(1)
+
+    const install = defineMutation<undefined, {ok: boolean}>({
+      name: 'test-install-application',
+      mutationFn: () => () => of({ok: true}),
+      invalidates: [{type: 'application', id: 'LIST'}],
+    })
+
+    const {invalidated} = await install(instance, undefined)
+    await invalidated
+
+    expect(request).toHaveBeenCalledTimes(2)
+    expect(source.getCurrent().data).toEqual({nextCursor: null, data: [{id: 'app-2'}]})
+    unsubscribe()
+  })
+
+  it('updates an application via PATCH and refetches the invalidated list', async () => {
+    request.mockImplementation((opts) => {
+      const {method} = opts as {method?: string}
+      return method === 'PATCH'
+        ? of({id: 'app1', title: 'New'})
+        : of({nextCursor: null, data: [{id: 'app1'}]})
+    })
+
+    const source = applications.getState(instance, {organizationId: 'org1'})
+    const unsubscribe = source.subscribe()
+    await vi.waitFor(() => expect(source.getCurrent().status).toBe('success'))
+
+    const {data, invalidated} = await updateApplication(instance, {
+      applicationId: 'app1',
+      title: 'New',
+    })
+    await invalidated
+
+    expect(data).toEqual({id: 'app1', title: 'New'})
+    expect(request).toHaveBeenCalledWith({
+      uri: '/applications/app1',
+      method: 'PATCH',
+      body: {title: 'New'},
+      tag: 'applications.update',
+    })
+    // initial list GET + PATCH + list refetch after invalidation
+    expect(request).toHaveBeenCalledTimes(3)
+    unsubscribe()
+  })
+
+  it('deletes an application via DELETE with no body', async () => {
+    request.mockReturnValue(of({deleted: true}))
+
+    const {data} = await deleteApplication(instance, {applicationId: 'app1'})
+
+    expect(data).toEqual({deleted: true})
+    expect(request).toHaveBeenCalledWith({
+      uri: '/applications/app1',
+      method: 'DELETE',
+      tag: 'applications.delete',
+    })
+  })
+})