@sanity/sdk 0.0.0-rc.2 → 0.0.0-rc.4

package/dist/index.d.ts

@@ -1,9 +1,14 @@
+import {AuthStoreState as AuthStoreState_2} from './authStore'
+import {BoundStoreAction} from '../store/createActionBinder'
+import {BoundStoreAction as BoundStoreAction_2} from '../../store/createActionBinder'
 import {ChannelInput} from '@sanity/comlink'
 import {ChannelInstance} from '@sanity/comlink'
 import {ClientConfig} from '@sanity/client'
 import {Controller} from '@sanity/comlink'
 import {CurrentUser} from '@sanity/types'
 import {DatasetsResponse} from '@sanity/client'
+import {DocumentPermissionsResult as DocumentPermissionsResult_2} from './permissions'
+import {FetcherStoreState as FetcherStoreState_2} from '../_exports'
 import {IndexTuple} from '@sanity/types'
 import {ListenEvent} from '@sanity/client'
 import {Message} from '@sanity/comlink'
@@ -14,13 +19,20 @@ import {Observable} from 'rxjs'
 import {PatchMutation} from '@sanity/mutate/_unstable_store'
 import {PatchOperations} from '@sanity/types'
 import {PathSegment} from '@sanity/types'
+import {PreviewStoreState as PreviewStoreState_2} from './previewStore'
+import {ProjectionStoreState} from './projectionStore'
+import {ProjectionValuePending as ProjectionValuePending_2} from './projectionStore'
 import {ResponseQueryOptions} from '@sanity/client'
 import {Role} from '@sanity/types'
 import {SanityClient} from '@sanity/client'
 import {SanityDocument} from '@sanity/types'
+import {SanityDocument as SanityDocument_2} from '@sanity/client'
 import {SanityDocumentLike} from '@sanity/types'
 import {SanityProject as SanityProject_2} from '@sanity/client'
+import {SanityUser as SanityUser_2} from './types'
+import {StateSource as StateSource_2} from '../_exports'
 import {Subject} from 'rxjs'
+import {ValuePending as ValuePending_2} from './previewStore'
 
 declare interface AccessAttributeNode extends BaseNode {
   type: 'AccessAttribute'
@@ -34,12 +46,6 @@ declare interface AccessElementNode extends BaseNode {
   index: number
 }
 
-/** @public */
-export declare interface ActionContext<TState> {
-  instance: SanityInstance
-  state: ResourceState<TState>
-}
-
 /**
  * @beta
  * Event emitted when a precondition to applying an action fails.
@@ -76,6 +82,20 @@ export declare interface ActionsResult<TDocument extends SanityDocument = Sanity
   submitted: () => ReturnType<SanityClient['action']>
 }
 
+declare type AllowedClientConfigKey =
+  | 'useCdn'
+  | 'token'
+  | 'perspective'
+  | 'apiHost'
+  | 'proxy'
+  | 'withCredentials'
+  | 'timeout'
+  | 'maxRetries'
+  | 'dataset'
+  | 'projectId'
+  | 'requestTagPrefix'
+  | 'useProjectHostname'
+
 declare interface AndNode extends BaseNode {
   type: 'And'
   left: ExprNode
@@ -147,14 +167,14 @@ declare interface AppliedTransaction extends QueuedTransaction {
 
 /** @beta */
 export declare function applyDocumentActions<TDocument extends SanityDocument>(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
   options?: ApplyDocumentActionsOptions,
 ): Promise<ActionsResult<TDocument>>
 
 /** @beta */
 export declare function applyDocumentActions(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   action: DocumentAction | DocumentAction[],
   options?: ApplyDocumentActionsOptions,
 ): Promise<ActionsResult>
@@ -299,6 +319,7 @@ export declare interface AuthStoreState {
     storageKey: string
     storageArea: Storage | undefined
     apiHost: string | undefined
+    loginUrl: string
     callbackUrl: string | undefined
     providedToken: string | undefined
   }
@@ -313,9 +334,10 @@ declare interface BaseNode {
 declare type BooleanValue = StaticValue<boolean, 'boolean'>
 
 /**
- * @public
+ * Represents a store action that has been bound to a specific store instance
  */
-export declare type BoundResourceAction<TParams extends unknown[], TReturn> = (
+declare type BoundStoreAction_3<_TState, TParams extends unknown[], TReturn> = (
+  instance: SanityInstance,
   ...params: TParams
 ) => TReturn
 
@@ -339,27 +361,25 @@ declare interface ChannelEntry {
  *   ('project') and the global client ('global'). When set to `'global'`, the
  *   global client is used.
  *
- * These options are utilized by `getClient` and `getClientState` to return a memoized
- * client instance, ensuring that clients are reused for identical configurations and that
- * updates (such as auth token changes) propagate correctly.
+ * These options are utilized by `getClient` and `getClientState` to configure and
+ * return appropriate client instances that automatically handle authentication
+ * updates and configuration changes.
  *
  * @public
  */
-export declare interface ClientOptions extends ClientConfig {
+export declare interface ClientOptions
+  extends Pick<ClientConfig, AllowedClientConfigKey>,
+    DatasetHandle {
   /**
-   * An optional flag to choose between the project-specific client ('project')
+   * An optional flag to choose between the default client (typically project-level)
    * and the global client ('global'). When set to `'global'`, the global client
    * is used.
    */
-  scope?: 'project' | 'global'
+  scope?: 'default' | 'global'
   /**
    * A required string indicating the API version for the client.
    */
   apiVersion: string
-  /**
-   * A resource identifier for a document, in the format of `projectId.dataset`
-   */
-  resourceId?: ResourceId
 }
 
 /**
@@ -367,8 +387,10 @@ export declare interface ClientOptions extends ClientConfig {
  * @public
  */
 export declare interface ClientState {
-  defaultClient: SanityClient
-  defaultGlobalClient: SanityClient
+  token: string | null
+  clients: {
+    [TKey in string]?: SanityClient
+  }
 }
 
 /**
@@ -414,70 +436,40 @@ export declare const CORE_SDK_VERSION: {}
 
 /** @beta */
 export declare function createDocument<TDocument extends SanityDocumentLike>(
-  doc: DocumentTypeHandle<TDocument> | DocumentHandle<TDocument>,
+  doc: DocumentTypeHandle<TDocument>,
 ): CreateDocumentAction<TDocument>
 
 /** @beta */
 export declare interface CreateDocumentAction<
   TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+> extends DocumentTypeHandle<TDocument> {
   type: 'document.create'
-  documentId?: string
-  resourceId?: DocumentResourceId
-  documentType: TDocument['_type']
 }
 
 /**
- * Returns a new instance of dependencies required for SanitySDK.
+ * Creates a GROQ search filter string (`[@] match text::query("...")`)
+ * from a raw search query string.
  *
- * @public
+ * It applies wildcard ('*') logic to the last eligible token and escapes
+ * double quotes within the search term.
  *
- * @param config - The configuration for this instance
+ * If the input query is empty or only whitespace, it returns an empty string.
  *
- * @returns A new "instance" of a Sanity SDK, used to bind resources/configuration to it
+ * @param query - The raw input search string.
+ * @returns The GROQ search filter string, or an empty string.
+ * @internal
  */
-export declare function createSanityInstance({
-  projectId,
-  dataset,
-  ...config
-}: SanityConfig): SanityInstance
+export declare function createGroqSearchFilter(query: string): string
 
 /**
+ * Creates a new Sanity resource instance
+ * @param config - Configuration for the instance (optional)
+ * @returns A configured SanityInstance
+ * @remarks When creating child instances, configurations are merged with parent values
+ *
  * @public
  */
-export declare const createUsersStore: (instance: SanityInstance | ActionContext<any>) => {
-  dispose: () => void
-} & {
-  getState: BoundResourceAction<
-    [],
-    StateSource<{
-      users: SanityUser[]
-      totalCount: number
-      nextCursor: string | null
-      hasMore: boolean
-      options: {
-        resourceType: ResourceType
-        resourceId: string
-        /**
-         * The maximum number of users to fetch. [Default: 100]
-         */
-        limit?: number
-      }
-      initialFetchCompleted: boolean
-    }>
-  >
-  loadMore: BoundResourceAction<[], Promise<void>>
-  resolveUsers: BoundResourceAction<[], Promise<SanityUserResponse>>
-  setOptions: BoundResourceAction<
-    [
-      options: {
-        resourceType: 'organization' | 'project'
-        resourceId: string
-      },
-    ],
-    void
-  >
-}
+export declare function createSanityInstance(config?: SanityConfig): SanityInstance
 
 export {CurrentUser}
 
@@ -492,6 +484,13 @@ declare interface DashboardContext {
   orgId?: string
 }
 
+/**
+ * @public
+ */
+export declare interface DatasetHandle extends ProjectHandle {
+  dataset?: string | undefined
+}
+
 declare class DateTime {
   date: Date
   constructor(date: Date)
@@ -532,11 +531,9 @@ export declare function deleteDocument<TDocument extends SanityDocumentLike>(
 
 /** @beta */
 export declare interface DeleteDocumentAction<
-  _TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> extends DocumentHandle<TDocument> {
   type: 'document.delete'
-  documentId: string
-  resourceId?: DocumentResourceId
 }
 
 declare type DereferenceFunction = (obj: {
@@ -557,9 +554,7 @@ declare interface DescNode extends BaseNode {
  * Calls the destroy method on the controller and resets the controller state.
  * @public
  */
-export declare const destroyController: (
-  actionContext: ActionContext<ComlinkControllerState>,
-) => void
+export declare const destroyController: BoundStoreAction_2<ComlinkControllerState, [], void>
 
 /** @beta */
 export declare function discardDocument<TDocument extends SanityDocumentLike>(
@@ -568,11 +563,9 @@ export declare function discardDocument<TDocument extends SanityDocumentLike>(
 
 /** @beta */
 export declare interface DiscardDocumentAction<
-  _TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> extends DocumentHandle<TDocument> {
   type: 'document.discard'
-  documentId: string
-  resourceId?: DocumentResourceId
 }
 
 declare type Document_2 = {
@@ -644,16 +637,15 @@ export declare type DocumentEvent =
   | DocumentDiscardedEvent
 
 /**
- * @beta
+ * @public
  * A minimal set of metadata for a given document, comprising the document's ID and type.
  * Used by most document-related hooks (such as {@link usePreview}, {@link useDocument}, and {@link useEditDocument})
  * to reference a particular document without fetching the entire document upfront.
  * @category Types
  */
-export declare interface DocumentHandle<TDocument extends SanityDocumentLike = SanityDocumentLike> {
-  _id: string
-  _type: TDocument['_type']
-  resourceId?: DocumentResourceId
+export declare interface DocumentHandle<TDocument extends SanityDocumentLike = SanityDocumentLike>
+  extends DocumentTypeHandle<TDocument> {
+  documentId: string
 }
 
 /** @beta */
@@ -691,12 +683,6 @@ declare interface DocumentRebaseErrorEvent {
   error: unknown
 }
 
-/**
- * @beta
- * A resource identifier for a document, in the format of `document:${projectId}.${dataset}:${documentId}`
- */
-export declare type DocumentResourceId = `document:${string}.${string}:${string}`
-
 /**
  * Represents a set of document that will go into `applyMutations`. Before
  * applying a mutation, it's expected that all relevant documents that the
@@ -753,18 +739,17 @@ declare interface DocumentStoreState {
   outgoing?: OutgoingTransaction
   grants?: Record<Grant, ExprNode>
   error?: unknown
-  sharedListener: Observable<ListenEvent<SanityDocument>>
+  sharedListener: SharedListener
   fetchDocument: (documentId: string) => Observable<SanityDocument | null>
   events: Subject<DocumentEvent>
 }
 
-/** @beta */
+/** @public */
 export declare interface DocumentTypeHandle<
   TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
-  _id?: string
-  _type: TDocument['_type']
-  resourceId?: DocumentResourceId
+> extends DatasetHandle {
+  documentId?: string
+  documentType: TDocument['_type']
 }
 
 /**
@@ -779,6 +764,7 @@ export declare interface DocumentUnpublishedEvent {
 
 /** @beta */
 export declare function editDocument<TDocument extends SanityDocumentLike>(
+  doc: DocumentHandle<TDocument>,
   sanityMutatePatch: PatchMutation,
 ): EditDocumentAction<TDocument>
 
@@ -790,11 +776,9 @@ export declare function editDocument<TDocument extends SanityDocumentLike>(
 
 /** @beta */
 export declare interface EditDocumentAction<
-  _TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> extends DocumentHandle<TDocument> {
   type: 'document.edit'
-  documentId: string
-  resourceId?: DocumentResourceId
   patches?: PatchOperations[]
 }
 
@@ -856,12 +840,12 @@ declare type ExprNode =
  * @public
  */
 export declare interface FetcherStore<TParams extends unknown[], TData> {
-  getState: ResourceAction<
+  getState: BoundStoreAction_3<
     FetcherStoreState<TParams, TData>,
     TParams,
     StateSource<TData | undefined>
   >
-  resolveState: ResourceAction<FetcherStoreState<TParams, TData>, TParams, Promise<TData>>
+  resolveState: BoundStoreAction_3<FetcherStoreState<TParams, TData>, TParams, Promise<TData>>
 }
 
 /**
@@ -875,21 +859,6 @@ export declare interface FetcherStoreState<TParams extends unknown[], TData> {
   error?: unknown
 }
 
-/**
- * @public
- */
-export declare const fetchLoginUrls: ResourceAction<
-  AuthStoreState,
-  [],
-  Promise<
-    {
-      url: string
-      name: string
-      title: string
-    }[]
-  >
->
-
 declare interface FilterNode extends BaseNode {
   type: 'Filter'
   base: ExprNode
@@ -919,60 +888,63 @@ declare interface FuncCallNode extends BaseNode {
 /**
  * @public
  */
-export declare const getAuthState: ResourceAction<AuthStoreState, [], StateSource<AuthState>>
+export declare const getAuthState: BoundStoreAction<AuthStoreState, [], StateSource_2<AuthState>>
 
 /**
- * Retrieves a memoized Sanity client instance configured with the provided options.
+ * Retrieves a Sanity client instance configured with the provided options.
  *
- * This function uses a memoized selector to return a client instance from the
- * client store, based on the default project or global client. The selector
- * leverages a WeakMap-based cache and reselect to ensure that clients with the
- * same configuration are reused, and that updates, such as authentication token
- * changes, propagate automatically.
+ * This function returns a client instance configured for the project or as a
+ * global client based on the options provided. It ensures efficient reuse of
+ * client instances by returning the same instance for the same options.
+ * For automatic handling of authentication token updates, consider using
+ * `getClientState`.
  *
  * @public
  */
-export declare const getClient: ResourceAction<ClientState, [options: ClientOptions], SanityClient>
+export declare const getClient: BoundStoreAction<
+  ClientState,
+  [options: ClientOptions],
+  SanityClient
+>
 
 /**
  * Returns a state source for the Sanity client instance.
  *
  * This function provides a subscribable state source that emits updated client
- * instances whenever the client configuration changes (for example, due to
- * token updates). It leverages the underlying client store and memoized selector
- * to ensure that subscribers receive the most current client configuration.
+ * instances whenever relevant configurations change (such as authentication tokens).
+ * Use this when you need to react to client configuration changes in your application.
  *
  * @public
  */
-export declare const getClientState: ResourceAction<
+export declare const getClientState: BoundStoreAction<
   ClientState,
   [options: ClientOptions],
-  StateSource<SanityClient>
+  StateSource_2<SanityClient>
 >
 
 /**
  * @public
  */
-export declare const getCurrentUserState: ResourceAction<
+export declare const getCurrentUserState: BoundStoreAction<
   AuthStoreState,
   [],
-  StateSource<CurrentUser | null>
+  StateSource_2<CurrentUser | null>
 >
 
 /**
  * @public
  */
-export declare const getDashboardOrganizationId: ResourceAction<
+export declare const getDashboardOrganizationId: BoundStoreAction<
   AuthStoreState,
   [],
-  StateSource<string | undefined>
+  StateSource_2<string | undefined>
 >
 
 /** @public */
-export declare const getDatasetsState: ResourceAction<
-  FetcherStoreState<[], DatasetsResponse>,
-  [],
-  StateSource<DatasetsResponse | undefined>
+export declare const getDatasetsState: BoundStoreAction<
+  FetcherStoreState_2<[options?: ProjectHandle | undefined], DatasetsResponse>,
+  [options?: ProjectHandle | undefined],
+  StateSource_2<DatasetsResponse | undefined>
 >
 
 /** @beta */
@@ -980,26 +952,26 @@ export declare function getDocumentState<
   TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
 >(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   doc: string | DocumentHandle<TDocument>,
   path: TPath,
 ): StateSource<JsonMatch<TDocument, TPath> | undefined>
 
 /** @beta */
 export declare function getDocumentState<TDocument extends SanityDocument>(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   doc: string | DocumentHandle<TDocument>,
 ): StateSource<TDocument | null>
 
 /** @beta */
 export declare function getDocumentState(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   doc: string | DocumentHandle,
   path?: string,
 ): StateSource<unknown>
 
 /** @beta */
-export declare const getDocumentSyncStatus: ResourceAction<
+export declare const getDocumentSyncStatus: BoundStoreAction<
   DocumentStoreState,
   [doc: DocumentHandle<SanityDocumentLike>],
   StateSource<boolean | undefined>
@@ -1008,18 +980,14 @@ export declare const getDocumentSyncStatus: ResourceAction<
 /**
  * @public
  */
-export declare const getLoginUrlsState: ResourceAction<
-  AuthStoreState,
-  [],
-  StateSource<AuthProvider[] | null>
->
+export declare const getLoginUrlState: BoundStoreAction<AuthStoreState, [], StateSource_2<string>>
 
 /**
  * Retrieve or create a channel to be used for communication between
  * an application and the controller.
  * @public
  */
-export declare const getOrCreateChannel: ResourceAction<
+export declare const getOrCreateChannel: BoundStoreAction_2<
   ComlinkControllerState,
   [options: ChannelInput],
   ChannelInstance<Message, Message>
@@ -1030,7 +998,7 @@ export declare const getOrCreateChannel: ResourceAction<
  * between an application and iframes.
  * @public
  */
-export declare const getOrCreateController: ResourceAction<
+export declare const getOrCreateController: BoundStoreAction_2<
   ComlinkControllerState,
   [targetOrigin: string],
   Controller
@@ -1042,40 +1010,45 @@ export declare const getOrCreateController: ResourceAction<
  * be created within a frame / window to communicate with the controller.
  * @public
  */
-export declare const getOrCreateNode: ResourceAction<
+export declare const getOrCreateNode: BoundStoreAction_2<
   ComlinkNodeState,
   [options: NodeInput],
   Node_2<Message, Message>
 >
 
 /** @beta */
-export declare const getPermissionsState: ResourceAction<
+export declare const getPermissionsState: BoundStoreAction<
   DocumentStoreState,
-  [actions: DocumentAction | DocumentAction[]],
-  StateSource<DocumentPermissionsResult | undefined>
+  [DocumentAction | DocumentAction[]],
+  StateSource<DocumentPermissionsResult_2 | undefined>
 >
 
 /**
  * @beta
  */
-export declare const getPreviewState: ResourceAction<
-  PreviewStoreState,
-  [GetPreviewStateOptions],
-  StateSource<ValuePending<PreviewValue>>
->
+export declare function getPreviewState<TResult extends object>(
+  instance: SanityInstance,
+  options: GetPreviewStateOptions,
+): StateSource<ValuePending<TResult>>
 
 /**
  * @beta
  */
-export declare interface GetPreviewStateOptions {
-  document: DocumentHandle
-}
+export declare function getPreviewState(
+  instance: SanityInstance,
+  options: GetPreviewStateOptions,
+): StateSource<ValuePending<PreviewValue>>
+
+/**
+ * @beta
+ */
+export declare type GetPreviewStateOptions = DocumentHandle
 
 /**
  * @beta
  */
 export declare function getProjectionState<TResult extends object>(
-  instance: SanityInstance | ActionContext<ProjectionStoreState>,
+  instance: SanityInstance,
   options: GetProjectionStateOptions,
 ): StateSource<ProjectionValuePending<TResult>>
 
@@ -1083,27 +1056,26 @@ export declare function getProjectionState<TResult extends object>(
  * @beta
  */
 export declare function getProjectionState(
-  instance: SanityInstance | ActionContext<ProjectionStoreState>,
+  instance: SanityInstance,
   options: GetProjectionStateOptions,
 ): StateSource<ProjectionValuePending<Record<string, unknown>>>
 
-declare interface GetProjectionStateOptions {
-  document: DocumentHandle
+declare interface GetProjectionStateOptions extends DocumentHandle {
   projection: ValidProjection
 }
 
 /** @public */
-export declare const getProjectsState: ResourceAction<
-  FetcherStoreState<[], Omit<SanityProject_2, 'members'>[]>,
+export declare const getProjectsState: BoundStoreAction<
+  FetcherStoreState_2<[], Omit<SanityProject_2, 'members'>[]>,
   [],
-  StateSource<Omit<SanityProject_2, 'members'>[] | undefined>
+  StateSource_2<Omit<SanityProject_2, 'members'>[] | undefined>
 >
 
 /** @public */
-export declare const getProjectState: ResourceAction<
-  FetcherStoreState<[projectId: string], SanityProject_2>,
-  [projectId: string],
-  StateSource<SanityProject_2 | undefined>
+export declare const getProjectState: BoundStoreAction<
+  FetcherStoreState_2<[options?: ProjectHandle | undefined], SanityProject_2>,
+  [options?: ProjectHandle | undefined],
+  StateSource_2<SanityProject_2 | undefined>
 >
 
 /** @beta */
@@ -1126,30 +1098,67 @@ export declare const getQueryKey: (query: string, options?: QueryOptions) => str
  * @beta
  */
 export declare function getQueryState<T>(
-  instance: SanityInstance | ActionContext<QueryStoreState>,
+  instance: SanityInstance,
   query: string,
   options?: QueryOptions,
 ): StateSource<T | undefined>
 
 /** @beta */
 export declare function getQueryState(
-  instance: SanityInstance | ActionContext<QueryStoreState>,
+  instance: SanityInstance,
   query: string,
   options?: QueryOptions,
 ): StateSource<unknown>
 
 /**
- * @beta
- * Get the resource ID from a document resource ID
+ * @public
  */
-export declare function getResourceId(
-  documentResourceId: DocumentResourceId | undefined,
-): ResourceId | undefined
+export declare const getTokenState: BoundStoreAction<
+  AuthStoreState,
+  [],
+  StateSource_2<string | null>
+>
+
+/** @internal */
+export declare const getUsersKey: (
+  instance: SanityInstance,
+  {resourceType, organizationId, batchSize, projectId}?: GetUsersOptions,
+) => string
 
 /**
  * @public
  */
-export declare const getTokenState: ResourceAction<AuthStoreState, [], StateSource<string | null>>
+export declare interface GetUsersOptions extends ProjectHandle {
+  resourceType?: 'organization' | 'project'
+  batchSize?: number
+  organizationId?: string
+}
+
+/**
+ * Returns the state source for users associated with a specific resource.
+ *
+ * This function returns a state source that represents the current list of users for a given
+ * resource. Subscribing to the state source will instruct the SDK to fetch the users (if not
+ * already fetched) and will load more from this state source as well. When the last subscriber is
+ * removed, the users state is automatically cleaned up from the store after a delay.
+ *
+ * Note: This functionality is for advanced users who want to build their own framework
+ * integrations. Our SDK also provides a React integration for convenient usage.
+ *
+ * @beta
+ */
+export declare const getUsersState: BoundStoreAction<
+  UsersStoreState,
+  [options?: GetUsersOptions | undefined],
+  StateSource_2<
+    | {
+        data: SanityUser_2[]
+        totalCount: number
+        hasMore: boolean
+      }
+    | undefined
+  >
+>
 
 declare type Grant = 'read' | 'update' | 'create' | 'history'
 
@@ -1191,7 +1200,7 @@ declare interface GroupNode extends BaseNode {
 /**
  * @public
  */
-export declare const handleAuthCallback: ResourceAction<
+export declare const handleAuthCallback: BoundStoreAction<
   AuthStoreState,
   [locationHref?: string | undefined],
   Promise<string | false>
@@ -1276,10 +1285,27 @@ export declare function jsonMatch<TValue>(input: unknown, path: string): MatchEn
  */
 export declare type JsonMatchPath<_TDocument extends SanityDocumentLike> = string
 
-declare interface LiveEventAwareState {
-  lastLiveEventId: string | null
-  syncTags: Record<string, true>
-}
+/**
+ * Loads more users for a specific resource.
+ *
+ * This function triggers a request to fetch the next page of users for a given resource. It
+ * requires that users have already been loaded for the resource (via `resolveUsers` or
+ * `getUsersState`), and that there are more users available to load (as indicated by the `hasMore`
+ * property).
+ *
+ * The function returns a promise that resolves when the next page of users has been loaded.
+ *
+ * @beta
+ */
+export declare const loadMoreUsers: BoundStoreAction<
+  UsersStoreState,
+  [options?: GetUsersOptions | undefined],
+  Promise<{
+    data: SanityUser_2[]
+    totalCount: number
+    hasMore: boolean
+  }>
+>
 
 /**
  * Logged-in state from the auth state.
@@ -1312,7 +1338,7 @@ export declare type LoggingInAuthState = {
 /**
  * @public
  */
-export declare const logout: ResourceAction<AuthStoreState, [], Promise<void>>
+export declare const logout: BoundStoreAction<AuthStoreState_2, [], Promise<void>>
 
 declare interface MapNode extends BaseNode {
   type: 'Map'
@@ -1494,6 +1520,14 @@ declare type ParseSegment<TInput extends string> = TInput extends `${infer TProp
     ? []
     : [TInput]
 
+/** @internal */
+export declare const parseUsersKey: (key: string) => {
+  batchSize: number
+  resourceType?: 'organization' | 'project'
+  projectId?: string
+  organizationId?: string
+}
+
 declare class Path {
   private pattern
   private patternRe
@@ -1558,13 +1592,10 @@ declare interface PreviewMedia {
 /**
  * @public
  */
-export declare interface PreviewStoreState extends LiveEventAwareState {
+export declare interface PreviewStoreState {
   values: {
     [TDocumentId in string]?: ValuePending<PreviewValue>
   }
-  documentTypes: {
-    [TDocumentId in string]?: string
-  }
   subscriptions: {
     [TDocumentId in string]?: {
       [TSubscriptionId in string]?: true
@@ -1575,7 +1606,7 @@ export declare interface PreviewStoreState extends LiveEventAwareState {
 /**
  * Represents the set of values displayed as a preview for a given Sanity document.
  * This includes a primary title, a secondary subtitle, an optional piece of media associated
- * with the document, and the document’s status.
+ * with the document, and the document's status.
  *
  * @public
  */
@@ -1604,26 +1635,19 @@ export declare interface PreviewValue {
   }
 }
 
+/**
+ * @public
+ */
+export declare interface ProjectHandle {
+  projectId?: string | undefined
+}
+
 declare interface ProjectionNode extends BaseNode {
   type: 'Projection'
   base: ExprNode
   expr: ExprNode
 }
 
-declare interface ProjectionStoreState<TValue extends object = object> extends LiveEventAwareState {
-  values: {
-    [TDocumentId in string]?: ProjectionValuePending<TValue>
-  }
-  documentProjections: {
-    [TDocumentId in string]?: ValidProjection
-  }
-  subscriptions: {
-    [TDocumentId in string]?: {
-      [TSubscriptionId in string]?: true
-    }
-  }
-}
-
 /**
  * @beta
  */
@@ -1639,37 +1663,23 @@ export declare function publishDocument<TDocument extends SanityDocumentLike>(
 
 /** @beta */
 export declare interface PublishDocumentAction<
-  _TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> extends DocumentHandle<TDocument> {
   type: 'document.publish'
-  documentId: string
-  resourceId?: DocumentResourceId
 }
 
 /**
  * @beta
  */
 export declare interface QueryOptions
-  extends Pick<ResponseQueryOptions, 'perspective' | 'useCdn' | 'cache' | 'next' | 'cacheMode'>,
-    Pick<ClientOptions, 'scope' | 'resourceId'> {
+  extends Pick<
+      ResponseQueryOptions,
+      'perspective' | 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'
+    >,
+    DatasetHandle {
   params?: Record<string, unknown>
 }
 
-declare interface QueryState {
-  syncTags?: string[]
-  result?: unknown
-  error?: unknown
-  lastLiveEventId?: string
-  subscribers: string[]
-}
-
-declare interface QueryStoreState {
-  queries: {
-    [key: string]: QueryState | undefined
-  }
-  error?: unknown
-}
-
 /**
  * Represents a transaction that is queued to be applied but has not yet been
  * applied. A transaction will remain in a queued state until all required
@@ -1697,80 +1707,81 @@ declare interface QueuedTransaction {
  * Signals to the store that the consumer has stopped using the channel
  * @public
  */
-export declare const releaseChannel: ResourceAction<ComlinkControllerState, [name: string], void>
+export declare const releaseChannel: BoundStoreAction_2<
+  ComlinkControllerState,
+  [name: string],
+  void
+>
 
 /**
  * Signals to the store that the consumer has stopped using the node
  * @public
  */
-export declare const releaseNode: ResourceAction<ComlinkNodeState, [name: string], void>
+export declare const releaseNode: BoundStoreAction_2<ComlinkNodeState, [name: string], void>
 
 /** @public */
-export declare const resolveDatasets: ResourceAction<
-  FetcherStoreState<[], DatasetsResponse>,
-  [],
+export declare const resolveDatasets: BoundStoreAction<
+  FetcherStoreState_2<[options?: ProjectHandle | undefined], DatasetsResponse>,
+  [options?: ProjectHandle | undefined],
   Promise<DatasetsResponse>
 >
 
 /** @beta */
 export declare function resolveDocument<TDocument extends SanityDocument>(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   doc: string | DocumentHandle<TDocument>,
 ): Promise<TDocument | null>
 
 /** @beta */
 export declare function resolveDocument(
-  instance: SanityInstance | ActionContext<DocumentStoreState>,
+  instance: SanityInstance,
   doc: string | DocumentHandle,
 ): Promise<SanityDocument | null>
 
 /** @beta */
-export declare const resolvePermissions: ResourceAction<
+export declare const resolvePermissions: BoundStoreAction<
   DocumentStoreState,
   [actions: DocumentAction | DocumentAction[]],
-  Promise<DocumentPermissionsResult>
+  Promise<DocumentPermissionsResult_2>
 >
 
 /**
  * @beta
  */
-export declare const resolvePreview: ResourceAction<
-  PreviewStoreState,
-  [ResolvePreviewOptions],
-  Promise<ValuePending<PreviewValue>>
+export declare const resolvePreview: BoundStoreAction<
+  PreviewStoreState_2,
+  [docHandle: ResolvePreviewOptions],
+  Promise<ValuePending_2<object>>
 >
 
 /**
  * @beta
  */
-export declare interface ResolvePreviewOptions {
-  document: DocumentHandle
-}
+export declare type ResolvePreviewOptions = DocumentHandle
 
 /** @public */
-export declare const resolveProject: ResourceAction<
-  FetcherStoreState<[projectId: string], SanityProject_2>,
-  [projectId: string],
+export declare const resolveProject: BoundStoreAction<
+  FetcherStoreState_2<[options?: ProjectHandle | undefined], SanityProject_2>,
+  [options?: ProjectHandle | undefined],
   Promise<SanityProject_2>
 >
 
 /**
  * @beta
  */
-export declare const resolveProjection: ResourceAction<
+export declare const resolveProjection: BoundStoreAction<
   ProjectionStoreState<object>,
   [ResolveProjectionOptions],
-  Promise<ProjectionValuePending<Record<string, unknown>>>
+  Promise<ProjectionValuePending_2<object>>
 >
 
-declare interface ResolveProjectionOptions {
-  document: DocumentHandle
+declare interface ResolveProjectionOptions extends DocumentHandle {
   projection: ValidProjection
 }
 
 /** @public */
-export declare const resolveProjects: ResourceAction<
-  FetcherStoreState<[], Omit<SanityProject_2, 'members'>[]>,
+export declare const resolveProjects: BoundStoreAction<
+  FetcherStoreState_2<[], Omit<SanityProject_2, 'members'>[]>,
   [],
   Promise<Omit<SanityProject_2, 'members'>[]>
 >
@@ -1790,14 +1801,14 @@ export declare const resolveProjects: ResourceAction<
  * @beta
  */
 export declare function resolveQuery<T>(
-  instance: SanityInstance | ActionContext<QueryStoreState>,
+  instance: SanityInstance,
   query: string,
   options?: ResolveQueryOptions,
 ): Promise<T>
 
 /** @beta */
 export declare function resolveQuery(
-  instance: SanityInstance | ActionContext<QueryStoreState>,
+  instance: SanityInstance,
   query: string,
   options?: ResolveQueryOptions,
 ): Promise<unknown>
@@ -1810,41 +1821,48 @@ declare interface ResolveQueryOptions extends QueryOptions {
 }
 
 /**
- * @public
- */
-export declare type ResourceAction<TState, TParams extends unknown[], TReturn> = (
-  dependencies: SanityInstance | ActionContext<TState>,
-  ...params: TParams
-) => TReturn
-
-/**
- * @public
- * A resource identifier for a document, in the format of `projectId.dataset`
+ * Resolves the users for a specific resource without registering a lasting subscriber.
+ *
+ * This function fetches the users for a given resource and returns a promise that resolves with
+ * the users result. Unlike `getUsersState`, which registers subscribers to keep the data live and
+ * performs automatic cleanup, `resolveUsers` does not track subscribers. This makes it ideal for
+ * use with React Suspense, where the returned promise is thrown to delay rendering until the users
+ * result becomes available. Once the promise resolves, it is expected that a real subscriber will
+ * be added via `getUsersState` to manage ongoing updates.
+ *
+ * Additionally, an optional AbortSignal can be provided to cancel the request and immediately
+ * clear the associated state if there are no active subscribers.
+ *
+ * @beta
  */
-export declare type ResourceId = `${string}.${string}`
+export declare const resolveUsers: BoundStoreAction<
+  UsersStoreState,
+  [ResolveUsersOptions],
+  Promise<{
+    data: SanityUser_2[]
+    totalCount: number
+    hasMore: boolean
+  }>
+>
 
 /**
  * @public
  */
-export declare type ResourceState<TState> = {
-  get: () => TState
-  set: (name: string, state: Partial<TState> | ((s: TState) => Partial<TState>)) => void
-  observable: Observable<TState>
+export declare interface ResolveUsersOptions extends GetUsersOptions {
+  signal?: AbortSignal
 }
 
-/**
- * @public
- */
-export declare type ResourceType = 'organization' | 'project'
-
 export {Role}
 
 /**
+ * Represents the complete configuration for a Sanity SDK instance
  * @public
  */
-export declare interface SanityConfig {
-  projectId: string
-  dataset: string
+export declare interface SanityConfig extends DatasetHandle {
+  /**
+   * Authentication configuration for the instance
+   * @remarks Merged with parent configurations when using createChild
+   */
   auth?: AuthConfig
 }
 
@@ -1852,17 +1870,57 @@ export {SanityDocument}
 
 export {SanityDocumentLike}
 
-/** @public */
+/**
+ * Represents a Sanity.io resource instance with its own configuration and lifecycle
+ * @remarks Instances form a hierarchy through parent/child relationships
+ *
+ * @public
+ */
 export declare interface SanityInstance {
   /**
-   * The following is used to look up resources associated with this instance,
-   * and can be used to retrieve an "id" for the instance - useful in debugging.
-   *
-   * @public
+   * Unique identifier for this instance
+   * @remarks Generated using crypto.randomUUID()
    */
-  readonly identity: SdkIdentity
-  config: Omit<SanityConfig, 'projectId' | 'dataset'>
-  dispose: () => void
+  readonly instanceId: string
+  /**
+   * Resolved configuration for this instance
+   * @remarks Merges values from parent instances where appropriate
+   */
+  readonly config: SanityConfig
+  /**
+   * Checks if the instance has been disposed
+   * @returns true if dispose() has been called
+   */
+  isDisposed(): boolean
+  /**
+   * Disposes the instance and cleans up associated resources
+   * @remarks Triggers all registered onDispose callbacks
+   */
+  dispose(): void
+  /**
+   * Registers a callback to be invoked when the instance is disposed
+   * @param cb - Callback to execute on disposal
+   * @returns Function to unsubscribe the callback
+   */
+  onDispose(cb: () => void): () => void
+  /**
+   * Gets the parent instance in the hierarchy
+   * @returns Parent instance or undefined if this is the root
+   */
+  getParent(): SanityInstance | undefined
+  /**
+   * Creates a child instance with merged configuration
+   * @param config - Configuration to merge with parent values
+   * @remarks Child instances inherit parent configuration but can override values
+   */
+  createChild(config: SanityConfig): SanityInstance
+  /**
+   * Traverses the instance hierarchy to find the first instance whose configuration
+   * matches the given target config using a shallow comparison.
+   * @param targetConfig - A partial configuration object containing key-value pairs to match.
+   * @returns The first matching instance or undefined if no match is found.
+   */
+  match(targetConfig: Partial<SanityConfig>): SanityInstance | undefined
 }
 
 /**
@@ -1879,15 +1937,6 @@ export declare interface SanityUser {
   memberships: Membership[]
 }
 
-/**
- * @public
- */
-declare interface SanityUserResponse {
-  data: SanityUser[]
-  totalCount: number
-  nextCursor: string | null
-}
-
 declare class Scope {
   params: Record<string, unknown>
   source: Value
@@ -1906,14 +1955,6 @@ declare class Scope {
   createHidden(value: Value): Scope
 }
 
-/** @public */
-export declare interface SdkIdentity {
-  readonly id: string
-  readonly projectId: string
-  readonly dataset: string
-  readonly resourceId: ResourceId
-}
-
 declare interface SelectAlternativeNode extends BaseNode {
   type: 'SelectAlternative'
   condition: ExprNode
@@ -1926,10 +1967,56 @@ declare interface SelectNode extends BaseNode {
   fallback?: ExprNode
 }
 
+/**
+ * Function type for selecting derived state from store state and parameters
+ * @public
+ */
+export declare type Selector<TState, TParams extends unknown[], TReturn> = (
+  context: SelectorContext<TState>,
+  ...params: TParams
+) => TReturn
+
+/**
+ * Context passed to selectors when deriving state
+ *
+ * @remarks
+ * Provides access to both the current state value and the Sanity instance,
+ * allowing selectors to use configuration values when computing derived state.
+ * The context is memoized for each state object and instance combination
+ * to optimize performance and prevent unnecessary recalculations.
+ *
+ * @example
+ * ```ts
+ * // Using both state and instance in a selector (psuedo example)
+ * const getUserByProjectId = createStateSourceAction(
+ *   ({ state, instance }: SelectorContext<UsersState>, options?: ProjectHandle) => {
+ *     const allUsers = state.users
+ *     const projectId = options?.projectId ?? instance.config.projectId
+ *     return allUsers.filter(user => user.projectId === projectId)
+ *   }
+ * )
+ * ```
+ */
+declare interface SelectorContext<TState> {
+  /**
+   * The current state object from the store
+   */
+  state: TState
+  /**
+   * The Sanity instance associated with this state
+   */
+  instance: SanityInstance
+}
+
 declare interface SelectorNode extends BaseNode {
   type: 'Selector'
 }
 
+declare interface SharedListener {
+  events: Observable<ListenEvent<SanityDocument_2>>
+  dispose: () => void
+}
+
 declare type SingleValuePath = Exclude<PathSegment, IndexTuple>[]
 
 declare interface SliceNode extends BaseNode {
@@ -1941,11 +2028,40 @@ declare interface SliceNode extends BaseNode {
 }
 
 /**
+ * Represents a reactive state source that provides synchronized access to store data
+ *
+ * @remarks
+ * Designed to work with React's useSyncExternalStore hook. Provides three ways to access data:
+ * 1. `getCurrent()` for synchronous current value access
+ * 2. `subscribe()` for imperative change notifications
+ * 3. `observable` for reactive stream access
+ *
  * @public
  */
 export declare interface StateSource<T> {
+  /**
+   * Subscribes to state changes with optional callback
+   * @param onStoreChanged - Called whenever relevant state changes occur
+   * @returns Unsubscribe function to clean up the subscription
+   */
   subscribe: (onStoreChanged?: () => void) => () => void
+  /**
+   * Gets the current derived state value
+   *
+   * @remarks
+   * Safe to call without subscription. Will always return the latest value
+   * based on the current store state and selector parameters.
+   */
   getCurrent: () => T
+  /**
+   * Observable stream of state values
+   *
+   * @remarks
+   * Shares a single underlying subscription between all observers. Emits:
+   * - Immediately with current value on subscription
+   * - On every relevant state change
+   * - Errors if selector throws
+   */
   observable: Observable<T>
 }
 
@@ -1960,6 +2076,7 @@ declare class StaticValue<P, T extends GroqType> {
 
 declare interface StoreEntry<TParams extends unknown[], TData> {
   params: TParams
+  instance: SanityInstance
   key: string
   data?: TData
   error?: unknown
@@ -1983,7 +2100,7 @@ declare class StreamValue {
 declare type StringValue = StaticValue<string, 'string'>
 
 /** @beta */
-export declare const subscribeDocumentEvents: ResourceAction<
+export declare const subscribeDocumentEvents: BoundStoreAction<
   DocumentStoreState,
   [eventHandler: (e: DocumentEvent) => void],
   () => void
@@ -2030,11 +2147,9 @@ export declare function unpublishDocument<TDocument extends SanityDocumentLike>(
 
 /** @beta */
 export declare interface UnpublishDocumentAction<
-  _TDocument extends SanityDocumentLike = SanityDocumentLike,
-> {
+  TDocument extends SanityDocumentLike = SanityDocumentLike,
+> extends DocumentHandle<TDocument> {
   type: 'document.unpublish'
-  documentId: string
-  resourceId?: DocumentResourceId
 }
 
 declare interface UnverifiedDocumentRevision {
@@ -2066,20 +2181,23 @@ export declare interface UserProfile {
 /**
  * @public
  */
-export declare interface UsersStoreState {
-  users: SanityUser[]
-  totalCount: number
-  nextCursor: string | null
-  hasMore: boolean
-  initialFetchCompleted: boolean
-  options: {
-    resourceType: ResourceType
-    resourceId: string
-    /**
-     * The maximum number of users to fetch. [Default: 100]
-     */
-    limit?: number
+declare interface UsersGroupState {
+  subscriptions: string[]
+  totalCount?: number
+  nextCursor?: string | null
+  lastLoadMoreRequest?: string
+  users?: SanityUser[]
+  error?: unknown
+}
+
+/**
+ * @public
+ */
+declare interface UsersStoreState {
+  users: {
+    [TUsersKey in string]?: UsersGroupState
   }
+  error?: unknown
 }
 
 /**