@sanity/sdk 2.10.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "private": false,
   "description": "Sanity SDK",
   "keywords": [
@@ -61,7 +61,7 @@
     "@sanity/telemetry": "^1.1.0",
     "@sanity/types": "^5.2.0",
     "groq": "3.88.1-typegen-experimental.0",
-    "groq-js": "^1.19.0",
+    "groq-js": "^1.30.1",
     "reselect": "^5.1.1",
     "rxjs": "^7.8.2",
     "zustand": "^5.0.12"
@@ -70,21 +70,19 @@
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/pkg-utils": "^8.1.29",
     "@sanity/prettier-config": "^1.0.6",
-    "@vitest/coverage-v8": "3.2.4",
+    "@types/node": "^22.19.1",
+    "@vitest/coverage-v8": "4.1.5",
     "eslint": "^9.22.0",
     "prettier": "^3.7.3",
     "rollup-plugin-visualizer": "^5.14.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.0",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.4",
     "@repo/config-eslint": "0.0.0",
-    "@repo/tsconfig": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
-    "@repo/config-test": "0.0.1"
-  },
-  "engines": {
-    "node": ">=20.19"
+    "@repo/tsconfig": "0.0.1"
   },
   "publishConfig": {
     "access": "public"

package/src/_exports/_internal.ts

@@ -12,3 +12,4 @@ export {getQueryKey, parseQueryKey} from '../query/queryStore' // only used for
 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'
+export {isDeepEqual, pickProperties} from '../utils/object'

package/src/_exports/index.ts

@@ -157,6 +157,20 @@ export {type JsonMatch} from '../document/patchOperations'
 export {type DocumentPermissionsResult, type PermissionDeniedReason} from '../document/permissions'
 export type {FavoriteStatusResponse} from '../favorites/favorites'
 export {getFavoritesState, resolveFavoritesState} from '../favorites/favorites'
+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 {getPresence} from '../presence/presenceStore'
 export type {
   DisconnectEvent,
@@ -178,11 +192,20 @@ export type {
   ValuePending,
 } from '../preview/types'
 export {type OrgVerificationResult} from '../project/organizationVerification'
-export {getProjectState, resolveProject} 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, resolveProjects} from '../projects/projects'
+export {getProjectsState, type ProjectsOptions, resolveProjects} from '../projects/projects'
 export {
   getQueryKey,
   getQueryState,

package/src/agent/agentActions.ts

@@ -2,6 +2,7 @@ import {type SanityClient} from '@sanity/client'
 import {from, Observable, switchMap} from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
+import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
 
 const API_VERSION = 'vX'
@@ -58,12 +59,11 @@ export type AgentPatchResult = Awaited<ReturnType<SanityClient['agent']['action'
 export function agentGenerate(
   instance: SanityInstance,
   options: AgentGenerateOptions,
+  resource?: DocumentResource,
 ): 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)))
+  return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    switchMap((client) => client.observable.agent.action.generate(options)),
+  )
 }
 
 /**
@@ -76,12 +76,11 @@ export function agentGenerate(
 export function agentTransform(
   instance: SanityInstance,
   options: AgentTransformOptions,
+  resource?: DocumentResource,
 ): 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)))
+  return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    switchMap((client) => client.observable.agent.action.transform(options)),
+  )
 }
 
 /**
@@ -94,12 +93,11 @@ export function agentTransform(
 export function agentTranslate(
   instance: SanityInstance,
   options: AgentTranslateOptions,
+  resource?: DocumentResource,
 ): 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)))
+  return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    switchMap((client) => client.observable.agent.action.translate(options)),
+  )
 }
 
 /**
@@ -112,12 +110,11 @@ export function agentTranslate(
 export function agentPrompt(
   instance: SanityInstance,
   options: AgentPromptOptions,
+  resource?: DocumentResource,
 ): 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))))
+  return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    switchMap((client) => from(client.agent.action.prompt(options))),
+  )
 }
 
 /**
@@ -130,10 +127,9 @@ export function agentPrompt(
 export function agentPatch(
   instance: SanityInstance,
   options: AgentPatchOptions,
+  resource?: DocumentResource,
 ): 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))))
+  return getClientState(instance, {apiVersion: API_VERSION, resource}).observable.pipe(
+    switchMap((client) => from(client.agent.action.patch(options))),
+  )
 }

package/src/client/clientStore.test.ts

@@ -191,29 +191,7 @@ describe('clientStore', () => {
   })
 
   describe('resource handling', () => {
-    it('should create client when resource is provided', () => {
-      const client = getClient(instance, {
-        apiVersion: '2024-11-12',
-        resource: {projectId: 'source-project', dataset: 'source-dataset'},
-      })
-
-      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
-        expect.objectContaining({
-          apiVersion: '2024-11-12',
-          resource: {type: 'dataset', id: 'source-project.source-dataset'},
-        }),
-      )
-      // Client should be projectless - no projectId/dataset in config
-      expect(client.config()).not.toHaveProperty('projectId')
-      expect(client.config()).not.toHaveProperty('dataset')
-      expect(client.config()).toEqual(
-        expect.objectContaining({
-          resource: {type: 'dataset', id: 'source-project.source-dataset'},
-        }),
-      )
-    })
-
-    it('should create resource when resource has array resourceId and be projectless', () => {
+    it('should create resource when media library resource is provided and be projectless', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
         resource: {mediaLibraryId: 'media-lib-123'},
@@ -257,38 +235,24 @@ describe('clientStore', () => {
       )
     })
 
-    it('should create projectless client when resource is provided, ignoring instance config', () => {
+    it('should transform dataset resource to project-based config for now', () => {
       const client = getClient(instance, {
         apiVersion: '2024-11-12',
         resource: {projectId: 'source-project', dataset: 'source-dataset'},
       })
 
-      // Client should be projectless - resource takes precedence, instance config is ignored
-      expect(client.config()).not.toHaveProperty('projectId')
-      expect(client.config()).not.toHaveProperty('dataset')
-      expect(client.config()).toEqual(
+      expect(vi.mocked(createClient)).toHaveBeenCalledWith(
         expect.objectContaining({
-          resource: {type: 'dataset', id: 'source-project.source-dataset'},
+          projectId: 'source-project',
+          dataset: 'source-dataset',
         }),
       )
-    })
-
-    it('should warn when both resource and explicit projectId/dataset are provided', () => {
-      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
-      const client = getClient(instance, {
-        apiVersion: '2024-11-12',
-        resource: {projectId: 'source-project', dataset: 'source-dataset'},
-        projectId: 'explicit-project',
-        dataset: 'explicit-dataset',
-      })
-
-      expect(consoleSpy).toHaveBeenCalledWith(
-        'Both resource and explicit projectId/dataset are provided. The resource will be used and projectId/dataset will be ignored.',
+      expect(client.config()).toEqual(
+        expect.objectContaining({
+          projectId: 'source-project',
+          dataset: 'source-dataset',
+        }),
       )
-      // Client should still be projectless despite explicit projectId/dataset
-      expect(client.config()).not.toHaveProperty('projectId')
-      expect(client.config()).not.toHaveProperty('dataset')
-      consoleSpy.mockRestore()
     })
 
     it('should create different clients for different resources', () => {

package/src/client/clientStore.ts

@@ -178,24 +178,23 @@ export const getClient = bindActionGlobally(
 
     const tokenFromState = state.get().token
     const {clients, authMethod} = state.get()
+    let projectId = options.projectId ?? instance.config.projectId
+    let dataset = options.dataset ?? instance.config.dataset
 
     let resource: ClientConfig['resource'] | undefined
 
     if (options.resource) {
-      if (isDatasetResource(options.resource)) {
-        resource = {
-          type: 'dataset',
-          id: `${options.resource.projectId}.${options.resource.dataset}`,
-        }
-      } else if (isMediaLibraryResource(options.resource)) {
+      if (isMediaLibraryResource(options.resource)) {
         resource = {type: 'media-library', id: options.resource.mediaLibraryId}
       } else if (isCanvasResource(options.resource)) {
         resource = {type: 'canvas', id: options.resource.canvasId}
+      } else if (isDatasetResource(options.resource)) {
+        // use project-based routes for datasets to avoid existing CORS and Studio auth cookie issues
+        projectId = options.resource.projectId
+        dataset = options.resource.dataset
       }
     }
 
-    const projectId = options.projectId ?? instance.config.projectId
-    const dataset = options.dataset ?? instance.config.dataset
     const apiHost = options.apiHost ?? instance.config.auth?.apiHost ?? getStagingApiHost()
 
     const effectiveOptions: ClientConfig & {apiVersion: string} = {
@@ -213,12 +212,6 @@ export const getClient = bindActionGlobally(
     // The client code itself will ignore the non-resource config, so we do this to prevent confusing the user.
     // (ref: https://github.com/sanity-io/client/blob/5c23f81f5ab93a53f5b22b39845c867988508d84/src/data/dataMethods.ts#L691)
     if (resource) {
-      if (options.projectId || options.dataset) {
-        // eslint-disable-next-line no-console
-        console.warn(
-          'Both resource and explicit projectId/dataset are provided. The resource will be used and projectId/dataset will be ignored.',
-        )
-      }
       delete effectiveOptions.projectId
       delete effectiveOptions.dataset
     }

package/src/comlink/node/actions/getOrCreateNode.test.ts

@@ -27,14 +27,17 @@ describe('getOrCreateNode', () => {
     dataset: 'test-dataset',
   })
   let state: ReturnType<typeof createStoreState<ComlinkNodeState>>
-  let mockNode: Partial<Node<WindowMessage, FrameMessage>> & {
+  let mockNode: {
     start: ReturnType<typeof vi.fn>
     stop: ReturnType<typeof vi.fn>
+    onStatus: ReturnType<typeof vi.fn>
   }
 
   beforeEach(() => {
     mockNode = {start: vi.fn(), stop: vi.fn(), onStatus: vi.fn()}
-    vi.mocked(comlink.createNode).mockReturnValue(mockNode as Node<WindowMessage, FrameMessage>)
+    vi.mocked(comlink.createNode).mockReturnValue(
+      mockNode as unknown as Node<WindowMessage, FrameMessage>,
+    )
     state = createStoreState<ComlinkNodeState>({nodes: new Map(), subscriptions: new Map()})
     vi.clearAllMocks()
   })

package/src/comlink/node/actions/releaseNode.test.ts

@@ -15,7 +15,7 @@ const nodeConfig = {
 describe('releaseNode', () => {
   let instance: SanityInstance
   let state: ReturnType<typeof createStoreState<ComlinkNodeState>>
-  let mockNode: Partial<Node<WindowMessage, FrameMessage>> & {
+  let mockNode: {
     start: ReturnType<typeof vi.fn>
     stop: ReturnType<typeof vi.fn>
     onStatus: ReturnType<typeof vi.fn>
@@ -39,7 +39,7 @@ describe('releaseNode', () => {
     // Set up a node in the state
     const nodes = new Map()
     nodes.set('test-node', {
-      node: mockNode as Node<WindowMessage, FrameMessage>,
+      node: mockNode as unknown as Node<WindowMessage, FrameMessage>,
       options: nodeConfig,
     })
     state.set('setup', {nodes})
@@ -58,7 +58,7 @@ describe('releaseNode', () => {
     const statusUnsub = vi.fn()
     const nodes = new Map()
     nodes.set('test-node', {
-      node: mockNode as Node<WindowMessage, FrameMessage>,
+      node: mockNode as unknown as Node<WindowMessage, FrameMessage>,
       options: nodeConfig,
       statusUnsub,
     })

package/src/config/sanityConfig.ts

@@ -125,7 +125,6 @@ export interface DocumentHandle<
 export interface SanityConfig extends DatasetHandle, PerspectiveHandle {
   /**
    * Authentication configuration for the instance
-   * @remarks Merged with parent configurations when using createChild
    */
   auth?: AuthConfig
   /**

package/src/document/documentStore.ts

@@ -396,8 +396,7 @@ const subscribeToAppliedAndSubmitNextTransaction = ({
       withLatestFrom(
         getClientState(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,
         }).observable,
       ),
       concatMap(([outgoing, client]) => {
@@ -520,11 +519,7 @@ const subscribeToClientAndFetchDatasetAcl = ({
   state,
   key: {resource},
 }: StoreContext<DocumentStoreState, BoundResourceKey>) => {
-  const clientOptions: ClientOptions = {apiVersion: API_VERSION}
-  // TODO: remove in v3 when we're ready for everything to be queried via resource
-  if (resource && !isDatasetResource(resource)) {
-    clientOptions.resource = resource
-  }
+  const clientOptions: ClientOptions = {apiVersion: API_VERSION, resource}
 
   let uri: string
   if (resource && isDatasetResource(resource)) {

package/src/document/sharedListener.ts

@@ -14,7 +14,7 @@ import {
 } from 'rxjs'
 
 import {getClientState} from '../client/clientStore'
-import {type DocumentResource, isDatasetResource} from '../config/sanityConfig'
+import {type DocumentResource} from '../config/sanityConfig'
 import {type SanityInstance} from '../store/createSanityInstance'
 
 const API_VERSION = 'v2025-05-06'
@@ -31,8 +31,7 @@ export function createSharedListener(
   const dispose$ = new Subject<void>()
   const events$ = getClientState(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,
   }).observable.pipe(
     switchMap((client) =>
       // TODO: it seems like the client.listen method is not emitting disconnected
@@ -72,8 +71,7 @@ export function createFetchDocument(instance: SanityInstance, resource?: Documen
   return function (documentId: string): Observable<SanityDocument | null> {
     return getClientState(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,
     }).observable.pipe(
       switchMap((client) => {
         // creates a observable request to the /doc/{documentId} endpoint for a given document id

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

@@ -0,0 +1,102 @@
+import {expectTypeOf, test} from 'vitest'
+
+import {type SanityInstance} from '../store/createSanityInstance'
+import {type StateSource} from '../store/createStateSourceAction'
+import {
+  getOrganizationState,
+  type Organization,
+  type OrganizationBase,
+  type OrganizationMember,
+  resolveOrganization,
+} from './organization'
+
+const instance = {} as SanityInstance
+
+test('resolveOrganization — default call: members and features both omitted by default', () => {
+  expectTypeOf(resolveOrganization(instance, {organizationId: 'org_1'})).resolves.toEqualTypeOf<
+    Organization<false, false>
+  >()
+  type Result = Awaited<ReturnType<typeof resolveOrganization<false, false>>>
+  expectTypeOf<Result['id']>().toEqualTypeOf<string>()
+})
+
+test('resolveOrganization — includeMembers: true adds members to the type', () => {
+  expectTypeOf(
+    resolveOrganization(instance, {organizationId: 'org_1', includeMembers: true}),
+  ).resolves.toEqualTypeOf<Organization<true, false>>()
+  type Result = Awaited<ReturnType<typeof resolveOrganization<true, false>>>
+  expectTypeOf<Result['members']>().toEqualTypeOf<OrganizationMember[]>()
+})
+
+test('resolveOrganization — includeFeatures: true adds features to the type', () => {
+  expectTypeOf(
+    resolveOrganization(instance, {organizationId: 'org_1', includeFeatures: true}),
+  ).resolves.toEqualTypeOf<Organization<false, true>>()
+})
+
+test('resolveOrganization — both flags true → both arrays present', () => {
+  expectTypeOf(
+    resolveOrganization(instance, {
+      organizationId: 'org_1',
+      includeMembers: true,
+      includeFeatures: true,
+    }),
+  ).resolves.toEqualTypeOf<Organization<true, true>>()
+})
+
+test('resolveOrganization — rejects non-boolean flag values', () => {
+  // @ts-expect-error — includeMembers must be a boolean
+  void resolveOrganization(instance, {organizationId: 'org_1', includeMembers: 'yes'})
+})
+
+test('resolveOrganization — requires organizationId', () => {
+  // @ts-expect-error — organizationId is required
+  void resolveOrganization(instance, {})
+})
+
+test('resolveOrganization — non-literal boolean flag makes members optional', () => {
+  const includeMembers = false as boolean
+  expectTypeOf(
+    resolveOrganization(instance, {organizationId: 'org_1', includeMembers}),
+  ).resolves.toEqualTypeOf<Organization<boolean, false>>()
+})
+
+test('getOrganizationState — default call returns bare-base StateSource', () => {
+  expectTypeOf(getOrganizationState(instance, {organizationId: 'org_1'})).toEqualTypeOf<
+    StateSource<Organization<false, false> | undefined>
+  >()
+})
+
+test('getOrganizationState — both flags true narrows the StateSource value type', () => {
+  expectTypeOf(
+    getOrganizationState(instance, {
+      organizationId: 'org_1',
+      includeMembers: true,
+      includeFeatures: true,
+    }),
+  ).toEqualTypeOf<StateSource<Organization<true, true> | undefined>>()
+})
+
+test('Organization — wide boolean for IncludeMembers makes members optional', () => {
+  expectTypeOf<Organization<boolean, true>>().toEqualTypeOf<
+    OrganizationBase & {members?: OrganizationMember[]} & {features: string[]}
+  >()
+  expectTypeOf<Pick<Organization<boolean, true>, 'members'>>().toEqualTypeOf<{
+    members?: OrganizationMember[]
+  }>()
+})
+
+test('Organization — wide boolean for IncludeFeatures makes features optional', () => {
+  expectTypeOf<Organization<true, boolean>>().toEqualTypeOf<
+    OrganizationBase & {members: OrganizationMember[]} & {features?: string[]}
+  >()
+  expectTypeOf<Pick<Organization<true, boolean>, 'features'>>().toEqualTypeOf<{
+    features?: string[]
+  }>()
+})
+
+test('Organization — both wide booleans make both fields optional', () => {
+  expectTypeOf<Organization<boolean, boolean>>().toEqualTypeOf<
+    OrganizationBase & {members?: OrganizationMember[]} & {features?: string[]}
+  >()
+})

package/src/organization/organization.test.ts

@@ -0,0 +1,138 @@
+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 {getOrganizationCacheKey, resolveOrganization} from './organization'
+
+vi.mock('../client/clientStore')
+
+describe('organization', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('calls `client.observable.request` against `/organizations/<id>` and returns the result', async () => {
+    const organization = {id: 'org_1'}
+    const request = vi.fn().mockReturnValue(of(organization))
+
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    const result = await resolveOrganization(instance, {organizationId: 'org_1'})
+    expect(result).toEqual(organization)
+    expect(request).toHaveBeenCalledWith({
+      uri: '/organizations/org_1',
+      query: {includeMembers: 'false', includeFeatures: 'false'},
+      tag: 'organization.get',
+    })
+  })
+
+  it('serializes query params (booleans → strings) and respects flags', async () => {
+    const request = vi.fn().mockReturnValue(of({id: 'org_1'}))
+    const mockClient = {
+      observable: {request} as unknown as SanityClient['observable'],
+    } as SanityClient
+
+    vi.mocked(getClientState).mockReturnValue({
+      observable: of(mockClient),
+    } as StateSource<SanityClient>)
+
+    await resolveOrganization(instance, {
+      organizationId: 'org_1',
+      includeMembers: true,
+      includeFeatures: true,
+    })
+
+    expect(request).toHaveBeenCalledWith({
+      uri: '/organizations/org_1',
+      query: {
+        includeMembers: 'true',
+        includeFeatures: 'true',
+      },
+      tag: 'organization.get',
+    })
+  })
+
+  it('throws when no organizationId is provided', async () => {
+    await expect(resolveOrganization(instance, {organizationId: ''} as never)).rejects.toThrow(
+      'An organizationId is required to use the organization API.',
+    )
+  })
+})
+
+describe('organization cache key generation', () => {
+  let instance: SanityInstance
+
+  beforeEach(() => {
+    instance = createSanityInstance({})
+  })
+
+  afterEach(() => {
+    instance.dispose()
+  })
+
+  it('default call excludes :members and :features (both default-false)', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1'})).toBe('organization:org_1')
+  })
+
+  it('treats undefined and the matching default as the same key', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1'})).toBe(
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: false,
+        includeFeatures: false,
+      }),
+    )
+  })
+
+  it('explicit includeMembers: true appends :members', () => {
+    expect(getOrganizationCacheKey(instance, {organizationId: 'org_1', includeMembers: true})).toBe(
+      'organization:org_1:members',
+    )
+  })
+
+  it('explicit includeFeatures: true appends :features', () => {
+    expect(
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeFeatures: true}),
+    ).toBe('organization:org_1:features')
+  })
+
+  it('combines all segments in order', () => {
+    expect(
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+    ).toBe('organization:org_1:members:features')
+  })
+
+  it('produces distinct keys for each meaningful option permutation', () => {
+    const keys = new Set([
+      getOrganizationCacheKey(instance, {organizationId: 'org_1'}),
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeMembers: true}),
+      getOrganizationCacheKey(instance, {organizationId: 'org_1', includeFeatures: true}),
+      getOrganizationCacheKey(instance, {
+        organizationId: 'org_1',
+        includeMembers: true,
+        includeFeatures: true,
+      }),
+      getOrganizationCacheKey(instance, {organizationId: 'org_2'}),
+    ])
+    expect(keys.size).toBe(5)
+  })
+})