@sanity/sdk-react 0.0.0-alpha.11 → 0.0.0-alpha.13

package/dist/hooks.d.ts

@@ -12,10 +12,10 @@ import {FrameMessage} from '@sanity/sdk'
 import {JsonMatch} from '@sanity/sdk'
 import {JsonMatchPath} from '@sanity/sdk'
 import {Observable} from 'rxjs'
+import {PermissionsResult} from '@sanity/sdk'
 import {PreviewValue} from '@sanity/sdk'
 import {Requester} from 'get-it'
-import {SanityDocument as SanityDocument_2} from '@sanity/types'
-import {SanityDocumentLike} from '@sanity/types'
+import {SanityDocument} from '@sanity/types'
 import {SanityInstance} from '@sanity/sdk'
 import {WindowMessage} from '@sanity/sdk'
 
@@ -300,9 +300,18 @@ declare interface ClientConfig {
   /** @defaultValue true */
   useCdn?: boolean
   token?: string
-  /** @defaultValue 'raw' */
+  /**
+   * What perspective to use for the client. See {@link https://www.sanity.io/docs/perspectives|perspective documentation}
+   * @remarks
+   * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+   * @defaultValue 'published'
+   */
   perspective?: ClientPerspective
   apiHost?: string
+  /**
+     @remarks
+     * As of API version `v2025-02-19`, the default perspective has changed from `raw` to `published`. {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog}
+     */
   apiVersion?: string
   proxy?: string
   /**
@@ -353,11 +362,11 @@ declare interface ClientConfig {
 
 /** @public */
 declare type ClientPerspective =
-  | 'previewDrafts'
+  | DeprecatedPreviewDrafts
   | 'published'
   | 'drafts'
   | 'raw'
-  | ('published' | 'drafts' | ReleaseId)[]
+  | StackablePerspective[]
 
 /** @public */
 declare type ClientReturn<
@@ -507,7 +516,7 @@ declare type CreateAction = {
   ifExists: 'fail' | 'ignore'
 }
 
-/** @internal */
+/** @public */
 declare interface CurrentSanityUser {
   id: string
   name: string
@@ -518,10 +527,10 @@ declare interface CurrentSanityUser {
 
 export {CurrentUser}
 
-/** @internal */
+/** @public */
 declare type DatasetAclMode = 'public' | 'private' | 'custom'
 
-/** @internal */
+/** @public */
 declare type DatasetResponse = {
   datasetName: string
   aclMode: DatasetAclMode
@@ -569,7 +578,7 @@ declare class DatasetsClient {
   list(): Promise<DatasetsResponse>
 }
 
-/** @internal */
+/** @public */
 declare type DatasetsResponse = {
   name: string
   aclMode: DatasetAclMode
@@ -604,6 +613,11 @@ declare type DeleteAction = {
   purge?: boolean
 }
 
+/**
+ * @deprecated use 'drafts' instead
+ */
+declare type DeprecatedPreviewDrafts = 'previewDrafts'
+
 /**
  * Delete the draft version of a document.
  * It is an error if it does not exist. If the purge flag is set, the document history is also deleted.
@@ -636,10 +650,14 @@ declare type DisconnectEvent = {
   reason: string
 }
 
+export {DocumentHandle}
+
 /**
  * @public
+ * A live collection of {@link DocumentHandle}s, along with metadata about the collection and a function for loading more of them.
+ * @category Types
  */
-export declare interface DocumentCollection {
+export declare interface DocumentHandleCollection {
   /** Retrieve more documents matching the provided options */
   loadMore: () => void
   /** The retrieved document handles of the documents matching the provided options */
@@ -764,6 +782,7 @@ export declare interface FrameConnection<TFrameMessage extends FrameMessage> {
           >['data'],
         ]
   ) => void
+  status: Status
 }
 
 /** @public */
@@ -893,6 +912,16 @@ declare interface ListenOptions {
    * @defaultValue `false`
    */
   includePreviousRevision?: boolean
+  /**
+   * Whether to include events for drafts and versions. As of API Version >= v2025-02-19, only events
+   * for published documents will be included by default (see {@link https://www.sanity.io/changelog/e93a2d5a-9cee-4801-829e-8d3394bfed85|Changelog})
+   * If you need events from drafts and versions, set this to `true`.
+   * Note: Keep in mind that additional document variants may be introduced in the future, so it's
+   * recommended to respond to events in a way that's tolerant of potential future variants, e.g. by
+   * explicitly checking whether the event is for a draft or a version.
+   * @defaultValue `false`
+   */
+  includeAllVersions?: boolean
   /**
    * Whether events should be sent as soon as a transaction has been committed (`transaction`, default),
    * or only after they are available for queries (query). Note that this is on a best-effort basis,
@@ -987,6 +1016,16 @@ declare type Logger =
       Pick<typeof console, 'debug' | 'error' | 'groupCollapsed' | 'groupEnd' | 'log' | 'table'>
     >
 
+declare type Membership = {
+  addedAt?: string
+  resourceType: string
+  resourceId: string
+  roleNames: Array<string>
+  lastSeenAt?: string | null
+}
+
+declare type Memberships = Array<Membership>
+
 /**
  * @internal
  */
@@ -1064,12 +1103,12 @@ declare type MutationEvent_2<R extends Record<string, Any> = Record<string, Any>
    * The document as it looked after the mutation was performed. This is only included if
    * the listener was configured with `includeResult: true`.
    */
-  result?: SanityDocument<R>
+  result?: SanityDocument_2<R>
   /**
    * The document as it looked before the mutation was performed. This is only included if
    * the listener was configured with `includePreviousRevision: true`.
    */
-  previous?: SanityDocument<R> | null
+  previous?: SanityDocument_2<R> | null
   /**
    * The effects of the mutation, if the listener was configured with `effectFormat: 'mendoza'`.
    * Object with `apply` and `revert` arrays, see {@link https://github.com/sanity-io/mendoza}.
@@ -1256,7 +1295,7 @@ declare class ObservablePatch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Commit the patch, returning an observable that produces an array of the mutated documents
    *
@@ -1264,7 +1303,7 @@ declare class ObservablePatch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Commit the patch, returning an observable that produces a mutation result object
    *
@@ -1284,7 +1323,7 @@ declare class ObservablePatch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
 }
 
 /** @public */
@@ -1410,7 +1449,7 @@ declare class ObservableSanityClient {
     options?: {
       tag?: string
     },
-  ): Observable<SanityDocument<R> | undefined>
+  ): Observable<SanityDocument_2<R> | undefined>
   /**
    * Fetch multiple documents in one request.
    * Should be used sparingly - performing a query is usually a better option.
@@ -1425,7 +1464,7 @@ declare class ObservableSanityClient {
     options?: {
       tag?: string
     },
-  ): Observable<(SanityDocument<R> | null)[]>
+  ): Observable<(SanityDocument_2<R> | null)[]>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to the created document.
@@ -1436,7 +1475,7 @@ declare class ObservableSanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to an array containing the created document.
@@ -1447,7 +1486,7 @@ declare class ObservableSanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns an observable that resolves to a mutation result object containing the ID of the created document.
@@ -1480,7 +1519,7 @@ declare class ObservableSanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns an observable that resolves to the created document.
@@ -1491,7 +1530,7 @@ declare class ObservableSanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns an observable that resolves to an array containing the created document.
@@ -1502,7 +1541,7 @@ declare class ObservableSanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns an observable that resolves to a mutation result object containing the ID of the created document.
@@ -1535,7 +1574,7 @@ declare class ObservableSanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns an observable that resolves to the created document.
@@ -1546,7 +1585,7 @@ declare class ObservableSanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns an observable that resolves to an array containing the created document.
@@ -1557,7 +1596,7 @@ declare class ObservableSanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns an observable that resolves to a mutation result object containing the ID of the created document.
@@ -1590,7 +1629,7 @@ declare class ObservableSanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Deletes a document with the given document ID.
    * Returns an observable that resolves to the deleted document.
@@ -1601,7 +1640,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Deletes a document with the given document ID.
    * Returns an observable that resolves to an array containing the deleted document.
@@ -1612,7 +1651,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Deletes a document with the given document ID.
    * Returns an observable that resolves to a mutation result object containing the deleted document ID.
@@ -1639,7 +1678,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns an observable that resolves to first deleted document.
@@ -1650,7 +1689,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns an observable that resolves to an array containing the deleted documents.
@@ -1661,7 +1700,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns an observable that resolves to a mutation result object containing the ID of the first deleted document.
@@ -1694,7 +1733,7 @@ declare class ObservableSanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Perform mutation operations against the configured dataset
    * Returns an observable that resolves to the first mutated document.
@@ -1705,7 +1744,7 @@ declare class ObservableSanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | ObservablePatch | ObservableTransaction,
     options: FirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Perform mutation operations against the configured dataset.
    * Returns an observable that resolves to an array of the mutated documents.
@@ -1716,7 +1755,7 @@ declare class ObservableSanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | ObservablePatch | ObservableTransaction,
     options: AllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Perform mutation operations against the configured dataset
    * Returns an observable that resolves to a mutation result object containing the document ID of the first mutated document.
@@ -1749,7 +1788,7 @@ declare class ObservableSanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | ObservablePatch | ObservableTransaction,
     options?: BaseMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Create a new buildable patch of operations to perform
    *
@@ -1829,7 +1868,7 @@ declare class ObservableTransaction extends BaseTransaction {
    */
   commit<R extends Record<string, Any>>(
     options: TransactionFirstDocumentMutationOptions,
-  ): Observable<SanityDocument<R>>
+  ): Observable<SanityDocument_2<R>>
   /**
    * Commit the transaction, returning an observable that produces an array of the mutated documents
    *
@@ -1837,7 +1876,7 @@ declare class ObservableTransaction extends BaseTransaction {
    */
   commit<R extends Record<string, Any>>(
     options: TransactionAllDocumentsMutationOptions,
-  ): Observable<SanityDocument<R>[]>
+  ): Observable<SanityDocument_2<R>[]>
   /**
    * Commit the transaction, returning an observable that produces a mutation result object
    *
@@ -1911,7 +1950,7 @@ declare class Patch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Commit the patch, returning a promise that resolves to an array of the mutated documents
    *
@@ -1919,7 +1958,7 @@ declare class Patch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Commit the patch, returning a promise that resolves to a mutation result object
    *
@@ -1939,7 +1978,7 @@ declare class Patch extends BasePatch {
    */
   commit<R extends Record<string, Any> = Record<string, Any>>(
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
 }
 
 /** @public */
@@ -2124,9 +2163,6 @@ declare type ReconnectEvent = {
   type: 'reconnect'
 }
 
-/** @public */
-declare type ReleaseId = `r${string}`
-
 /**
  * Replaces an existing draft document.
  * At least one of the draft or published versions of the document must exist.
@@ -2160,6 +2196,13 @@ declare interface RequestOptions {
 /** @alpha */
 declare type ResolveStudioUrl = (sourceDocument: ContentSourceMapDocuments[number]) => StudioUrl
 
+/**
+ * Resources are entities that can be managed and accessed through the
+ * Access API.
+ *
+ */
+declare type ResourceType = 'organization' | 'project'
+
 /** @public */
 declare interface ResponseEvent<T = unknown> {
   type: 'response'
@@ -2191,7 +2234,7 @@ declare interface ResponseQueryOptions extends RequestOptions {
 }
 
 /** @internal */
-declare interface SanityAssetDocument extends SanityDocument {
+declare interface SanityAssetDocument extends SanityDocument_2 {
   url: string
   path: string
   size: number
@@ -2308,7 +2351,7 @@ declare class SanityClient {
       signal?: AbortSignal
       tag?: string
     },
-  ): Promise<SanityDocument<R> | undefined>
+  ): Promise<SanityDocument_2<R> | undefined>
   /**
    * Fetch multiple documents in one request.
    * Should be used sparingly - performing a query is usually a better option.
@@ -2324,7 +2367,7 @@ declare class SanityClient {
       signal?: AbortSignal
       tag?: string
     },
-  ): Promise<(SanityDocument<R> | null)[]>
+  ): Promise<(SanityDocument_2<R> | null)[]>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to the created document.
@@ -2335,7 +2378,7 @@ declare class SanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to an array containing the created document.
@@ -2346,7 +2389,7 @@ declare class SanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Create a document. Requires a `_type` property. If no `_id` is provided, it will be generated by the database.
    * Returns a promise that resolves to a mutation result object containing the ID of the created document.
@@ -2379,7 +2422,7 @@ declare class SanityClient {
   create<R extends Record<string, Any> = Record<string, Any>>(
     document: SanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns a promise that resolves to the created document.
@@ -2390,7 +2433,7 @@ declare class SanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns a promise that resolves to an array containing the created document.
@@ -2401,7 +2444,7 @@ declare class SanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Create a document if no document with the same ID already exists.
    * Returns a promise that resolves to a mutation result object containing the ID of the created document.
@@ -2434,7 +2477,7 @@ declare class SanityClient {
   createIfNotExists<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns a promise that resolves to the created document.
@@ -2445,7 +2488,7 @@ declare class SanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns a promise that resolves to an array containing the created document.
@@ -2456,7 +2499,7 @@ declare class SanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Create a document if it does not exist, or replace a document with the same document ID
    * Returns a promise that resolves to a mutation result object containing the ID of the created document.
@@ -2489,7 +2532,7 @@ declare class SanityClient {
   createOrReplace<R extends Record<string, Any> = Record<string, Any>>(
     document: IdentifiedSanityDocumentStub<R>,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Deletes a document with the given document ID.
    * Returns a promise that resolves to the deleted document.
@@ -2500,7 +2543,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Deletes a document with the given document ID.
    * Returns a promise that resolves to an array containing the deleted document.
@@ -2511,7 +2554,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Deletes a document with the given document ID.
    * Returns a promise that resolves to a mutation result object containing the deleted document ID.
@@ -2538,7 +2581,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     id: string,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns a promise that resolves to first deleted document.
@@ -2549,7 +2592,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns a promise that resolves to an array containing the deleted documents.
@@ -2560,7 +2603,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Deletes one or more documents matching the given query or document ID.
    * Returns a promise that resolves to a mutation result object containing the ID of the first deleted document.
@@ -2593,7 +2636,7 @@ declare class SanityClient {
   delete<R extends Record<string, Any> = Record<string, Any>>(
     selection: MutationSelection,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Perform mutation operations against the configured dataset
    * Returns a promise that resolves to the first mutated document.
@@ -2604,7 +2647,7 @@ declare class SanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | Patch | Transaction,
     options: FirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Perform mutation operations against the configured dataset.
    * Returns a promise that resolves to an array of the mutated documents.
@@ -2615,7 +2658,7 @@ declare class SanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | Patch | Transaction,
     options: AllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Perform mutation operations against the configured dataset
    * Returns a promise that resolves to a mutation result object containing the document ID of the first mutated document.
@@ -2648,7 +2691,7 @@ declare class SanityClient {
   mutate<R extends Record<string, Any> = Record<string, Any>>(
     operations: Mutation<R>[] | Patch | Transaction,
     options?: BaseMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Create a new buildable patch of operations to perform
    *
@@ -2727,8 +2770,10 @@ declare class SanityClient {
   getDataUrl(operation: string, path?: string): string
 }
 
+export {SanityDocument}
+
 /** @internal */
-declare type SanityDocument<T extends Record<string, Any> = Record<string, Any>> = {
+declare type SanityDocument_2<T extends Record<string, Any> = Record<string, Any>> = {
   [P in keyof T]: T[P]
 } & {
   _id: string
@@ -2792,7 +2837,7 @@ declare interface SanityImagePalette {
   title: string
 }
 
-/** @internal */
+/** @public */
 declare interface SanityProject {
   id: string
   displayName: string
@@ -2820,7 +2865,7 @@ declare interface SanityProject {
   }
 }
 
-/** @internal */
+/** @public */
 declare interface SanityProjectMember {
   id: string
   role: string
@@ -2831,7 +2876,7 @@ declare interface SanityProjectMember {
 /** @public */
 declare interface SanityQueries {}
 
-/** @internal */
+/** @public */
 declare interface SanityUser {
   id: string
   projectId: string
@@ -2860,6 +2905,14 @@ declare interface SingleMutationResult {
   }[]
 }
 
+/** @public */
+declare type StackablePerspective = ('published' | 'drafts' | string) & {}
+
+/**
+ * @public
+ */
+declare type Status = 'idle' | 'handshaking' | 'connected' | 'disconnected'
+
 /** @public */
 declare interface StegaConfig {
   /**
@@ -2924,7 +2977,7 @@ declare class Transaction extends BaseTransaction {
    */
   commit<R extends Record<string, Any>>(
     options: TransactionFirstDocumentMutationOptions,
-  ): Promise<SanityDocument<R>>
+  ): Promise<SanityDocument_2<R>>
   /**
    * Commit the transaction, returning a promise that resolves to an array of the mutated documents
    *
@@ -2932,7 +2985,7 @@ declare class Transaction extends BaseTransaction {
    */
   commit<R extends Record<string, Any>>(
     options: TransactionAllDocumentsMutationOptions,
-  ): Promise<SanityDocument<R>[]>
+  ): Promise<SanityDocument_2<R>[]>
   /**
    * Commit the transaction, returning a promise that resolves to a mutation result object
    *
@@ -3106,8 +3159,51 @@ declare interface UploadClientConfig {
   }
 }
 
-/** @beta */
-export declare function useApplyActions(): <TDocument extends SanityDocument_2>(
+/**
+ *
+ * @beta
+ *
+ * Provides a callback for applying one or more actions to a document.
+ *
+ * @category Documents
+ * @returns A function that takes one more more {@link DocumentAction}s and returns a promise that resolves to an {@link ActionsResult}.
+ * @example Publish or unpublish a document
+ * ```
+ * import { publishDocument, unpublishDocument } from '@sanity/sdk'
+ * import { useApplyActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyActions()
+ * const myDocument = { _id: 'my-document-id', _type: 'my-document-type' }
+ *
+ * return (
+ *   <button onClick={() => apply(publishDocument(myDocument))}>Publish</button>
+ *   <button onClick={() => apply(unpublishDocument(myDocument))}>Unpublish</button>
+ * )
+ * ```
+ *
+ * @example Create and publish a new document
+ * ```
+ * import { createDocument, publishDocument } from '@sanity/sdk'
+ * import { useApplyActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyActions()
+ *
+ * const handleCreateAndPublish = () => {
+ *   const handle = { _id: window.crypto.randomUUID(), _type: 'my-document-type' }
+ *   apply([
+ *     createDocument(handle),
+ *     publishDocument(handle),
+ *   ])
+ * }
+ *
+ * return (
+ *   <button onClick={handleCreateAndPublish}>
+ *     I’m feeling lucky
+ *   </button>
+ * )
+ * ```
+ */
+export declare function useApplyActions(): <TDocument extends SanityDocument>(
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
   options?: ApplyActionsOptions,
 ) => Promise<ActionsResult<TDocument>>
@@ -3132,8 +3228,6 @@ export declare function useApplyActions(): <TDocument extends SanityDocument_2>(
  *   return <div>Current auth state: {authState}</div>
  * }
  * ```
- *
- * @public
  */
 export declare const useAuthState: () => AuthState
 
@@ -3152,6 +3246,7 @@ export declare const useAuthToken: () => string | null
  * The hook uses `useSyncExternalStore` to safely subscribe to changes
  * and ensure consistency between server and client rendering.
  *
+ * @category Platform
  * @returns A Sanity client
  *
  * @example
@@ -3176,9 +3271,10 @@ export declare function useClient(options: ClientOptions): SanityClient
  *
  * @public
  *
- * The `useCurrentUser` hook returns the currently authenticated user’s profile information (their name, email, roles, etc).
+ * Provides the currently authenticated user’s profile information (their name, email, roles, etc).
  * If no users are currently logged in, the hook returns null.
  *
+ * @category Authentication
  * @returns The current user data, or `null` if not authenticated
  *
  * @example Rendering a basic user profile
@@ -3195,30 +3291,115 @@ export declare function useClient(options: ClientOptions): SanityClient
  */
 export declare const useCurrentUser: () => CurrentUser | null
 
-/** @beta */
+/**
+ * @beta
+ *
+ * ## useDocument(doc, path)
+ * Read and subscribe to nested values in a document
+ * @category Documents
+ * @param doc - The document to read state from
+ * @param path - The path to the nested value to read from
+ * @returns The value at the specified path
+ * @example
+ * ```tsx
+ * import {type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ *
+ * function OrderLink({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const title = useDocument(documentHandle, 'title')
+ *   const id = useDocument(documentHandle, '_id')
+ *
+ *   return (
+ *     <a href=`/order/${id}`>Order {title} today!</a>
+ *   )
+ * }
+ * ```
+ *
+ */
 export declare function useDocument<
-  TDocument extends SanityDocument_2,
+  TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
 >(doc: string | DocumentHandle<TDocument>, path: TPath): JsonMatch<TDocument, TPath> | undefined
 
-/** @beta */
-export declare function useDocument<TDocument extends SanityDocument_2>(
+/**
+ * @beta
+ * ## useDocument(doc)
+ * Read and subscribe to an entire document
+ * @param doc - The document to read state from
+ * @returns The document state as an object
+ * @example
+ * ```tsx
+ * import {type SanityDocument, type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ *
+ * interface Book extends SanityDocument {
+ *   title: string
+ *   author: string
+ *   summary: string
+ * }
+ *
+ * function DocumentView({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const book = useDocument<Book>(documentHandle)
+ *
+ *   return (
+ *     <article>
+ *       <h1>{book?.title}</h1>
+ *       <address>By {book?.author}</address>
+ *
+ *       <h2>Summary</h2>
+ *       {book?.summary}
+ *
+ *       <h2>Order</h2>
+ *       <a href=`/order/${book._id}`>Order {book?.title} today!</a>
+ *     </article>
+ *   )
+ * }
+ * ```
+ *
+ */
+export declare function useDocument<TDocument extends SanityDocument>(
   doc: string | DocumentHandle<TDocument>,
 ): TDocument | null
 
-/** @beta */
+/**
+ *
+ * @beta
+ *
+ * Subscribes an event handler to events in your application’s document store, such as document
+ * creation, deletion, and updates.
+ *
+ * @category Documents
+ * @param handler - The event handler to register.
+ * @example
+ * ```
+ * import {useDocumentEvent} from '@sanity/sdk-react'
+ * import {type DocumentEvent} from '@sanity/sdk'
+ *
+ * useDocumentEvent((event) => {
+ *   if (event.type === DocumentEvent.DocumentDeletedEvent) {
+ *     alert(`Document with ID ${event.documentId} deleted!`)
+ *   } else {
+ *     console.log(event)
+ *   }
+ * })
+ * ```
+ */
 export declare function useDocumentEvent(handler: (documentEvent: DocumentEvent) => void): void
 
 /**
  * @public
  *
- * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.
- * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.
+ * Retrieves and provides access to a live collection of {@link DocumentHandle}s, with an optional filter and sort applied.
+ * The returned document handles are canonical — that is, they refer to the document in its current state, whether draft, published, or within a release or perspective.
+ * Because the returned document handle collection is live, the results will update in real time until the component invoking the hook is unmounted.
+ *
+ * @remarks
+ * {@link DocumentHandle}s are used by many other hooks (such as {@link usePreview}, {@link useDocument}, and {@link useEditDocument})
+ * to work with documents in various ways without the entire document needing to be fetched upfront.
  *
+ * @category Documents
  * @param options - Options for narrowing and sorting the document collection
- * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.
+ * @returns The collection of document handles matching the provided options (if any), as well as properties describing the collection and a function to load more.
  *
- * @example Retrieving all documents of type 'movie'
+ * @example Retrieving document handles for all documents of type 'movie'
  * ```
  * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
  *
@@ -3235,7 +3416,7 @@ export declare function useDocumentEvent(handler: (documentEvent: DocumentEvent)
  * )
  * ```
  *
- * @example Retrieving all movies released since 1980, sorted by director’s last name
+ * @example Retrieving document handles for all movies released since 1980, sorted by director’s last name
  * ```
  * const { results } = useDocuments({
  *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
@@ -3260,24 +3441,150 @@ export declare function useDocumentEvent(handler: (documentEvent: DocumentEvent)
  * )
  * ```
  */
-export declare function useDocuments(options?: DocumentListOptions): DocumentCollection
+export declare function useDocuments(options?: DocumentListOptions): DocumentHandleCollection
 
-/** @beta */
-export declare const useDocumentSyncStatus: (
-  doc: string | DocumentHandle<SanityDocumentLike>,
-) => boolean | undefined
+declare type UseDocumentSyncStatus = {
+  /**
+   * Exposes the document’s sync status between local and remote document states.
+   *
+   * @category Documents
+   * @param doc - The document handle to get sync status for
+   * @returns `true` if local changes are synced with remote, `false` if the changes are not synced, and `undefined` if the document is not found
+   * @example Disable a Save button when there are no changes to sync
+   * ```
+   * const myDocumentHandle = { _id: 'documentId', _type: 'documentType' }
+   * const documentSynced = useDocumentSyncStatus(myDocumentHandle)
+   *
+   * return (
+   *   <button disabled={documentSynced}>
+   *     Save Changes
+   *   </button>
+   * )
+   * ```
+   */
+  (doc: DocumentHandle): boolean | undefined
+}
 
 /** @beta */
+export declare const useDocumentSyncStatus: UseDocumentSyncStatus
+
+/**
+ *
+ * @beta
+ *
+ * ## useEditDocument(doc, path)
+ * Edit a nested value within a document
+ *
+ * @category Documents
+ * @param doc - The document to be edited; either as a document handle or the document’s ID a string
+ * @param path - The path to the nested value to be edited
+ * @returns A function to update the nested value. Accepts either a new value, or an updater function that exposes the previous value and returns a new value.
+ * @example Update a document’s name by providing the new value directly
+ * ```
+ * const handle = { _id: 'documentId', _type: 'documentType' }
+ * const name = useDocument(handle, 'name')
+ * const editName = useEditDocument(handle, 'name')
+ *
+ * function handleNameChange(event: React.ChangeEvent<HTMLInputElement>) {
+ *   editName(event.target.value)
+ * }
+ *
+ * return (
+ *   <input type='text' value={name} onChange={handleNameChange} />
+ * )
+ * ```
+ *
+ * @example Update a count on a document by providing an updater function
+ * ```
+ * const handle = { _id: 'documentId', _type: 'documentType' }
+ * const count = useDocument(handle, 'count')
+ * const editCount = useEditDocument(handle, 'count')
+ *
+ * function incrementCount() {
+ *   editCount(previousCount => previousCount + 1)
+ * }
+ *
+ * return (
+ *   <>
+ *     <button onClick={incrementCount}>
+ *       Increment
+ *     </button>
+ *     Current count: {count}
+ *   </>
+ * )
+ * ```
+ */
 export declare function useEditDocument<
-  TDocument extends SanityDocument_2,
+  TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
 >(
   doc: string | DocumentHandle<TDocument>,
   path: TPath,
 ): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
 
-/** @beta */
-export declare function useEditDocument<TDocument extends SanityDocument_2>(
+/**
+ *
+ * @beta
+ *
+ * ## useEditDocument(doc)
+ * Edit an entire document
+ * @param doc - The document to be edited; either as a document handle or the document’s ID a string
+ * @returns A function to update the document state. Accepts either a new document state, or an updater function that exposes the previous document state and returns the new document state.
+ * @example
+ * ```
+ * const myDocumentHandle = { _id: 'documentId', _type: 'documentType' }
+ *
+ * const myDocument = useDocument(myDocumentHandle)
+ * const { title, price } = myDocument
+ *
+ * const editMyDocument = useEditDocument(myDocumentHandle)
+ *
+ * function handleFieldChange(e: React.ChangeEvent<HTMLInputElement>) {
+ *   const {name, value} = e.currentTarget
+ *   // Use an updater function to update the document state based on the previous state
+ *   editMyDocument(previousDocument => ({
+ *     ...previousDocument,
+ *     [name]: value
+ *   }))
+ * }
+ *
+ * function handleSaleChange(e: React.ChangeEvent<HTMLInputElement>) {
+ *   const { checked } = e.currentTarget
+ *   if (checked) {
+ *     // Use an updater function to add a new salePrice field;
+ *     // set it at a 20% discount off the normal price
+ *     editMyDocument(previousDocument => ({
+ *       ...previousDocument,
+ *       salePrice: previousDocument.price * 0.8,
+ *     }))
+ *   } else {
+ *     // Get the document state without the salePrice field
+ *     const { salePrice, ...rest } = myDocument
+ *     // Update the document state to remove the salePrice field
+ *     editMyDocument(rest)
+ *   }
+ * }
+ *
+ * return (
+ *   <>
+ *     <form onSubmit={e => e.preventDefault()}>
+ *       <input name='title' type='text' value={title} onChange={handleFieldChange} />
+ *       <input name='price' type='number' value={price} onChange={handleFieldChange} />
+ *       <input
+ *         name='salePrice'
+ *         type='checkbox'
+ *         checked={Object(myDocument).hasOwnProperty('salePrice')}
+ *         onChange={handleSaleChange}
+ *       />
+ *     </form>
+ *     <pre><code>
+ *       {JSON.stringify(myDocument, null, 2)}
+ *     </code></pre>
+ *   </>
+ * )
+ * ```
+ */
+export declare function useEditDocument<TDocument extends SanityDocument>(
   doc: string | DocumentHandle<TDocument>,
 ): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
 
@@ -3296,7 +3603,17 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
   name: string
   connectTo: string
   targetOrigin: string
-  onMessage?: Record<string, MessageHandler<TWindowMessage>>
+  onMessage?: {
+    [K in TWindowMessage['type']]: (
+      data: Extract<
+        TWindowMessage,
+        {
+          type: K
+        }
+      >['data'],
+    ) => void
+  }
+  heartbeat?: boolean
 }
 
 /**
@@ -3391,14 +3708,20 @@ export declare function useLoginUrls(): AuthProvider[]
  */
 export declare const useLogOut: () => () => Promise<void>
 
+/** @beta */
+export declare function usePermissions(
+  actions: DocumentAction | DocumentAction[],
+): PermissionsResult
+
 /**
- * @alpha
+ * @beta
  *
- * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,
+ * Returns the preview values of a document (specified via a `DocumentHandle`),
  * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
+ * @category Documents
  * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
  * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
  *
@@ -3440,7 +3763,8 @@ export declare function usePreview({
 }: UsePreviewOptions): UsePreviewResults
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export declare interface UsePreviewOptions {
   document: DocumentHandle
@@ -3448,7 +3772,8 @@ export declare interface UsePreviewOptions {
 }
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export declare interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
@@ -3457,6 +3782,28 @@ export declare interface UsePreviewResults {
   isPending: boolean
 }
 
+declare type User = {
+  sanityUserId: string
+  profile: UserProfile
+  memberships: Memberships
+}
+
+declare type 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 */
 declare class UsersClient {
   #private
@@ -3472,7 +3819,7 @@ declare class UsersClient {
 /**
  * `useSanityInstance` returns the current Sanity instance from the application context.
  * This must be called from within a `SanityProvider` component.
- * @public
+ * @internal
  * @returns The current Sanity instance
  * @example
  * ```tsx
@@ -3481,6 +3828,43 @@ declare class UsersClient {
  */
 export declare const useSanityInstance: () => SanityInstance
 
+/** @public */
+export declare function useUsers(params: UseUsersParams): UseUsersResult
+
+/**
+ * @public
+ */
+declare interface UseUsersParams {
+  /**
+   * The type of resource to fetch users for.
+   */
+  resourceType: ResourceType
+  /**
+   * The ID of the resource to fetch users for.
+   */
+  resourceId: string
+  /**
+   * The limit of users to fetch.
+   */
+  limit?: number
+}
+
+/** @public */
+export declare interface UseUsersResult {
+  /**
+   * The users fetched.
+   */
+  users: User[]
+  /**
+   * Whether there are more users to fetch.
+   */
+  hasMore: boolean
+  /**
+   * Load more users.
+   */
+  loadMore: () => void
+}
+
 /**
  * @internal
  */
@@ -3522,6 +3906,7 @@ export declare interface WindowConnection<TMessage extends WindowMessage> {
       }
     >['data'],
   ) => void
+  status: Status
 }
 
 /**