@sanity/sdk 3.0.0-rc.0 → 3.0.0-rc.1

package/dist/_chunks-dts/createGroqSearchFilter.d.ts

@@ -0,0 +1,1147 @@
+import { ClientConfig, ClientError, ClientPerspective, ResponseQueryOptions, SanityClient, StackablePerspective } from "@sanity/client";
+import { CurrentUser } from "@sanity/types";
+import { Observable } from "rxjs";
+import "zustand/middleware";
+import { SanityQueryResult } from "groq";
+/**
+ * Configuration for an authentication provider
+ * @public
+ */
+interface AuthProvider {
+  /**
+   * Unique identifier for the auth provider (e.g., 'google', 'github')
+   */
+  name: string;
+  /**
+   * Display name for the auth provider in the UI
+   */
+  title: string;
+  /**
+   * Complete authentication URL including callback and token parameters
+   */
+  url: string;
+  /**
+   * Optional URL for direct sign-up flow
+   */
+  signUpUrl?: string;
+}
+/**
+ * Configuration options for creating an auth store.
+ *
+ * @public
+ */
+interface AuthConfig {
+  /**
+   * The initial location href to use when handling auth callbacks.
+   * Defaults to the current window location if available.
+   */
+  initialLocationHref?: string;
+  /**
+   * Factory function to create a SanityClient instance.
+   * Defaults to the standard Sanity client factory if not provided.
+   */
+  clientFactory?: (config: ClientConfig) => SanityClient;
+  /**
+   * Custom authentication providers to use instead of or in addition to the default ones.
+   * Can be an array of providers or a function that takes the default providers and returns
+   * a modified array or a Promise resolving to one.
+   */
+  providers?: AuthProvider[] | ((prev: AuthProvider[]) => AuthProvider[] | Promise<AuthProvider[]>);
+  /**
+   * The API hostname for requests. Usually leave this undefined, but it can be set
+   * if using a custom domain or CNAME for the API endpoint.
+   */
+  apiHost?: string;
+  /**
+   * Storage implementation to persist authentication state.
+   * Defaults to `localStorage` if available.
+   */
+  storageArea?: Storage;
+  /**
+   * A callback URL for your application.
+   * If none is provided, the auth API will redirect back to the current location (`location.href`).
+   * When handling callbacks, this URL's pathname is checked to ensure it matches the callback.
+   */
+  callbackUrl?: string;
+  /**
+   * A static authentication token to use instead of handling the OAuth flow.
+   * When provided, the auth store will remain in a logged-in state with this token,
+   * ignoring any storage or callback handling.
+   */
+  token?: string;
+}
+/**
+ * A minimal Observable-compatible interface for subscribing to token changes.
+ * Any object with a `subscribe` method that follows this contract will work,
+ * including RxJS Observables. This avoids coupling the SDK to a specific
+ * reactive library.
+ *
+ * @public
+ */
+interface TokenSource {
+  /** Subscribe to token emissions. Emits `null` when logged out. */
+  subscribe(observer: {
+    next: (token: string | null) => void;
+  }): {
+    unsubscribe(): void;
+  };
+}
+/**
+ * Studio-specific configuration for the SDK.
+ * When present, the SDK operates in studio mode and derives auth from the
+ * provided token source instead of discovering tokens independently.
+ *
+ * @public
+ */
+interface StudioConfig {
+  /**
+   * Whether the Studio has already determined the user is authenticated.
+   * When `true` and the token source emits `null`, the SDK infers
+   * cookie-based auth is in use rather than transitioning to logged-out.
+   */
+  authenticated?: boolean;
+  /** Reactive auth token source from the Studio's auth store. */
+  auth?: {
+    /**
+     * A reactive token source. The SDK subscribes and stays in sync — the
+     * Studio is the single authority for auth and handles token refresh.
+     *
+     * Optional because older Studios may not expose it. When absent, the
+     * SDK falls back to localStorage/cookie discovery.
+     */
+    token?: TokenSource;
+  };
+}
+/**
+ * Represents the minimal configuration required to identify a Sanity project.
+ * @public
+ */
+interface ProjectHandle<TProjectId extends string = string> {
+  projectId?: TProjectId;
+}
+/**
+ * @public
+ */
+type ReleasePerspective = {
+  releaseName: string;
+  excludedPerspectives?: StackablePerspective[];
+};
+/**
+ * @public
+ */
+interface PerspectiveHandle {
+  perspective?: ClientPerspective | ReleasePerspective;
+}
+/**
+ * @public
+ */
+interface DatasetHandle<TDataset extends string = string, TProjectId extends string = string> extends ProjectHandle<TProjectId>, PerspectiveHandle {
+  dataset?: TDataset;
+  /**
+   * @beta
+   * Explicit resource object to use for this operation.
+   */
+  resource?: DocumentResource;
+  /**
+   * @deprecated Use `resource` instead.
+   * @beta
+   */
+  source?: DocumentResource;
+}
+/**
+ * Identifies a specific document type within a Sanity dataset and project.
+ * Includes `projectId`, `dataset`, and `documentType`.
+ * Optionally includes a `documentId` and `liveEdit` flag.
+ * @public
+ */
+interface DocumentTypeHandle<TDocumentType extends string = string, TDataset extends string = string, TProjectId extends string = string> extends DatasetHandle<TDataset, TProjectId> {
+  documentId?: string;
+  documentType: TDocumentType;
+  /**
+   * Indicates whether this document uses liveEdit mode.
+   * When `true`, the document does not use the draft/published model and edits are applied directly to the document.
+   * @see https://www.sanity.io/docs/content-lake/drafts#ca0663a8f002
+   */
+  liveEdit?: boolean;
+}
+/**
+ * Uniquely identifies a specific document within a Sanity dataset and project.
+ * Includes `projectId`, `dataset`, `documentType`, and the required `documentId`.
+ * Commonly used by document-related hooks and components to reference a document without fetching its full content initially.
+ * @public
+ */
+interface DocumentHandle<TDocumentType extends string = string, TDataset extends string = string, TProjectId extends string = string> extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
+  documentId: string;
+}
+/**
+ * Identifies a release within a Sanity dataset and project. `releaseId` is the
+ * `name` parameter on the release document (e.g. `{name: 'r41035a4'}`).
+ * The underlying release document ID is `_.releases.<releaseId>`.
+ * It's also the `id` parameter sent to the Actions API.
+ * (This type doesn't need to have ProjectId / Dataset generics since it's always the same shape)
+ * @beta
+ */
+interface ReleaseHandle extends DatasetHandle {
+  releaseId: string;
+}
+/**
+ * Represents the complete configuration for a Sanity SDK instance
+ * @public
+ */
+interface SanityConfig extends DatasetHandle, PerspectiveHandle {
+  /**
+   * Authentication configuration for the instance
+   */
+  auth?: AuthConfig;
+  /**
+   * Studio configuration provided by a Sanity Studio workspace.
+   * When present, the SDK operates in studio mode and derives auth from the
+   * workspace's reactive token source — no manual configuration needed.
+   *
+   * @remarks Typically set automatically by `SanityApp` when it detects an
+   * `SDKStudioContext` provider. Can also be set explicitly for programmatic use.
+   */
+  studio?: StudioConfig;
+  /**
+   * Studio mode configuration for use of the SDK in a Sanity Studio.
+   * @remarks Controls whether studio mode features are enabled.
+   * @deprecated Use `studio` instead, which provides richer integration
+   * with the Studio's workspace (auth token sync, etc.).
+   */
+  studioMode?: {
+    enabled: boolean;
+  };
+  /**
+   * @beta
+   * A list of named resources to use for this instance.
+   */
+  resources?: Record<string, DocumentResource>;
+  /**
+   * @deprecated Use `resources` instead.
+   * @beta
+   */
+  sources?: Record<string, DocumentResource>;
+}
+/**
+ * A document resource can be used for querying.
+ * This will soon be the default way to identify where you are querying from.
+ *
+ * @beta
+ */
+type DocumentResource = DatasetResource | MediaLibraryResource | CanvasResource;
+/**
+ * @beta
+ */
+type DatasetResource = {
+  projectId: string;
+  dataset: string;
+};
+/**
+ * @beta
+ */
+type MediaLibraryResource = {
+  mediaLibraryId: string;
+};
+/**
+ * @beta
+ */
+type CanvasResource = {
+  canvasId: string;
+};
+/**
+ * @beta
+ */
+declare function isDatasetResource(resource: DocumentResource): resource is DatasetResource;
+/**
+ * @beta
+ */
+declare function isMediaLibraryResource(resource: DocumentResource): resource is MediaLibraryResource;
+/**
+ * @beta
+ */
+declare function isCanvasResource(resource: DocumentResource): resource is CanvasResource;
+/**
+ * @deprecated Use `DocumentResource` instead.
+ * @beta
+ */
+type DocumentSource = DocumentResource;
+/**
+ * @deprecated Use `DatasetResource` instead.
+ * @beta
+ */
+type DatasetSource = DatasetResource;
+/**
+ * @deprecated Use `MediaLibraryResource` instead.
+ * @beta
+ */
+type MediaLibrarySource = MediaLibraryResource;
+/**
+ * @deprecated Use `CanvasResource` instead.
+ * @beta
+ */
+type CanvasSource = CanvasResource;
+/**
+ * @deprecated Use `isDatasetResource` instead.
+ * @beta
+ */
+declare function isDatasetSource(source: DocumentSource): source is DatasetSource;
+/**
+ * @deprecated Use `isMediaLibraryResource` instead.
+ * @beta
+ */
+declare function isMediaLibrarySource(source: DocumentSource): source is MediaLibrarySource;
+/**
+ * @deprecated Use `isCanvasResource` instead.
+ * @beta
+ */
+declare function isCanvasSource(source: DocumentSource): source is CanvasSource;
+/**
+ * Returns `true` when the config indicates the SDK is running inside a Studio.
+ * Checks the new `studio` field first, then falls back to the deprecated
+ * `studioMode.enabled` for backwards compatibility.
+ *
+ * @internal
+ */
+declare function isStudioConfig(config: SanityConfig): boolean;
+/**
+ * Represents a Sanity.io resource instance with its own configuration and lifecycle
+ *
+ * @public
+ */
+interface SanityInstance {
+  /**
+   * Unique identifier for this instance
+   * @remarks Generated using crypto.randomUUID()
+   */
+  readonly instanceId: string;
+  /**
+   * Resolved configuration for this instance
+   */
+  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
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  getParent(): SanityInstance | undefined;
+  /**
+   * Creates a child instance with merged configuration
+   * @param config - Configuration to merge with parent values
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  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.
+   * @deprecated The parent/child instance hierarchy is deprecated. Use a single SanityInstance instead.
+   */
+  match(targetConfig: Partial<SanityConfig>): SanityInstance | undefined;
+}
+/**
+ * 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
+ */
+declare function createSanityInstance(config?: SanityConfig): SanityInstance;
+/**
+ * Represents a reactive store state container with multiple access patterns
+ */
+interface StoreState<TState> {
+  /**
+   * Gets the current state value
+   *
+   * @remarks
+   * This is a direct synchronous accessor that doesn't trigger subscriptions
+   */
+  get: () => TState;
+  /**
+   * Updates the store state
+   * @param name - Action name for devtools tracking
+   * @param updatedState - New state value or updater function
+   *
+   * @remarks
+   * When providing a partial object, previous top-level keys not included in
+   * the update will be preserved.
+   */
+  set: (name: string, updatedState: Partial<TState> | ((s: TState) => Partial<TState>)) => void;
+  /**
+   * Observable stream of state changes
+   * @remarks
+   * - Emits immediately with current state on subscription
+   * - Shares underlying subscription between observers
+   * - Only emits when state reference changes
+   * - Completes when store is disposed
+   */
+  observable: Observable<TState>;
+}
+/**
+ * Context object provided to store initialization functions
+ */
+interface StoreContext<TState, TKey = unknown> {
+  /**
+   * Sanity instance associated with this store
+   *
+   * @remarks
+   * Provides access to the Sanity configuration and instance lifecycle methods
+   */
+  instance: SanityInstance;
+  /**
+   * Reactive store state management utilities
+   *
+   * @remarks
+   * Contains methods for getting/setting state and observing changes
+   */
+  state: StoreState<TState>;
+  /**
+   * The key used to instantiate the store.
+   */
+  key: TKey;
+}
+/**
+ * Defines a store action that operates on a specific state type
+ */
+type StoreAction<TState, TParams extends unknown[], TReturn, TKey = unknown> = (context: StoreContext<TState, TKey>, ...params: TParams) => TReturn;
+/**
+ * Represents a store action that has been bound to a specific store instance
+ */
+type BoundStoreAction<_TState, TParams extends unknown[], TReturn> = (instance: SanityInstance, ...params: TParams) => TReturn;
+/**
+ * Represents the various states the authentication type can be in.
+ *
+ * @public
+ */
+declare enum AuthStateType {
+  LOGGED_IN = "logged-in",
+  LOGGING_IN = "logging-in",
+  ERROR = "error",
+  LOGGED_OUT = "logged-out"
+}
+/**
+ * Represents the various states the authentication can be in.
+ *
+ * @public
+ */
+type AuthState = LoggedInAuthState | LoggedOutAuthState | LoggingInAuthState | ErrorAuthState;
+/**
+ * Logged-in state from the auth state.
+ * @public
+ */
+type LoggedInAuthState = {
+  type: AuthStateType.LOGGED_IN;
+  token: string;
+  currentUser: CurrentUser | null;
+  lastTokenRefresh?: number;
+};
+/**
+ * Logged-out state from the auth state.
+ * @public
+ */
+type LoggedOutAuthState = {
+  type: AuthStateType.LOGGED_OUT;
+  isDestroyingSession: boolean;
+};
+/**
+ * Logging-in state from the auth state.
+ * @public
+ */
+type LoggingInAuthState = {
+  type: AuthStateType.LOGGING_IN;
+  isExchangingToken: boolean;
+};
+/**
+ * Error state from the auth state.
+ * @public
+ */
+type ErrorAuthState = {
+  type: AuthStateType.ERROR;
+  error: unknown;
+};
+/**
+ * Represents the various states the authentication can be in.
+ *
+ * @public
+ */
+interface DashboardContext {
+  mode?: string;
+  env?: string;
+  orgId?: string;
+}
+/**
+ * The method of authentication used.
+ * @internal
+ */
+type AuthMethodOptions = 'localstorage' | 'cookie' | undefined;
+/**
+ * @public
+ */
+interface AuthStoreState {
+  authState: AuthState;
+  providers?: AuthProvider[];
+  options: {
+    initialLocationHref: string;
+    clientFactory: (config: ClientConfig) => SanityClient;
+    customProviders: AuthConfig['providers'];
+    storageKey: string;
+    storageArea: Storage | undefined;
+    apiHost: string | undefined;
+    loginUrl: string;
+    callbackUrl: string | undefined;
+    providedToken: string | undefined;
+    authMethod: AuthMethodOptions;
+  };
+  dashboardContext?: DashboardContext;
+}
+/**
+ * @public
+ */
+declare const getCurrentUserState: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<CurrentUser | null>>;
+/**
+ * @public
+ */
+declare const getTokenState: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<string | null>>;
+/**
+ * @public
+ */
+declare const getLoginUrlState: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<string>>;
+/**
+ * @public
+ */
+declare const getAuthState: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<AuthState>>;
+/**
+ * @public
+ */
+declare const getDashboardOrganizationId: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<string | undefined>>;
+/**
+ * Returns a state source indicating if the SDK is running within a dashboard context.
+ * @public
+ */
+declare const getIsInDashboardState: BoundStoreAction<AuthStoreState, [], import("../_exports").StateSource<boolean>>;
+/**
+ * Action to explicitly set the authentication token.
+ * Used internally by the Comlink token refresh.
+ * @internal
+ */
+declare const setAuthToken: BoundStoreAction<AuthStoreState, [token: string | null], void>;
+/** @internal */
+type ApiErrorBody = {
+  error?: {
+    type?: string;
+    description?: string;
+  };
+  type?: string;
+  description?: string;
+  message?: string;
+};
+/** @internal Extracts the structured API error body from a ClientError, if present. */
+declare function getClientErrorApiBody(error: ClientError): ApiErrorBody | undefined;
+/** @internal Returns the error type string from an API error body, if available. */
+declare function getClientErrorApiType(error: ClientError): string | undefined;
+/** @internal Returns the error description string from an API error body, if available. */
+declare function getClientErrorApiDescription(error: ClientError): string | undefined;
+/** @internal True if the error represents a projectUserNotFoundError. */
+declare function isProjectUserNotFoundClientError(error: ClientError): boolean;
+/**
+ * Generates a GROQ projection for preview data without requiring a schema.
+ * Uses common field names to make educated guesses about which fields to use.
+ *
+ * @internal
+ */
+declare const PREVIEW_PROJECTION: string;
+/**
+ * @public
+ * The result of a projection query
+ */
+interface ProjectionValuePending<TValue extends object> {
+  data: TValue | null;
+  isPending: boolean;
+}
+/**
+ * @public
+ * @deprecated
+ * Template literals are a bit too limited, so this type is deprecated.
+ * Use `string` instead. Projection strings are validated at runtime.
+ */
+type ValidProjection = string;
+interface DocumentStatus {
+  lastEditedDraftAt?: string;
+  lastEditedPublishedAt?: string;
+  lastEditedVersionAt?: string;
+}
+/**
+ *
+ * @internal
+ */
+interface PreviewQueryResult {
+  _id: string;
+  _type: string;
+  _updatedAt: string;
+  titleCandidates: Record<string, unknown>;
+  subtitleCandidates: Record<string, unknown>;
+  media?: PreviewMedia | null;
+  _status?: DocumentStatus;
+}
+/**
+ * Represents a media asset in a preview.
+ *
+ * @public
+ */
+interface PreviewMedia {
+  type: 'image-asset';
+  _ref: string;
+  url: string;
+}
+/**
+ * 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.
+ *
+ * @public
+ */
+interface PreviewValue {
+  /**
+   * The primary text displayed for the document preview.
+   */
+  title: string;
+  /**
+   * A secondary line of text providing additional context about the document.
+   */
+  subtitle?: string;
+  /**
+   * An optional piece of media representing the document within its preview.
+   * Currently, only image assets are available.
+   */
+  media?: PreviewMedia | null;
+  /**
+   * The status of the document.
+   */
+  _status?: {
+    /** The date of the last published edit */
+    lastEditedPublishedAt?: string;
+    /** The date of the last draft edit */
+    lastEditedDraftAt?: string;
+  };
+}
+/**
+ * Represents the current state of a preview value along with a flag indicating whether
+ * the preview data is still being fetched or is fully resolved.
+ *
+ * The tuple contains a preview value or null, and a boolean indicating if the data is
+ * pending. A `true` value means a fetch is ongoing; `false` indicates that the
+ * currently provided preview value is up-to-date.
+ *
+ * @public
+ */
+type ValuePending<T> = {
+  data: T | null;
+  isPending: boolean;
+};
+/**
+ * @public
+ * @deprecated This interface is kept for backwards compatibility but is no longer used internally.
+ * Preview state is now stored in the projection store.
+ */
+interface PreviewStoreState {
+  values: { [TDocumentId in string]?: ValuePending<PreviewValue>; };
+  subscriptions: { [TDocumentId in string]?: { [TSubscriptionId in string]?: true; }; };
+}
+/**
+ * Transforms a projection result (with titleCandidates, subtitleCandidates, media)
+ * into a PreviewValue (with title, subtitle, media).
+ *
+ * @param projectionResult - The raw projection result from GROQ
+ * @param instance - The Sanity instance to use for client configuration
+ * @param resource - Data resource for the preview
+ * @internal
+ */
+declare function transformProjectionToPreview(instance: SanityInstance, projectionResult: PreviewQueryResult, resource?: DocumentResource): PreviewValue;
+/**
+ * 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
+ */
+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>;
+}
+/**
+ * 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)
+ *   }
+ * )
+ * ```
+ */
+interface SelectorContext<TState> {
+  /**
+   * The current state object from the store
+   */
+  state: TState;
+  /**
+   * The Sanity instance associated with this state
+   */
+  instance: SanityInstance;
+}
+/**
+ * Function type for selecting derived state from store state and parameters
+ * @public
+ */
+type Selector<TState, TParams extends unknown[], TReturn> = (context: SelectorContext<TState>, ...params: TParams) => TReturn;
+/**
+ * @beta
+ */
+interface QueryOptions<TQuery extends string = string, TDataset extends string = string, TProjectId extends string = string> extends Pick<ResponseQueryOptions, 'useCdn' | 'cache' | 'next' | 'cacheMode' | 'tag'>, DatasetHandle<TDataset, TProjectId> {
+  query: TQuery;
+  params?: Record<string, unknown>;
+}
+/**
+ * @beta
+ */
+interface ResolveQueryOptions<TQuery extends string = string, TDataset extends string = string, TProjectId extends string = string> extends QueryOptions<TQuery, TDataset, TProjectId> {
+  signal?: AbortSignal;
+}
+/** @beta */
+declare const getQueryKey: (options: QueryOptions) => string;
+/** @beta */
+declare const parseQueryKey: (key: string) => QueryOptions;
+/**
+ * Returns the state source for a query.
+ *
+ * This function returns a state source that represents the current result of a GROQ query.
+ * Subscribing to the state source will instruct the SDK to fetch the query (if not already fetched)
+ * and will keep the query live using the Live content API (considering sync tags) to provide up-to-date results.
+ * When the last subscriber is removed, the query state is automatically cleaned up from the store.
+ *
+ * Note: This functionality is for advanced users who want to build their own framework integrations.
+ * Our SDK also provides a React integration (useQuery hook) for convenient usage.
+ *
+ * Note: Automatic cleanup can interfere with React Suspense because if a component suspends while being the only subscriber,
+ * cleanup might occur unexpectedly. In such cases, consider using `resolveQuery` instead.
+ *
+ * @beta
+ */
+declare function getQueryState<TQuery extends string = string, TDataset extends string = string, TProjectId extends string = string>(instance: SanityInstance, queryOptions: QueryOptions<TQuery, TDataset, TProjectId>): StateSource<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`> | undefined>;
+/** @beta */
+declare function getQueryState<TData>(instance: SanityInstance, queryOptions: QueryOptions): StateSource<TData | undefined>;
+/** @beta */
+declare function getQueryState(instance: SanityInstance, queryOptions: QueryOptions): StateSource<unknown>;
+/**
+ * Resolves the result of a query without registering a lasting subscriber.
+ *
+ * This function fetches the result of a GROQ query and returns a promise that resolves with the query result.
+ * It registers a temporary subscriber for the lifetime of the resolution (released shortly after the promise
+ * settles), so the query state participates in normal cleanup even when no lasting subscriber ever attaches —
+ * e.g. when a suspended component errors before committing. This makes it ideal for use with React Suspense,
+ * where the returned promise is thrown to delay rendering until the query result becomes available.
+ * Once the promise resolves, it is expected that a real subscriber will be added via `getQueryState` to manage ongoing updates.
+ *
+ * Additionally, an optional AbortSignal can be provided to cancel the query and immediately clear the associated state
+ * if there are no other active subscribers.
+ *
+ * @beta
+ */
+declare function resolveQuery<TQuery extends string = string, TDataset extends string = string, TProjectId extends string = string>(instance: SanityInstance, queryOptions: ResolveQueryOptions<TQuery, TDataset, TProjectId>): Promise<SanityQueryResult<TQuery, `${TProjectId}.${TDataset}`>>;
+/** @beta */
+declare function resolveQuery<TData>(instance: SanityInstance, queryOptions: ResolveQueryOptions): Promise<TData>;
+/**
+ * Identifies cached data for invalidation, matched across the whole store.
+ * A fetcher declares the tags each of its entries carries (via
+ * {@link FetcherDefinition.tags}); a mutation declares the tags it invalidates
+ * (via {@link MutationDefinition.invalidates}).
+ *
+ * When invalidating,`{type: 'organization'}` matches every entry carrying any `organization` tag;
+ * `{type: 'organization', id: 'abc'}` matches only entries carrying that exact pair.
+ * List entries carry a `{type, id: 'LIST'}` sentinel plus one tag per item, so a
+ * "create" mutation can refetch lists without touching unrelated detail entries.
+ *
+ * @internal
+ */
+interface CacheTag {
+  type: string;
+  /** Specific id, or the `'LIST'` sentinel for list entries */
+  id?: string | number;
+}
+/**
+ * The reactive value of one cache entry, as exposed by
+ * {@link Fetcher.getState}. React hooks consume this envelope directly.
+ * Discriminated on `status`, so narrowing gives correctly-typed `data`:
+ * `'success'` is the only arm carrying data, and a background failure while
+ * data still renders surfaces on the `'success'` arm's `error`.
+ *
+ * `isFetching` is common to all arms: a fetch for this entry is in flight
+ * (initial load, revalidation, or poll).
+ *
+ * @internal
+ */
+type FetcherSnapshot<TData> = {
+  /** No data yet — initial fetch in flight or not started */
+  status: 'pending';
+  data: undefined;
+  error: undefined;
+  isFetching: boolean;
+  dataUpdatedAt: undefined;
+} | {
+  /** Data available — possibly stale, possibly revalidating */
+  status: 'success';
+  data: TData;
+  /** Most recent background-fetch failure, cleared by the next successful fetch */
+  error: unknown;
+  isFetching: boolean;
+  /** Epoch ms of the fetch that produced `data` */
+  dataUpdatedAt: number;
+} | {
+  /** The last fetch failed and no data exists to serve */
+  status: 'error';
+  data: undefined;
+  error: unknown;
+  isFetching: boolean;
+  dataUpdatedAt: undefined;
+};
+/**
+ * A typed description of one cached, parameterised read of an API response —
+ * here is a single cache per {@link SanityInstance}; every definition registers
+ * into it and its `name` namespaces its keys. A list and a detail read are two
+ * definitions over the one cache, not two caches.
+ *
+ * Entry lifecycle: fresh → stale → collected. Fresh entries are served from
+ * cache with no fetch; stale entries are served immediately and revalidated in
+ * the background (stale-while-revalidate); collected entries are removed once
+ * their `gcTime` elapses after the last unsubscribe, so the next subscriber
+ * suspends.
+ *
+ * @internal
+ */
+interface FetcherDefinition<TParams extends unknown[], TData> {
+  /** Namespaces this fetcher's keys in the shared cache; used for devtools and request-tag derivation */
+  name: string;
+  /**
+   * Fetches the data once. Return an observable that emits the result and
+   * completes.
+   */
+  fetch: (instance: SanityInstance) => (...params: TParams) => Observable<TData>;
+  /** Converts params into the cache key that identifies an entry (unique within `name`) */
+  getKey: (instance: SanityInstance, ...params: TParams) => string;
+  /**
+   * Cache tags each entry carries, for cache-wide invalidation. A static array,
+   * or a function of the fetched data when tags depend on the response (e.g. one
+   * tag per list item).
+   */
+  tags?: CacheTag[] | ((data: TData, ...params: TParams) => CacheTag[]);
+  /**
+   * How long fetched data is fresh, in ms. Fresh entries never refetch;
+   * stale entries serve cached data and revalidate in the background.
+   * @defaultValue 30_000
+   */
+  staleTime?: number;
+  /**
+   * How long an entry survives after its last unsubscribe before it is garbage
+   * collected, in ms. The clock starts at the last unsubscribe — entries with
+   * active subscribers are never collected.
+   * @defaultValue 300_000
+   */
+  gcTime?: number;
+  /**
+   * Refetch on this interval (ms) while the entry has at least one subscriber,
+   * independent of staleness. Ticks are skipped while `document.hidden`. Off by default.
+   */
+  refetchInterval?: number;
+  /**
+   * Consulted once, when an entry is being created and no cached data exists for
+   * it. Return data pulled from another fetcher in the same cache — read via its
+   * ordinary `getState(instance, ...).getCurrent()`, e.g. a detail entry pulling
+   * its item out of the cached list — to skip or soften the initial fetch.
+   * `dataUpdatedAt` must be when the source data was fetched, not "now": staleness
+   * is measured from it. Return `undefined` to fetch as normal.
+   */
+  initialData?: (instance: SanityInstance, ...params: TParams) => {
+    data: TData;
+    dataUpdatedAt: number;
+  } | undefined;
+}
+/**
+ * A typed handle over the shared fetcher cache, returned by
+ * {@link defineFetcher}. It is a view onto the entries under its definition's
+ * `name`, not a cache of its own.
+ *
+ * @internal
+ */
+interface Fetcher<TParams extends unknown[], TData> {
+  /** Reactive envelope for one entry. Subscribing triggers fetching per staleness rules. */
+  getState: (instance: SanityInstance, ...params: TParams) => StateSource<FetcherSnapshot<TData>>;
+  /**
+   * Resolves with the entry's first available data — the promise a suspending
+   * component throws. Rejects if the initial fetch fails.
+   */
+  resolveState: (instance: SanityInstance, ...params: TParams) => Promise<TData>;
+  /**
+   * Marks the entry stale. If it has active subscribers it refetches immediately;
+   * otherwise it refetches on next subscribe.
+   */
+  invalidate: (instance: SanityInstance, ...params: TParams) => void;
+  /** {@link Fetcher.invalidate} for every entry under this fetcher's `name`. */
+  invalidateAll: (instance: SanityInstance) => void;
+  /**
+   * Imperative fetch, bypassing staleness. Dedupes against an in-flight fetch.
+   * Resolves with the entry's data as held by the cache once the fetch settles.
+   */
+  refetch: (instance: SanityInstance, ...params: TParams) => Promise<TData>;
+  /**
+   * Writes an entry's data directly. Returns an undo handle — inside a
+   * mutation's `onMutate` these writes are recorded and rolled back automatically
+   * on failure.
+   */
+  setData: (instance: SanityInstance, params: TParams, updater: TData | ((current: TData | undefined) => TData)) => {
+    undo: () => void;
+  };
+}
+/**
+ * Writes an entry's data in any fetcher. Passed to {@link MutationDefinition}
+ * callbacks — mutations are the only holders of arbitrary write access; read
+ * fetchers pull their data (see {@link FetcherDefinition.initialData}). Inside
+ * `onMutate`, every write is recorded and undone automatically if the mutation
+ * fails.
+ *
+ * @internal
+ */
+type CacheWriter = <TParams extends unknown[], TData>(fetcher: Fetcher<TParams, TData>, params: TParams, updater: TData | ((current: TData | undefined) => TData)) => void;
+/**
+ * Resolves when the mutation settles on the server. `invalidated` tracks the
+ * background reconciliation — the refetches triggered by
+ * {@link MutationDefinition.invalidates} — for the rare caller that must wait for
+ * full reconvergence rather than server settlement.
+ *
+ * @internal
+ */
+interface MutationResult<TResult> {
+  /** The server response */
+  data: TResult;
+  /** Settles when the refetches of matched active entries complete */
+  invalidated: Promise<void>;
+}
+/**
+ * Defines a mutation with optimistic cache updates. Lifecycle:
+ *
+ * 1. `onMutate` applies optimistic writes synchronously — the UI updates before
+ *    the request leaves. Each entry carries a version counter that increments on
+ *    every write. An optimistic write bumps the counter, so a revalidation already
+ *    in flight lands "out of date" and is discarded rather than clobbering the
+ *    optimistic write.
+ * 2. The request runs. On failure, recorded writes are rolled back automatically
+ *    — the cache is restored exactly, so failure ends the lifecycle here.
+ * 3. On success, `onSuccess` may write the server response into the cache directly.
+ * 4. On success, `invalidates` tags mark matching entries across the cache
+ *    stale (active entries refetch), so the cache reconverges on server truth
+ *    even if the optimistic shape was wrong.
+ *
+ * @internal
+ */
+interface MutationDefinition<TInput, TResult> {
+  /** Unique mutation name, used for devtools and request-tag derivation */
+  name: string;
+  /** Creates the observable that performs the server mutation */
+  mutationFn: (instance: SanityInstance) => (input: TInput) => Observable<TResult>;
+  /** Optimistic cache writes, applied synchronously before the request */
+  onMutate?: (write: CacheWriter, input: TInput) => void;
+  /** Reconcile the cache with the server response, avoiding a refetch round-trip */
+  onSuccess?: (write: CacheWriter, result: TResult, input: TInput) => void;
+  /**
+   * Cache tags to invalidate on success. Failure invalidates nothing: recorded
+   * optimistic writes roll back to the exact pre-mutation cache, and any
+   * server-side ambiguity (e.g. timeout after commit) heals via `staleTime`.
+   * A static array, or a function of the result/input.
+   */
+  invalidates?: CacheTag[] | ((result: TResult, input: TInput) => CacheTag[]);
+}
+/**
+ * Registers a fetcher definition against the shared cache and returns its typed
+ * handle.
+ *
+ * @internal
+ */
+declare function defineFetcher<TParams extends unknown[], TData>(definition: FetcherDefinition<TParams, TData>): Fetcher<TParams, TData>;
+/**
+ * Creates a bound mutation from its definition. The returned action resolves at
+ * server settlement — not after invalidation refetches, which run as background
+ * reconciliation (see {@link MutationResult.invalidated}).
+ *
+ * @internal
+ */
+declare function defineMutation<TInput, TResult>(definition: MutationDefinition<TInput, TResult>): (instance: SanityInstance, input: TInput) => Promise<MutationResult<TResult>>;
+/**
+ * @public
+ */
+interface SanityUser {
+  sanityUserId: string;
+  profile: UserProfile;
+  memberships: Membership[];
+}
+/**
+ * @public
+ */
+interface Membership {
+  addedAt?: string;
+  resourceType: string;
+  resourceId: string;
+  roleNames: Array<string>;
+  lastSeenAt?: string | null;
+}
+/**
+ * @public
+ */
+interface UserProfile {
+  id: string;
+  displayName: string;
+  email: string;
+  familyName?: string;
+  givenName?: string;
+  middleName?: string | null;
+  imageUrl?: string;
+  provider: string;
+  tosAcceptedAt?: string;
+  createdAt: string;
+  updatedAt?: string;
+  isCurrentUser?: boolean;
+  providerId?: string;
+}
+/**
+ * @public
+ */
+interface GetUsersOptions extends ProjectHandle {
+  resourceType?: 'organization' | 'project';
+  batchSize?: number;
+  organizationId?: string;
+  userId?: string;
+}
+/**
+ * @public
+ */
+interface UsersGroupState {
+  subscriptions: string[];
+  totalCount?: number;
+  nextCursor?: string | null;
+  lastLoadMoreRequest?: string;
+  users?: SanityUser[];
+  error?: unknown;
+}
+/**
+ * @public
+ */
+interface SanityUserResponse {
+  data: SanityUser[];
+  totalCount: number;
+  nextCursor: string | null;
+}
+/**
+ * @public
+ */
+interface UsersStoreState {
+  users: { [TUsersKey in string]?: UsersGroupState; };
+  error?: unknown;
+}
+/**
+ * @public
+ */
+interface ResolveUsersOptions extends GetUsersOptions {
+  signal?: AbortSignal;
+}
+/**
+ * @public
+ */
+interface GetUserOptions extends ProjectHandle {
+  userId: string;
+  resourceType?: 'organization' | 'project';
+  organizationId?: string;
+}
+/**
+ * @public
+ */
+interface ResolveUserOptions extends GetUserOptions {
+  signal?: AbortSignal;
+}
+/** @internal */
+declare const getUsersKey: (instance: SanityInstance, { resourceType, organizationId, batchSize, projectId, userId }?: GetUsersOptions) => string;
+/** @internal */
+declare const parseUsersKey: (key: string) => {
+  batchSize: number;
+  resourceType?: "organization" | "project";
+  projectId?: string;
+  organizationId?: string;
+  userId?: string;
+};
+/**
+ * Creates a GROQ search filter string (`[@] match text::query("...")`)
+ * from a raw search query string.
+ *
+ * It applies wildcard ('*') logic to the last eligible token and escapes
+ * double quotes within the search term.
+ *
+ * If the input query is empty or only whitespace, it returns an empty string.
+ *
+ * @param query - The raw input search string.
+ * @returns The GROQ search filter string, or an empty string.
+ * @internal
+ */
+declare function createGroqSearchFilter(query: string): string;
+export { getIsInDashboardState as $, transformProjectionToPreview as A, isDatasetSource as At, getClientErrorApiBody as B, QueryOptions as C, ReleasePerspective as Ct, resolveQuery as D, isCanvasResource as Dt, parseQueryKey as E, TokenSource as Et, ValuePending as F, AuthStoreState as G, getClientErrorApiType as H, ProjectionValuePending as I, LoggedOutAuthState as J, ErrorAuthState as K, ValidProjection as L, PreviewQueryResult as M, isMediaLibrarySource as Mt, PreviewStoreState as N, AuthConfig as Nt, Selector as O, isCanvasSource as Ot, PreviewValue as P, AuthProvider as Pt, getDashboardOrganizationId as Q, PREVIEW_PROJECTION as R, defineMutation as S, ReleaseHandle as St, getQueryState as T, StudioConfig as Tt, isProjectUserNotFoundClientError as U, getClientErrorApiDescription as V, AuthState as W, getAuthState as X, LoggingInAuthState as Y, getCurrentUserState as Z, FetcherDefinition as _, DocumentTypeHandle as _t, GetUsersOptions as a, StoreAction as at, MutationResult as b, PerspectiveHandle as bt, ResolveUsersOptions as c, isStudioConfig as ct, UserProfile as d, DatasetHandle as dt, getLoginUrlState as et, UsersGroupState as f, DatasetResource as ft, Fetcher as g, DocumentSource as gt, CacheWriter as h, DocumentResource as ht, GetUserOptions as i, BoundStoreAction as it, PreviewMedia as j, isMediaLibraryResource as jt, StateSource as k, isDatasetResource as kt, SanityUser as l, CanvasResource as lt, CacheTag as m, DocumentHandle as mt, getUsersKey as n, setAuthToken as nt, Membership as o, SanityInstance as ot, UsersStoreState as p, DatasetSource as pt, LoggedInAuthState as q, parseUsersKey as r, AuthStateType as rt, ResolveUserOptions as s, createSanityInstance as st, createGroqSearchFilter as t, getTokenState as tt, SanityUserResponse as u, CanvasSource as ut, FetcherSnapshot as v, MediaLibraryResource as vt, getQueryKey as w, SanityConfig as wt, defineFetcher as x, ProjectHandle as xt, MutationDefinition as y, MediaLibrarySource as yt, ApiErrorBody as z };
+//# sourceMappingURL=createGroqSearchFilter.d.ts.map