@sanity/sdk 2.9.0 → 2.11.0

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/bifurTransport.test.ts

@@ -45,16 +45,18 @@ describe('createBifurTransport', () => {
 
   beforeEach(() => {
     vi.useFakeTimers()
+    vi.clearAllMocks()
     mockBifurClient = {
       listen: vi.fn(() => new Subject<never>()),
       request: vi.fn(() => of(undefined)),
     }
     fromUrlMock.mockReturnValue(mockBifurClient)
 
+    // Default mock is a dataset client using project hostname
     mockSanityClient = {
       config: () => ({
         dataset: 'test-dataset',
-        url: 'http://localhost:3333',
+        url: 'https://test-project.api.sanity.io/v2022-06-30',
         requestTagPrefix: 'test-tag',
       }),
       withConfig: vi.fn().mockReturnThis(),
@@ -63,7 +65,7 @@ describe('createBifurTransport', () => {
     token$ = new Subject<string | null>()
   })
 
-  it('constructs the bifur client with the correct URL', () => {
+  it('constructs the bifur client URL for a dataset resource', () => {
     createBifurTransport({
       client: mockSanityClient,
       token$,
@@ -71,13 +73,51 @@ describe('createBifurTransport', () => {
     })
 
     expect(fromUrlMock).toHaveBeenCalledWith(
-      'ws://localhost:3333/socket/test-dataset?tag=test-tag',
-      {
-        token$,
-      },
+      'wss://test-project.api.sanity.io/v2022-06-30/socket/test-dataset?tag=test-tag',
+      {token$},
+    )
+  })
+
+  it('constructs the bifur client URL for a canvas resource', () => {
+    const canvasClient = {
+      config: () => ({
+        resource: {type: 'canvas', id: 'canvas-123'},
+        url: 'https://api.sanity.io/v2022-06-30',
+        requestTagPrefix: 'test-tag',
+      }),
+      withConfig: vi.fn().mockReturnThis(),
+    } as unknown as SanityClient
+
+    createBifurTransport({
+      client: canvasClient,
+      token$,
+      sessionId: 'session-id-123',
+    })
+
+    expect(fromUrlMock).toHaveBeenCalledWith(
+      'wss://api.sanity.io/v2022-06-30/socket/canvases/canvas-123?tag=test-tag',
+      {token$},
     )
   })
 
+  it('throws when no canvas resource or dataset is configured', () => {
+    const invalidClient = {
+      config: () => ({
+        url: 'https://api.sanity.io/v2022-06-30',
+        requestTagPrefix: 'test-tag',
+      }),
+      withConfig: vi.fn().mockReturnThis(),
+    } as unknown as SanityClient
+
+    expect(() =>
+      createBifurTransport({
+        client: invalidClient,
+        token$,
+        sessionId: 'session-id-123',
+      }),
+    ).toThrow('Unable to determine presence URL')
+  })
+
   it('handles incoming rollCall events', () => {
     const incomingBifurEvents$ = new Subject<IncomingBifurEvent>()
     mockBifurClient.listen.mockReturnValue(incomingBifurEvents$)

package/src/presence/bifurTransport.ts

@@ -37,11 +37,23 @@ type IncomingBifurEvent = RollCallEvent | BifurStateMessage | BifurDisconnectMes
 function getBifurClient(client: SanityClient, token$: Observable<string | null>): BifurClient {
   const bifurVersionedClient = client.withConfig({apiVersion: '2022-06-30'})
   const {
+    resource,
     dataset,
     url: baseUrl,
     requestTagPrefix = 'sanity.sdk.presence',
   } = bifurVersionedClient.config()
-  const url = `${baseUrl.replace(/\/+$/, '')}/socket/${dataset}`.replace(/^http/, 'ws')
+
+  let resourcePath: string
+  if (resource?.type === 'canvas') {
+    resourcePath = `canvases/${resource.id}`
+  } else if (dataset) {
+    // Dataset clients use project hostname — dataset name alone is the socket path
+    resourcePath = dataset
+  } else {
+    throw new Error(`Unable to determine presence URL: no canvas resource or dataset configured`)
+  }
+
+  const url = `${baseUrl}/socket/${resourcePath}`.replace(/^http/, 'ws')
 
   const urlWithTag = `${url}?tag=${requestTagPrefix}`
 

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',
@@ -48,6 +48,9 @@ describe('presenceStore', () => {
 
     mockClient = {
       withConfig: vi.fn().mockReturnThis(),
+      observable: {
+        request: vi.fn(() => of({organizationId: 'test-org-id'})),
+      },
     } as unknown as SanityClient
 
     mockTokenState = new Subject<string | null>()
@@ -243,5 +246,98 @@ describe('presenceStore', () => {
 
       unsubscribe()
     })
+
+    it('should throw an error when initialized with a media library resource', () => {
+      const mediaLibraryResource = {mediaLibraryId: 'ml123'}
+
+      expect(() => {
+        getPresence(instance, {resource: mediaLibraryResource})
+      }).toThrow('Presence is not supported for media library resources.')
+    })
+
+    it('should work with a dataset resource', () => {
+      const datasetResource = {projectId: 'test-project', dataset: 'test-dataset'}
+
+      expect(() => {
+        getPresence(instance, {resource: datasetResource})
+      }).not.toThrow()
+    })
+
+    it('should work with a canvas resource', () => {
+      const canvasResource = {canvasId: 'canvas123'}
+
+      expect(() => {
+        getPresence(instance, {resource: canvasResource})
+      }).not.toThrow()
+    })
+
+    it('creates a project-hostname client for dataset resources', () => {
+      getPresence(instance, {resource: {projectId: 'my-project', dataset: 'my-dataset'}})
+
+      expect(getClient).toHaveBeenCalledWith(instance, {
+        apiVersion: '2026-03-30',
+        projectId: 'my-project',
+        dataset: 'my-dataset',
+        useProjectHostname: true,
+      })
+    })
+
+    it('creates a resource client for canvas resources', () => {
+      const canvasResource = {canvasId: 'canvas123'}
+      getPresence(instance, {resource: canvasResource})
+
+      expect(getClient).toHaveBeenCalledWith(instance, {
+        apiVersion: '2026-03-30',
+        resource: canvasResource,
+      })
+    })
+
+    it('fetches organizationId from canvas endpoint for canvas resources', () => {
+      const canvasResource = {canvasId: 'canvas123'}
+      getPresence(instance, {resource: canvasResource})
+
+      expect(mockClient.observable.request).toHaveBeenCalledWith({
+        uri: '/canvases/canvas123',
+        tag: 'canvases.get',
+      })
+    })
+
+    it('does not fetch organizationId for dataset resources', () => {
+      getPresence(instance, {resource: {projectId: 'my-project', dataset: 'my-dataset'}})
+
+      expect(mockClient.observable.request).not.toHaveBeenCalled()
+    })
+
+    it('fetches user data for canvas users', async () => {
+      const source = getPresence(instance, {resource: {canvasId: 'canvas123'}})
+      const unsubscribe = source.subscribe(() => {})
+
+      await firstValueFrom(of(null).pipe(delay(10)))
+
+      mockIncomingEvents.next({
+        type: 'state',
+        userId: 'user-1',
+        sessionId: 'other-session',
+        timestamp: '2023-01-01T12:00:00Z',
+        locations: [
+          {
+            type: 'document',
+            documentId: 'doc-1',
+            path: ['title'],
+            lastActiveAt: '2023-01-01T12:00:00Z',
+          },
+        ],
+      })
+
+      await firstValueFrom(of(null).pipe(delay(50)))
+
+      expect(getUserState).toHaveBeenCalledWith(instance, {
+        userId: 'user-1',
+        resourceType: 'organization',
+        organizationId: 'test-org-id',
+      })
+
+      unsubscribe()
+    })
   })
 })