@sanity/sdk 2.10.0 → 2.11.0

package/src/organization/organization.ts

@@ -0,0 +1,166 @@
+import {switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {createFetcherStore} from '../utils/createFetcherStore'
+
+const API_VERSION = 'v2025-02-19'
+
+/** @public */
+export interface OrganizationMember {
+  sanityUserId: string
+  isCurrentUser: boolean
+  user: {
+    id: string
+    displayName: string
+    familyName: string
+    givenName: string
+    middleName: string | null
+    imageUrl: string | null
+    email: string
+    loginProvider: string
+  }
+  roles: Array<{
+    name: string
+    title: string
+    description?: string
+  }>
+}
+
+/**
+ * The base fields returned from `/organizations/<id>` for every organization.
+ * @public
+ */
+export interface OrganizationBase {
+  id: string
+  name: string
+  slug: string | null
+  createdAt: string
+  createdByUserId: string
+  updatedAt: string
+  deletedAt: string | null
+  dashboardStatus: 'enabled' | 'disabled'
+  aiFeaturesStatus: 'enabled' | 'disabled'
+  mediaLibraryStatus: 'enabled' | 'disabled'
+  requestAccessStatus: 'allowed' | 'disabled'
+  telemetryConsentStatus: 'allowed' | 'msa_denied' | 'customer_denied'
+  oauthAppsStatus: 'allowed' | 'blocked'
+  defaultRoleName: string
+  domains: string[] | null
+}
+
+/** @public */
+export interface OrganizationOptions<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> {
+  includeMembers?: IncludeMembers
+  includeFeatures?: IncludeFeatures
+  organizationId: string
+}
+
+/**
+ * An `Organization` with `members` and/or `features` conditionally included
+ * based on the query options used to fetch it.
+ * @public
+ */
+export type Organization<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> = OrganizationBase &
+  // `boolean extends T` is non-distributive — true only when T is the wide
+  // `boolean`, in which case the field is optional. Literal `true`/`false`
+  // fall through to the strict branch.
+  (boolean extends IncludeMembers
+    ? {members?: OrganizationMember[]}
+    : IncludeMembers extends true
+      ? {members: OrganizationMember[]}
+      : unknown) &
+  (boolean extends IncludeFeatures
+    ? {features?: string[]}
+    : IncludeFeatures extends true
+      ? {features: string[]}
+      : unknown)
+
+function resolveOrganizationId(options?: OrganizationOptions<boolean, boolean>) {
+  const organizationId = options?.organizationId
+  if (!organizationId) {
+    throw new Error('An organizationId is required to use the organization API.')
+  }
+  return organizationId
+}
+
+function normalizeOrganizationOptions(options?: OrganizationOptions<boolean, boolean>) {
+  return {
+    includeMembers: options?.includeMembers ?? false,
+    includeFeatures: options?.includeFeatures ?? false,
+  }
+}
+
+/** @internal */
+export function getOrganizationCacheKey(
+  _instance: SanityInstance,
+  options?: OrganizationOptions<boolean, boolean>,
+): string {
+  const organizationId = resolveOrganizationId(options)
+  const {includeMembers, includeFeatures} = normalizeOrganizationOptions(options)
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  return `organization:${organizationId}${membersKey}${featuresKey}`
+}
+
+const organization = createFetcherStore({
+  name: 'Organization',
+  getKey: getOrganizationCacheKey,
+  fetcher: (instance) => (options?: OrganizationOptions<boolean, boolean>) => {
+    const organizationId = resolveOrganizationId(options)
+
+    return getClientState(instance, {
+      apiVersion: API_VERSION,
+      scope: 'global',
+    }).observable.pipe(
+      switchMap((client) => {
+        const normalized = normalizeOrganizationOptions(options)
+        const query = Object.fromEntries(
+          Object.entries(normalized)
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => [key, String(value)]),
+        )
+
+        return client.observable.request({
+          uri: `/organizations/${organizationId}`,
+          query,
+          tag: 'organization.get',
+        })
+      }),
+    )
+  },
+})
+
+/**
+ * Public signature for the organization state source. The conditional generics
+ * cannot flow through `BoundStoreAction`, so we declare the signature here
+ * and assign the (already-correct) runtime function to it.
+ */
+type GetOrganizationState = <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  instance: SanityInstance,
+  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
+) => StateSource<Organization<IncludeMembers, IncludeFeatures> | undefined>
+
+type ResolveOrganization = <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  instance: SanityInstance,
+  options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
+) => Promise<Organization<IncludeMembers, IncludeFeatures>>
+
+/** @public */
+export const getOrganizationState: GetOrganizationState = organization.getState
+
+/** @public */
+export const resolveOrganization: ResolveOrganization = organization.resolveState

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

@@ -0,0 +1,77 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type OrganizationMember} from '../organization/organization'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {getOrganizationsState, type Organizations, resolveOrganizations} from './organizations'
+
+const instance = {} as SanityInstance
+
+test('resolveOrganizations — default call: bare list shape', () => {
+  expectTypeOf(resolveOrganizations(instance)).resolves.toEqualTypeOf<Organizations<false, false>>()
+})
+
+test('resolveOrganizations — includeMembers: true narrows the generic', () => {
+  expectTypeOf(resolveOrganizations(instance, {includeMembers: true})).resolves.toEqualTypeOf<
+    Organizations<true, false>
+  >()
+})
+
+test('resolveOrganizations — includeFeatures: true narrows the generic', () => {
+  expectTypeOf(resolveOrganizations(instance, {includeFeatures: true})).resolves.toEqualTypeOf<
+    Organizations<false, true>
+  >()
+})
+
+test('resolveOrganizations — both flags true', () => {
+  expectTypeOf(
+    resolveOrganizations(instance, {includeMembers: true, includeFeatures: true}),
+  ).resolves.toEqualTypeOf<Organizations<true, true>>()
+})
+
+test('resolveOrganizations — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void resolveOrganizations(instance, {includeMembers: 'yes'})
+})
+
+test('resolveOrganizations — includeImplicitMemberships does not change the data shape', () => {
+  expectTypeOf(
+    resolveOrganizations(instance, {includeImplicitMemberships: true}),
+  ).resolves.toEqualTypeOf<Organizations<false, false>>()
+})
+
+test('Organizations — list items expose the documented subset of keys', () => {
+  type Keys = keyof Organizations<false, false>[number]
+  expectTypeOf<Keys>().toEqualTypeOf<
+    | 'id'
+    | 'name'
+    | 'slug'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'defaultRoleName'
+    | 'dashboardStatus'
+    | 'aiFeaturesStatus'
+  >()
+})
+
+test('Organizations<true, false>[number] exposes members[]', () => {
+  type Item = Organizations<true, false>[number]
+  expectTypeOf<Item['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('Organizations<false, true>[number] exposes features[]', () => {
+  type Item = Organizations<false, true>[number]
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[]>()
+})
+
+test('Organizations<true, true>[number] exposes both members[] and features[]', () => {
+  type Item = Organizations<true, true>[number]
+  expectTypeOf<Item['members']>().toEqualTypeOf<OrganizationMember[]>()
+  expectTypeOf<Item['features']>().toEqualTypeOf<string[]>()
+})
+
+test('getOrganizationsState — default call returns the bare-base StateSource', () => {
+  expectTypeOf(getOrganizationsState(instance)).toEqualTypeOf<
+    StateSource<Organizations<false, false> | undefined>
+  >()
+})

package/src/organizations/organizations.test.ts

@@ -0,0 +1,150 @@
+import {type SanityClient} from '@sanity/client'
+import {of} from 'rxjs'
+import {afterEach, beforeEach, describe, it} from 'vitest'
+
+import {getClientState} from '../client/clientStore'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {getOrganizationsCacheKey, resolveOrganizations} from './organizations'
+
+vi.mock('../client/clientStore')
+
+describe('organizations', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('calls `client.observable.request` against `/organizations` and returns the result', async () => {
+    const organizations = [{id: 'org_1'}, {id: 'org_2'}]
+    const request = vi.fn().mockReturnValue(of(organizations))
+
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    const result = await resolveOrganizations(instance)
+    expect(result).toEqual(organizations)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/organizations',
+      query: {
+        includeImplicitMemberships: 'false',
+        includeMembers: 'false',
+        includeFeatures: 'false',
+      },
+      tag: 'organizations.get',
+    })
+  })
+
+  it('serializes query params (booleans → strings) and respects flags', async () => {
+    const request = vi.fn().mockReturnValue(of([]))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await resolveOrganizations(instance, {
+      includeMembers: true,
+      includeFeatures: true,
+      includeImplicitMemberships: true,
+    })
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/organizations',
+      query: {
+        includeImplicitMemberships: 'true',
+        includeMembers: 'true',
+        includeFeatures: 'true',
+      },
+      tag: 'organizations.get',
+    })
+  })
+})
+
+describe('organizations cache key generation', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('default call excludes all segments (all flags default-false)', () => {
+    expect(getOrganizationsCacheKey(instance)).toBe('organizations')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getOrganizationsCacheKey(instance)).toBe(
+      getOrganizationsCacheKey(instance, {
+        includeMembers: false,
+        includeFeatures: false,
+        includeImplicitMemberships: false,
+      }),
+    )
+  })
+
+  it('explicit includeMembers: true appends :members', () => {
+    expect(getOrganizationsCacheKey(instance, {includeMembers: true})).toBe('organizations:members')
+  })
+
+  it('explicit includeFeatures: true appends :features', () => {
+    expect(getOrganizationsCacheKey(instance, {includeFeatures: true})).toBe(
+      'organizations:features',
+    )
+  })
+
+  it('explicit includeImplicitMemberships: true appends :implicit', () => {
+    expect(getOrganizationsCacheKey(instance, {includeImplicitMemberships: true})).toBe(
+      'organizations:implicit',
+    )
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getOrganizationsCacheKey(instance, {
+        includeMembers: true,
+        includeFeatures: true,
+        includeImplicitMemberships: true,
+      }),
+    ).toBe('organizations:members:features:implicit')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getOrganizationsCacheKey(instance),
+      getOrganizationsCacheKey(instance, {includeMembers: true}),
+      getOrganizationsCacheKey(instance, {includeFeatures: true}),
+      getOrganizationsCacheKey(instance, {includeImplicitMemberships: true}),
+      getOrganizationsCacheKey(instance, {includeMembers: true, includeFeatures: true}),
+      getOrganizationsCacheKey(instance, {
+        includeMembers: true,
+        includeImplicitMemberships: true,
+      }),
+      getOrganizationsCacheKey(instance, {
+        includeFeatures: true,
+        includeImplicitMemberships: true,
+      }),
+      getOrganizationsCacheKey(instance, {
+        includeMembers: true,
+        includeFeatures: true,
+        includeImplicitMemberships: true,
+      }),
+    ])
+    expect(keys.size).toBe(8)
+  })
+})

package/src/organizations/organizations.ts

@@ -0,0 +1,132 @@
+import {switchMap} from 'rxjs'
+
+import {getClientState} from '../client/clientStore'
+import {
+  type OrganizationBase,
+  type OrganizationMember,
+  type OrganizationOptions,
+} from '../organization/organization'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {createFetcherStore} from '../utils/createFetcherStore'
+
+const API_VERSION = 'v2025-02-19'
+
+/**
+ * The list shape returned from `/organizations`, with `members` and/or
+ * `features` conditionally included based on the query options used.
+ * @public
+ */
+export type Organizations<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> = (Pick<
+  OrganizationBase,
+  | 'id'
+  | 'name'
+  | 'slug'
+  | 'createdAt'
+  | 'updatedAt'
+  | 'defaultRoleName'
+  | 'dashboardStatus'
+  | 'aiFeaturesStatus'
+> &
+  // `boolean extends T` is non-distributive — true only when T is the wide
+  // `boolean`, in which case the field is optional. Literal `true`/`false`
+  // fall through to the strict branch.
+  (boolean extends IncludeMembers
+    ? {members?: OrganizationMember[]}
+    : IncludeMembers extends true
+      ? {members: OrganizationMember[]}
+      : unknown) &
+  (boolean extends IncludeFeatures
+    ? {features?: string[]}
+    : IncludeFeatures extends true
+      ? {features: string[]}
+      : unknown))[]
+
+/** @public */
+export interface OrganizationsOptions<
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+> extends Omit<OrganizationOptions<IncludeMembers, IncludeFeatures>, 'organizationId'> {
+  /**
+   * When `true`, includes organisations the user has access to via
+   * project-level grants, not just direct organisation memberships.
+   */
+  includeImplicitMemberships?: boolean
+}
+
+function normalizeOrganizationOptions(options?: OrganizationsOptions<boolean, boolean>) {
+  return {
+    includeImplicitMemberships: options?.includeImplicitMemberships ?? false,
+    includeMembers: options?.includeMembers ?? false,
+    includeFeatures: options?.includeFeatures ?? false,
+  }
+}
+
+/** @internal */
+export function getOrganizationsCacheKey(
+  _instance: SanityInstance,
+  options?: OrganizationsOptions<boolean, boolean>,
+): string {
+  const {includeMembers, includeFeatures, includeImplicitMemberships} =
+    normalizeOrganizationOptions(options)
+  const membersKey = includeMembers ? ':members' : ''
+  const featuresKey = includeFeatures ? ':features' : ''
+  const implicitKey = includeImplicitMemberships ? ':implicit' : ''
+  return `organizations${membersKey}${featuresKey}${implicitKey}`
+}
+
+const organizations = createFetcherStore({
+  name: 'Organizations',
+  getKey: getOrganizationsCacheKey,
+  fetcher: (instance) => (options?: OrganizationsOptions<boolean, boolean>) => {
+    return getClientState(instance, {
+      apiVersion: API_VERSION,
+      scope: 'global',
+    }).observable.pipe(
+      switchMap((client) => {
+        const normalized = normalizeOrganizationOptions(options)
+        const query = Object.fromEntries(
+          Object.entries(normalized)
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => [key, String(value)]),
+        )
+
+        return client.observable.request({
+          uri: `/organizations`,
+          query,
+          tag: 'organizations.get',
+        })
+      }),
+    )
+  },
+})
+
+/**
+ * Public signature for the organization state source. The conditional generics
+ * cannot flow through `BoundStoreAction`, so we declare the signature here
+ * and assign the (already-correct) runtime function to it.
+ */
+type GetOrganizationsState = <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  instance: SanityInstance,
+  options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
+) => StateSource<Organizations<IncludeMembers, IncludeFeatures> | undefined>
+
+type ResolveOrganizations = <
+  IncludeMembers extends boolean = false,
+  IncludeFeatures extends boolean = false,
+>(
+  instance: SanityInstance,
+  options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
+) => Promise<Organizations<IncludeMembers, IncludeFeatures>>
+
+/** @public */
+export const getOrganizationsState: GetOrganizationsState = organizations.getState
+
+/** @public */
+export const resolveOrganizations: ResolveOrganizations = organizations.resolveState

package/src/presence/presenceStore.test.ts

@@ -1,6 +1,6 @@
 import {type SanityClient} from '@sanity/client'
-import {delay, firstValueFrom, of, Subject} from 'rxjs'
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+import {delay, firstValueFrom, type Observable, of, Subject} from 'rxjs'
+import {afterEach, beforeEach, describe, expect, it, type Mock, vi} from 'vitest'
 
 import {getTokenState} from '../auth/authStore'
 import {getClient} from '../client/clientStore'
@@ -9,7 +9,7 @@ import {type SanityUser} from '../users/types'
 import {getUserState} from '../users/usersStore'
 import {createBifurTransport} from './bifurTransport'
 import {getPresence} from './presenceStore'
-import {type PresenceLocation, type TransportEvent} from './types'
+import {type PresenceLocation, type TransportEvent, type TransportMessage} from './types'
 
 vi.mock('../auth/authStore')
 vi.mock('../client/clientStore')
@@ -21,8 +21,8 @@ describe('presenceStore', () => {
   let mockClient: SanityClient
   let mockTokenState: Subject<string | null>
   let mockIncomingEvents: Subject<TransportEvent>
-  let mockDispatchMessage: ReturnType<typeof vi.fn>
-  let mockGetUserState: ReturnType<typeof vi.fn>
+  let mockDispatchMessage: Mock<(message: TransportMessage) => Observable<void>>
+  let mockGetUserState: Mock<typeof getUserState>
 
   const mockUser: SanityUser = {
     sanityUserId: 'u123',

package/src/preview/previewProjectionUtils.ts

@@ -2,7 +2,7 @@ import {type SanityClient} from '@sanity/client'
 import {createImageUrlBuilder} from '@sanity/image-url'
 
 import {getClient} from '../client/clientStore'
-import {type DocumentResource, isDatasetResource} from '../config/sanityConfig'
+import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
 import {isObject} from '../utils/object'
 import {SUBTITLE_CANDIDATES, TITLE_CANDIDATES} from './previewConstants'
@@ -80,8 +80,7 @@ export function transformProjectionToPreview(
   // Get a client for the resource (if provided) or use the instance config
   const client = getClient(instance, {
     apiVersion: API_VERSION,
-    // TODO: remove in v3 when we're ready for everything to be queried via resource
-    resource: resource && !isDatasetResource(resource) ? resource : undefined,
+    resource,
   })
 
   return {

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

@@ -0,0 +1,93 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {
+  getProjectState,
+  type Project,
+  type ProjectBase,
+  type ProjectMember,
+  resolveProject,
+} from './project'
+
+const instance = {} as SanityInstance
+
+test('resolveProject — default call: members and features both included by default', () => {
+  expectTypeOf(resolveProject(instance)).resolves.toEqualTypeOf<Project<true, true>>()
+  type Result = Awaited<ReturnType<typeof resolveProject<true, true>>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<ProjectMember[]>()
+})
+
+test('resolveProject — includeMembers: false drops members from the type', () => {
+  expectTypeOf(resolveProject(instance, {includeMembers: false})).resolves.toEqualTypeOf<
+    Project<false, true>
+  >()
+})
+
+test('resolveProject — includeFeatures: false drops features from the type', () => {
+  expectTypeOf(resolveProject(instance, {includeFeatures: false})).resolves.toEqualTypeOf<
+    Project<true, false>
+  >()
+})
+
+test('resolveProject — both flags false → bare base shape', () => {
+  expectTypeOf(
+    resolveProject(instance, {includeMembers: false, includeFeatures: false}),
+  ).resolves.toEqualTypeOf<Project<false, false>>()
+  type Result = Awaited<ReturnType<typeof resolveProject<false, false>>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('resolveProject — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void resolveProject(instance, {includeMembers: 'yes'})
+})
+
+test('resolveProject — projectId alone does not change the data shape', () => {
+  expectTypeOf(resolveProject(instance, {projectId: 'p'})).resolves.toEqualTypeOf<
+    Project<true, true>
+  >()
+})
+
+test('resolveProject — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(resolveProject(instance, {includeMembers})).resolves.toEqualTypeOf<
+    Project<boolean, true>
+  >()
+})
+
+test('getProjectState — default call returns members + features StateSource', () => {
+  expectTypeOf(getProjectState(instance)).toEqualTypeOf<
+    StateSource<Project<true, true> | undefined>
+  >()
+})
+
+test('getProjectState — both flags false narrows to the bare base shape', () => {
+  expectTypeOf(
+    getProjectState(instance, {includeMembers: false, includeFeatures: false}),
+  ).toEqualTypeOf<StateSource<Project<false, false> | undefined>>()
+})
+
+test('Project — wide boolean for IncludeMembers makes members optional', () => {
+  expectTypeOf<Project<boolean, true>>().toEqualTypeOf<
+    ProjectBase & {members?: ProjectMember[]} & {features: string[]}
+  >()
+  expectTypeOf<Pick<Project<boolean, true>, 'members'>>().toEqualTypeOf<{
+    members?: ProjectMember[]
+  }>()
+})
+
+test('Project — wide boolean for IncludeFeatures makes features optional', () => {
+  expectTypeOf<Project<true, boolean>>().toEqualTypeOf<
+    ProjectBase & {members: ProjectMember[]} & {features?: string[]}
+  >()
+  expectTypeOf<Pick<Project<true, boolean>, 'features'>>().toEqualTypeOf<{
+    features?: string[]
+  }>()
+})
+
+test('Project — both wide booleans make both fields optional', () => {
+  expectTypeOf<Project<boolean, boolean>>().toEqualTypeOf<
+    ProjectBase & {members?: ProjectMember[]} & {features?: string[]}
+  >()
+})