@sanity/sdk 0.0.0-rc.6 → 0.0.0

package/src/document/patchOperations.ts

@@ -7,7 +7,6 @@ import {
   type KeyedSegment,
   type Path,
   type PathSegment,
-  type SanityDocumentLike,
 } from '@sanity/types'
 
 type SingleValuePath = Exclude<PathSegment, IndexTuple>[]
@@ -17,7 +16,7 @@ type ToNumber<TInput extends string> = TInput extends `${infer TNumber extends n
   : TInput
 
 /**
- * Parse a single “segment” that may include bracket parts.
+ * Parse a single "segment" that may include bracket parts.
  *
  * For example, the literal
  *
@@ -42,7 +41,7 @@ type ParseSegment<TInput extends string> = TInput extends `${infer TProp}[${infe
 /**
  * Parse one or more bracketed parts from a segment.
  *
- * It recursively “peels off” a bracketed part and then continues.
+ * It recursively "peels off" a bracketed part and then continues.
  *
  * For example, given the string:
  *
@@ -61,7 +60,7 @@ type ParseBracket<TInput extends string> = TInput extends `[${infer TPart}]${inf
   : [] // no leading bracket → end of this segment
 
 /**
- * Split the entire path string on dots “outside” of any brackets.
+ * Split the entire path string on dots "outside" of any brackets.
  *
  * For example:
  * ```
@@ -76,42 +75,43 @@ type ParseBracket<TInput extends string> = TInput extends `[${infer TPart}]${inf
  *
  * (We use a simple recursion that splits on the first dot.)
  */
-type PathParts<TPath extends string> = TPath extends `${infer TLeft}.${infer TRight}`
-  ? [...ParseSegment<TLeft>, ...PathParts<TRight>]
-  : ParseSegment<TPath>
+type PathParts<TPath extends string> = TPath extends `${infer Head}.${infer Tail}`
+  ? [Head, ...PathParts<Tail>]
+  : TPath extends ''
+    ? []
+    : [TPath]
 
 /**
- * Given a type T and an array of “access keys” Parts, recursively index into T.
+ * Given a type T and an array of "access keys" Parts, recursively index into T.
  *
  * If a part is a key, it looks up that property.
- * If T is an array and the part is a number, it “indexes” into the element type.
+ * If T is an array and the part is a number, it "indexes" into the element type.
  */
-type DeepGet<T, TParts extends readonly unknown[]> = TParts extends [infer Head, ...infer Tail]
-  ? Head extends keyof T
-    ? DeepGet<T[Head], Tail>
-    : T extends Array<infer U>
-      ? Head extends number
-        ? DeepGet<U, Tail>
-        : never
-      : never
-  : T
+type DeepGet<TValue, TPath extends readonly (string | number)[]> = TPath extends []
+  ? TValue
+  : TPath extends readonly [infer THead, ...infer TTail]
+    ? // Handle traversing into optional properties
+      DeepGet<
+        TValue extends undefined | null
+          ? undefined // Stop traversal if current value is null/undefined
+          : THead extends keyof TValue // Access property if key exists
+            ? TValue[THead]
+            : // Handle array indexing
+              THead extends number
+              ? TValue extends readonly (infer TElement)[]
+                ? TElement | undefined // Array element or undefined if out of bounds
+                : undefined // Cannot index non-array with number
+              : undefined, // Key/index doesn't exist
+        TTail extends readonly (string | number)[] ? TTail : [] // Continue with the rest of the path
+      >
+    : never // Should be unreachable
 
 /**
  * Given a document type TDocument and a JSON Match path string TPath,
  * compute the type found at that path.
  * @beta
  */
-export type JsonMatch<TDocument extends SanityDocumentLike, TPath extends string> = DeepGet<
-  TDocument,
-  PathParts<TPath>
->
-
-/**
- * Computing the full possible paths may be possible but is hard to compute
- * within the type system for complex document types so we use string.
- * @beta
- */
-export type JsonMatchPath<_TDocument extends SanityDocumentLike> = string
+export type JsonMatch<TDocument, TPath extends string> = DeepGet<TDocument, PathParts<TPath>>
 
 function parseBracketContent(content: string): PathSegment {
   // 1) Range match:  ^(\d*):(\d*)$
@@ -138,7 +138,7 @@ function parseBracketContent(content: string): PathSegment {
     return index
   }
 
-  throw new Error(`Invalid bracket content: “[${content}]”`)
+  throw new Error(`Invalid bracket content: "[${content}]"`)
 }
 
 function parseSegment(segment: string): PathSegment[] {
@@ -271,10 +271,10 @@ type MatchEntry<T = unknown> = {
  *
  * @beta
  */
-export function jsonMatch<
-  TDocument extends SanityDocumentLike,
-  TPath extends JsonMatchPath<TDocument>,
->(input: TDocument, path: TPath): MatchEntry<JsonMatch<TDocument, TPath>>[]
+export function jsonMatch<TDocument, TPath extends string>(
+  input: TDocument,
+  path: TPath,
+): MatchEntry<JsonMatch<TDocument, TPath>>[]
 /** @beta */
 export function jsonMatch<TValue>(input: unknown, path: string): MatchEntry<TValue>[]
 /** @beta */
@@ -324,7 +324,7 @@ function matchRecursive(value: unknown, path: Path, currentPath: SingleValuePath
     const startIndex = start === '' ? 0 : start
     const endIndex = end === '' ? value.length : end
 
-    // We’ll accumulate all matches from each index in the range
+    // We'll accumulate all matches from each index in the range
     let results: MatchEntry[] = []
 
     // Decide whether the range is exclusive or inclusive. The example in
@@ -587,15 +587,15 @@ export function insert(input: unknown, insertPatch: InsertPatch): unknown {
   const pathExpression = (insertPatch as {[K in Operation]?: string} & {items: unknown})[operation]
   if (typeof pathExpression !== 'string') return input
 
-  // Helper to normalize a matched index given the parent array’s length.
+  // Helper to normalize a matched index given the parent array's length.
   function normalizeIndex(index: number, parentLength: number): number {
     switch (operation) {
       case 'before':
-        // A negative index means “append” (i.e. insert before a hypothetical element
+        // A negative index means "append" (i.e. insert before a hypothetical element
         // beyond the end of the array).
         return index < 0 ? parentLength : index
       case 'after':
-        // For "after", if the matched index is negative, we treat it as “prepend”:
+        // For "after", if the matched index is negative, we treat it as "prepend":
         // by convention, we convert it to -1 so that later adding 1 produces 0.
         return index < 0 ? -1 : index
       default: // default to 'replace'
@@ -916,7 +916,7 @@ export function setDeep(input: unknown, path: SingleValuePath, value: unknown):
     ]
   }
 
-  // For keyed segments that aren’t arrays, do nothing.
+  // For keyed segments that aren't arrays, do nothing.
   if (typeof currentSegment === 'object') return input
 
   // For plain objects, update an existing property if it exists…

package/src/document/sharedListener.ts

@@ -66,7 +66,9 @@ export function createFetchDocument(instance: SanityInstance) {
   return function (documentId: string): Observable<SanityDocument | null> {
     return getClientState(instance, {apiVersion: API_VERSION}).observable.pipe(
       switchMap((client) => {
-        const loadDocument = createDocumentLoaderFromClient(client)
+        // TODO: remove this once the client is updated to v7 the new type is available in @sanity/mutate/_unstable_store
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const loadDocument = createDocumentLoaderFromClient(client as any)
         return loadDocument(documentId)
       }),
       map((result) => {

package/src/favorites/favorites.test.ts

@@ -0,0 +1,237 @@
+import {type Node} from '@sanity/comlink'
+import {firstValueFrom} from 'rxjs'
+import {describe, expect, it, vi} from 'vitest'
+
+import {getOrCreateNode, releaseNode} from '../comlink/node/comlinkNodeStore'
+import {type FrameMessage, type WindowMessage} from '../comlink/types'
+import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
+import {getFavoritesState, resolveFavoritesState} from './favorites'
+
+vi.mock('../comlink/node/comlinkNodeStore')
+
+let instance: SanityInstance | undefined
+
+describe('favoritesStore', () => {
+  const mockContext = {
+    documentId: 'doc123',
+    documentType: 'movie',
+    resourceId: 'res456',
+    resourceType: 'studio' as const,
+    schemaName: 'movieSchema',
+  }
+
+  const mockContextNoSchema = {
+    documentId: 'doc123',
+    documentType: 'movie',
+    resourceId: 'res456',
+    resourceType: 'studio' as const,
+  }
+
+  describe('createFavoriteKey', () => {
+    beforeEach(() => {
+      vi.resetAllMocks()
+      instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    })
+
+    afterEach(() => {
+      instance?.dispose()
+    })
+
+    it('creates different keys for different contexts with schema name', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({isFavorited: false})
+      const mockNode = {fetch: mockFetch}
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      // Make two fetches with different document IDs
+      await resolveFavoritesState(instance!, mockContext)
+      await resolveFavoritesState(instance!, {
+        ...mockContext,
+        documentId: 'different',
+      })
+
+      // Verify that the fetch was called with different payloads
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+      const call1 = mockFetch.mock.calls[0][1]
+      const call2 = mockFetch.mock.calls[1][1]
+      expect(call1.document.id).toBe('doc123')
+      expect(call2.document.id).toBe('different')
+    })
+
+    it('creates different keys for contexts without schema name', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({isFavorited: false})
+      const mockNode = {fetch: mockFetch}
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      // Make two fetches with different document IDs
+      await resolveFavoritesState(instance!, mockContextNoSchema)
+      await resolveFavoritesState(instance!, {
+        ...mockContextNoSchema,
+        documentId: 'different',
+      })
+
+      // Verify that the fetch was called with different payloads
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+      const call1 = mockFetch.mock.calls[0][1]
+      const call2 = mockFetch.mock.calls[1][1]
+      expect(call1.document.id).toBe('doc123')
+      expect(call2.document.id).toBe('different')
+      expect(call1.document.resource.schemaName).toBeUndefined()
+      expect(call2.document.resource.schemaName).toBeUndefined()
+    })
+  })
+
+  describe('fetcher', () => {
+    beforeEach(() => {
+      vi.resetAllMocks()
+      instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    })
+
+    afterEach(() => {
+      instance?.dispose()
+    })
+
+    it('fetches favorite status and handles success', async () => {
+      const mockResponse = {isFavorited: true}
+      const mockFetch = vi.fn().mockResolvedValue(mockResponse)
+      const mockNode = {fetch: mockFetch}
+
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      const result = await resolveFavoritesState(instance!, mockContext)
+
+      expect(result).toEqual(mockResponse)
+      expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/events/favorite/query', {
+        document: {
+          id: mockContext.documentId,
+          type: mockContext.documentType,
+          resource: {
+            id: mockContext.resourceId,
+            type: mockContext.resourceType,
+            schemaName: mockContext.schemaName,
+          },
+        },
+      })
+    })
+
+    it('handles error and returns default response', async () => {
+      const mockFetch = vi.fn().mockRejectedValue(new Error('Failed to fetch'))
+      const mockNode = {fetch: mockFetch}
+
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      const result = await resolveFavoritesState(instance!, mockContext)
+
+      expect(result).toEqual({isFavorited: false})
+    })
+
+    it('shares observable between multiple subscribers and cleans up', async () => {
+      const mockResponse = {isFavorited: true}
+      const mockFetch = vi.fn().mockResolvedValue(mockResponse)
+      const mockNode = {fetch: mockFetch}
+
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      const state = getFavoritesState(instance!, mockContext)
+
+      // First subscriber
+      const sub1 = state.subscribe()
+      await firstValueFrom(state.observable)
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+
+      // Second subscriber should use cached response
+      const sub2 = state.subscribe()
+      await firstValueFrom(state.observable)
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+
+      // Cleanup
+      sub1()
+      sub2()
+
+      // Wait for cleanup
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      expect(vi.mocked(releaseNode)).toHaveBeenCalledWith(instance, 'dashboard/nodes/sdk')
+    })
+
+    it('reuses active fetch via createFetcherStore/shareReplay when called again while pending', async () => {
+      vi.useFakeTimers()
+
+      let resolveFetch: (value: {isFavorited: boolean}) => void
+      const fetchPromise = new Promise<{isFavorited: boolean}>((resolve) => {
+        resolveFetch = resolve
+      })
+      const mockFetch = vi.fn().mockReturnValue(fetchPromise) // Mocks node.fetch
+      const mockNode = {fetch: mockFetch}
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      // Call 1: Triggers the actual fetch
+      const promise1 = resolveFavoritesState(instance!, mockContext)
+      // Allow fetcher to run and call node.fetch
+      await vi.advanceTimersByTimeAsync(1)
+      expect(mockFetch).toHaveBeenCalledTimes(1) // node.fetch called once
+
+      // Call 2: Should reuse the pending fetch via createFetcherStore/shareReplay
+      const promise2 = resolveFavoritesState(instance!, mockContext)
+      await vi.advanceTimersByTimeAsync(1)
+
+      // Verify node.fetch was NOT called again
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+
+      // Resolve the underlying fetch
+      resolveFetch!({isFavorited: true})
+      await vi.advanceTimersByTimeAsync(1) // Allow promises to resolve
+
+      // Check results
+      const result1 = await promise1
+      const result2 = await promise2
+      expect(result1).toEqual({isFavorited: true})
+      expect(result2).toEqual({isFavorited: true})
+
+      // Allow cleanup timers
+      await vi.advanceTimersByTimeAsync(5001) // stateExpirationDelay
+      expect(vi.mocked(releaseNode)).toHaveBeenCalled()
+
+      vi.useRealTimers()
+    })
+
+    it('handles timeout and returns default response', async () => {
+      vi.useFakeTimers()
+
+      const mockFetch = vi.fn().mockReturnValue(new Promise(() => {})) // Promise that never resolves
+      const mockNode = {fetch: mockFetch}
+
+      vi.mocked(getOrCreateNode).mockReturnValue(
+        mockNode as unknown as Node<WindowMessage, FrameMessage>,
+      )
+
+      const resultPromise = resolveFavoritesState(instance!, mockContext)
+
+      // Advance time past the timeout threshold (3000ms)
+      await vi.advanceTimersByTimeAsync(3001)
+
+      const result = await resultPromise
+
+      expect(result).toEqual({isFavorited: false})
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+
+      // Ensure releaseNode is still called even on timeout/error path
+      // Need to wait for the catchError and cleanup logic
+      await vi.advanceTimersByTimeAsync(1) // Allow microtasks to run
+      expect(vi.mocked(releaseNode)).toHaveBeenCalledWith(instance, 'dashboard/nodes/sdk')
+
+      vi.useRealTimers()
+    })
+  })
+})

package/src/favorites/favorites.ts

@@ -0,0 +1,122 @@
+import {
+  type CanvasResource,
+  type MediaResource,
+  SDK_CHANNEL_NAME,
+  SDK_NODE_NAME,
+  type StudioResource,
+} from '@sanity/message-protocol'
+import {catchError, from, map, Observable, of, shareReplay, throwError, timeout} from 'rxjs'
+
+import {getOrCreateNode, releaseNode} from '../comlink/node/comlinkNodeStore'
+import {type DocumentHandle} from '../config/sanityConfig'
+import {type SanityInstance} from '../store/createSanityInstance'
+import {createFetcherStore} from '../utils/createFetcherStore'
+
+// Users may, in many situations, be developing
+// without a connection to the Dashboard UI.
+// This timeout allows us to return a fallback state
+// instead of suspending.
+const FAVORITES_FETCH_TIMEOUT = 3000
+
+/**
+ * @public
+ */
+export interface FavoriteStatusResponse {
+  isFavorited: boolean
+}
+
+/**
+ * @public
+ */
+interface FavoriteDocumentContext extends DocumentHandle {
+  resourceId: string
+  resourceType: StudioResource['type'] | MediaResource['type'] | CanvasResource['type']
+  schemaName?: string
+}
+
+// Helper to create a stable key for the store
+function createFavoriteKey(context: FavoriteDocumentContext): string {
+  return `${context.documentId}:${context.documentType}:${context.resourceId}:${context.resourceType}${
+    context.schemaName ? `:${context.schemaName}` : ''
+  }`
+}
+
+const favorites = createFetcherStore<[FavoriteDocumentContext], FavoriteStatusResponse>({
+  name: 'Favorites',
+  getKey: (_instance: SanityInstance, context: FavoriteDocumentContext) => {
+    return createFavoriteKey(context)
+  },
+  fetcher: (instance: SanityInstance) => {
+    return (context: FavoriteDocumentContext): Observable<FavoriteStatusResponse> => {
+      const node = getOrCreateNode(instance, {
+        name: SDK_NODE_NAME,
+        connectTo: SDK_CHANNEL_NAME,
+      })
+
+      const payload = {
+        document: {
+          id: context.documentId,
+          type: context.documentType,
+          resource: {
+            id: context.resourceId,
+            type: context.resourceType,
+            schemaName: context.schemaName,
+          },
+        },
+      }
+
+      const dashboardFetch = from(
+        node.fetch(
+          // @ts-expect-error -- getOrCreateNode should be refactored to take type arguments
+          'dashboard/v1/events/favorite/query',
+          payload,
+        ) as Promise<FavoriteStatusResponse>,
+      ).pipe(
+        timeout({
+          first: FAVORITES_FETCH_TIMEOUT,
+          with: () => throwError(() => new Error('Favorites service connection timeout')),
+        }),
+        map((response) => {
+          return {isFavorited: response.isFavorited}
+        }),
+        catchError((err) => {
+          // eslint-disable-next-line no-console
+          console.error('Favorites service connection error', err)
+          return of({isFavorited: false})
+        }),
+        // Share the same subscription between multiple subscribers
+        shareReplay(1),
+      )
+
+      // Clean up when all subscribers are gone
+      return new Observable<FavoriteStatusResponse>((subscriber) => {
+        const subscription = dashboardFetch.subscribe(subscriber)
+        return () => {
+          subscription.unsubscribe()
+          // If this was the last subscriber, clean up
+          if (subscription.closed) {
+            releaseNode(instance, SDK_NODE_NAME)
+          }
+        }
+      })
+    }
+  },
+})
+
+/**
+ * Gets a StateSource for the favorite status of a document.
+ * @param instance - The Sanity instance.
+ * @param context - The document context including ID, type, and resource information.
+ * @returns A StateSource emitting `{ isFavorited: boolean }`.
+ * @public
+ */
+export const getFavoritesState = favorites.getState
+
+/**
+ * Resolves the favorite status for a document.
+ * @param instance - The Sanity instance.
+ * @param context - The document context including ID, type, and resource information.
+ * @returns A Promise resolving to `{ isFavorited: boolean }`.
+ * @public
+ */
+export const resolveFavoritesState = favorites.resolveState

package/src/preview/resolvePreview.test.ts

@@ -1,8 +1,7 @@
-import {type SanityDocumentLike} from '@sanity/types'
 import {of} from 'rxjs'
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {type DocumentHandle} from '../config/sanityConfig'
+import {createDocumentHandle} from '../config/handles'
 import {createSanityInstance, type SanityInstance} from '../store/createSanityInstance'
 import {type StateSource} from '../store/createStateSourceAction'
 import {getPreviewState} from './getPreviewState'
@@ -32,10 +31,10 @@ describe('resolvePreview', () => {
   })
 
   it('resolves a preview and returns the first emitted value with results', async () => {
-    const docHandle: DocumentHandle<SanityDocumentLike> = {
+    const docHandle = createDocumentHandle({
       documentId: 'doc123',
       documentType: 'movie',
-    }
+    })
 
     const result = await resolvePreview(instance, docHandle)
 

package/src/preview/subscribeToStateAndFetchBatches.test.ts

@@ -53,13 +53,13 @@ describe('subscribeToStateAndFetchBatches', () => {
     expect(getQueryState).toHaveBeenCalledTimes(1)
     expect(getQueryState).toHaveBeenCalledWith(
       instance,
-      expect.any(String),
       expect.objectContaining({
         params: expect.objectContaining({
           __ids_71322c7a: ['doc1', 'drafts.doc1', 'doc2', 'drafts.doc2'],
         }),
         perspective: PREVIEW_PERSPECTIVE,
         tag: PREVIEW_TAG,
+        query: expect.any(String),
       }),
     )
 

package/src/preview/subscribeToStateAndFetchBatches.ts

@@ -59,7 +59,8 @@ export const subscribeToStateAndFetchBatches = ({
         const {query, params} = createPreviewQuery(ids)
         const controller = new AbortController()
         return new Observable<PreviewQueryResult[]>((observer) => {
-          const {getCurrent, observable} = getQueryState<PreviewQueryResult[]>(instance, query, {
+          const {getCurrent, observable} = getQueryState<PreviewQueryResult[]>(instance, {
+            query,
             params,
             tag: PREVIEW_TAG,
             perspective: PREVIEW_PERSPECTIVE,
@@ -67,7 +68,8 @@ export const subscribeToStateAndFetchBatches = ({
           const source$ = defer(() => {
             if (getCurrent() === undefined) {
               return from(
-                resolveQuery<PreviewQueryResult[]>(instance, query, {
+                resolveQuery<PreviewQueryResult[]>(instance, {
+                  query,
                   params,
                   tag: PREVIEW_TAG,
                   perspective: PREVIEW_PERSPECTIVE,

package/src/project/organizationVerification.test.ts

@@ -0,0 +1,35 @@
+import {describe, expect, it} from 'vitest'
+
+import {compareProjectOrganization, type OrgVerificationResult} from './organizationVerification'
+
+describe('compareProjectOrganization', () => {
+  const projectId = 'proj-1'
+  const expectedOrgId = 'org-abc'
+
+  it('should return error null when project orgId matches expected orgId', () => {
+    const projectOrgId = 'org-abc'
+    const result = compareProjectOrganization(projectId, projectOrgId, expectedOrgId)
+    expect(result).toEqual<OrgVerificationResult>({error: null})
+  })
+
+  it('should return an error message when project orgId does not match expected orgId', () => {
+    const projectOrgId = 'org-xyz' // Mismatch
+    const result = compareProjectOrganization(projectId, projectOrgId, expectedOrgId)
+    expect(result.error).toContain('belongs to Organization org-xyz')
+    expect(result.error).toContain('Dashboard has Organization org-abc selected')
+  })
+
+  it('should return an error message when project orgId is null', () => {
+    const projectOrgId = null
+    const result = compareProjectOrganization(projectId, projectOrgId, expectedOrgId)
+    expect(result.error).toContain('belongs to Organization unknown')
+    expect(result.error).toContain('Dashboard has Organization org-abc selected')
+  })
+
+  it('should return an error message when project orgId is undefined', () => {
+    const projectOrgId = undefined
+    const result = compareProjectOrganization(projectId, projectOrgId, expectedOrgId)
+    expect(result.error).toContain('belongs to Organization unknown')
+    expect(result.error).toContain('Dashboard has Organization org-abc selected')
+  })
+})

package/src/project/organizationVerification.ts

@@ -0,0 +1,26 @@
+/**
+ * Error message returned by the organization verification
+ * @public
+ */
+export interface OrgVerificationResult {
+  error: string | null
+}
+
+/**
+ * Compares a project's actual organization ID with the expected organization ID.
+ * @public
+ */
+export function compareProjectOrganization(
+  projectId: string,
+  projectOrganizationId: string | null | undefined,
+  currentDashboardOrgId: string,
+): OrgVerificationResult {
+  if (projectOrganizationId !== currentDashboardOrgId) {
+    return {
+      error:
+        `Project ${projectId} belongs to Organization ${projectOrganizationId ?? 'unknown'}, ` +
+        `but the Dashboard has Organization ${currentDashboardOrgId} selected`,
+    }
+  }
+  return {error: null}
+}