@sanity/sdk-react 2.18.0 → 3.0.0-rc.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { AccessResourceType } from "@sanity/sdk";
 import { ActionsResult } from "@sanity/sdk";
 import { AgentGenerateOptions } from "@sanity/sdk";
 import { AgentPatchOptions } from "@sanity/sdk";
@@ -6,13 +7,22 @@ import { AgentPromptOptions } from "@sanity/sdk";
 import { AgentPromptResult } from "@sanity/sdk";
 import { AgentTransformOptions } from "@sanity/sdk";
 import { AgentTranslateOptions } from "@sanity/sdk";
+import { Application } from "@sanity/sdk";
+import { ApplicationBase } from "@sanity/sdk";
+import { ApplicationInclude } from "@sanity/sdk";
+import { ApplicationsOptions } from "@sanity/sdk";
+import { ApplicationsResponse } from "@sanity/sdk";
 import { AuthState } from "@sanity/sdk";
 import { CanvasResource } from "@sanity/message-protocol";
 import { ClientOptions } from "@sanity/sdk";
 import { Context } from "react";
+import { CreateUserApplicationInput } from "@sanity/sdk";
 import { CurrentUser } from "@sanity/sdk";
 import { DatasetHandle } from "@sanity/sdk";
 import { DatasetsResponse } from "@sanity/client";
+import { DeleteApplicationInput } from "@sanity/sdk";
+import { DeletedResult } from "@sanity/sdk";
+import { DeleteUserApplicationInput } from "@sanity/sdk";
 import { DocumentAction } from "@sanity/sdk";
 import { DocumentEvent } from "@sanity/sdk";
 import { DocumentHandle as DocumentHandle_2 } from "@sanity/sdk";
@@ -25,6 +35,10 @@ import { FavoriteStatusResponse } from "@sanity/sdk";
 import { FrameMessage } from "@sanity/sdk";
 import { GetUserOptions } from "@sanity/sdk";
 import { GetUsersOptions } from "@sanity/sdk";
+import { Installation } from "@sanity/sdk";
+import { InstallationInclude } from "@sanity/sdk";
+import { InstallationsOptions } from "@sanity/sdk";
+import { InstallationsResponse } from "@sanity/sdk";
 import { JsonMatch } from "@sanity/sdk";
 import { MediaResource } from "@sanity/message-protocol";
 import { Organization } from "@sanity/sdk";
@@ -56,6 +70,10 @@ import { SanityUser } from "@sanity/sdk";
 import { SortOrderingItem } from "@sanity/types";
 import { StudioResource } from "@sanity/message-protocol";
 import { TokenSource } from "@sanity/sdk";
+import { UpdateApplicationInput } from "@sanity/sdk";
+import { UpdateUserApplicationInput } from "@sanity/sdk";
+import { UserApplication } from "@sanity/sdk";
+import { UserApplicationsOptions } from "@sanity/sdk";
 import { UserPresence } from "@sanity/sdk";
 import { WindowMessage } from "@sanity/sdk";
 
@@ -153,10 +171,7 @@ export declare interface AuthBoundaryProps {
  * @public
  */
 export declare type ComlinkStatus =
-  | "idle"
-  | "handshaking"
-  | "connected"
-  | "disconnected";
+  "idle" | "handshaking" | "connected" | "disconnected";
 
 /**
  * This provider is used to provide the Comlink token refresh feature.
@@ -191,14 +206,6 @@ declare interface DashboardResource {
 
 export { DatasetsResponse };
 
-/**
- * Return type for the useDispatchIntent hook
- * @beta
- */
-declare interface DispatchIntent {
-  dispatchIntent: () => void;
-}
-
 /**
  * React SDK document handle. Adds `resourceName` to the core `DocumentHandle`.
  *
@@ -301,6 +308,23 @@ export declare interface DocumentTypeHandle<
   resourceName?: string;
 }
 
+/**
+ * The value returned by a fetcher-backed hook. The hook suspends until the
+ * first fetch succeeds, so `data` is always present once your component renders.
+ *
+ * @public
+ */
+export declare interface FetcherHookResult<TData> {
+  /** The resolved data. Guaranteed present — the hook suspends until the first fetch succeeds. */
+  data: TData;
+  /** A fetch for this entry is in flight (background revalidation or a `refetch()`). */
+  isFetching: boolean;
+  /** The most recent background-fetch failure while data still renders; cleared by the next success. */
+  error: unknown;
+  /** Imperatively refetch, bypassing staleness. Resolves with the refreshed data. */
+  refetch: () => Promise<TData>;
+}
+
 /**
  * @internal
  */
@@ -327,11 +351,7 @@ export declare interface FrameConnection<TFrameMessage extends FrameMessage> {
 }
 
 declare type IgnoredKey =
-  | "_id"
-  | "_type"
-  | "_rev"
-  | "_createdAt"
-  | "_updatedAt";
+  "_id" | "_type" | "_rev" | "_createdAt" | "_updatedAt";
 
 /**
  * @alpha
@@ -356,6 +376,31 @@ export declare type MessageHandler<TWindowMessage extends WindowMessage> = (
   event: TWindowMessage["data"],
 ) => TWindowMessage["response"] | Promise<TWindowMessage["response"]>;
 
+/**
+ * The value returned by a mutation-backed hook. The write-side counterpart to
+ * {@link FetcherHookResult}: local `{mutate, isPending, error, data, reset}`
+ * state around a core mutation action.
+ *
+ * @public
+ */
+export declare interface MutationHookResult<TInput, TResult> {
+  /**
+   * Runs the mutation. Resolves with the server response; rejects on failure
+   * (the failure is also captured in {@link MutationHookResult.error}, so a
+   * fire-and-forget caller should read `error` and an `await`ing caller should
+   * `try`/`catch`).
+   */
+  mutate: (input: TInput) => Promise<TResult>;
+  /** A mutation is currently in flight. */
+  isPending: boolean;
+  /** The most recent failure; cleared by the next `mutate` or `reset`. */
+  error: unknown;
+  /** The last successful server response, or `undefined` before the first success. */
+  data: TResult | undefined;
+  /** Clears state back to idle and abandons any in-flight result. */
+  reset: () => void;
+}
+
 /** In-flight CLI PR is using named sources since it's aspirational.
  *  We can transform the shape in this function until it's finalized.
  */
@@ -1454,6 +1499,44 @@ export declare function useAllReleases(
   options?: WithResourceNameSupport<SanityConfig> | undefined,
 ): ReleaseDocument[];
 
+/**
+ * Returns a single application by id.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param applicationId - The application id.
+ * @param options - Optional `include` list to expand related resources.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useApplication: <
+  Include extends ApplicationInclude = never,
+>(
+  applicationId: string,
+  options?: {
+    include?: Include[];
+  },
+) => FetcherHookResult<Application<Include>>;
+
+/**
+ * Returns the applications matching the given options.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data.data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param options - Filter and include options for the applications list.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useApplications: <
+  Include extends ApplicationInclude = never,
+>(
+  options: ApplicationsOptions<Include>,
+) => FetcherHookResult<ApplicationsResponse<Include>>;
+
 /**
  * @public
  */
@@ -1766,6 +1849,25 @@ export declare const useAuthState: () => AuthState;
  */
 export declare const useAuthToken: () => string | null;
 
+/**
+ * Checks whether the current user holds the given permissions on a resource.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * `data` maps each requested permission to whether the user has it — keyed by
+ * exactly the permission strings you passed.
+ *
+ * @public
+ * @param resourceType - The type of resource (e.g. `'project'`, `'organization'`).
+ * @param resourceId - The resource id.
+ * @param permissions - The permission names to check.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useCheckPermissions: <Permission extends string>(
+  resourceType: AccessResourceType,
+  resourceId: string,
+  permissions: Permission[],
+) => FetcherHookResult<Record<Permission, boolean>>;
+
 /**
  * A React hook that provides a client that subscribes to changes in your application,
  *
@@ -1836,6 +1938,17 @@ export declare function useCreateDocument<
   overrides?: CreateDocumentOverrides,
 ) => Promise<DocumentHandle>;
 
+/**
+ * Creates a user application.
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
+ */
+export declare const useCreateUserApplication: () => MutationHookResult<
+  CreateUserApplicationInput,
+  UserApplication
+>;
+
 declare type UseCurrentUser = {
   /**
    * @public
@@ -1975,70 +2088,26 @@ declare type UseDatasets = {
 export declare const useDatasets: UseDatasets;
 
 /**
- * @beta
+ * Soft-deletes an application.
  *
- * A hook for dispatching intent messages to the Dashboard with a document handle.
- * This allows applications to signal their intent to pass the referenced document to other applications that have registered the ability to perform specific actions on that document.
- *
- * @param params - Object containing:
- *   - `action` - Action to perform (currently only 'edit' is supported). Will prompt a picker if multiple handlers are available.
- *   - `intentId` - Specific ID of the intent to dispatch. Either `action` or `intentId` is required.
- *   - `documentHandle` - The document handle containing document ID, type, and either:
- *     - `projectId` and `dataset` for traditional dataset resources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
- *     - `resource` for media library, canvas, or dataset resources, like `{documentId: '123', documentType: 'sanity.asset', resource: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', resource: canvasSource('canvas123')}`
- *   - `paremeters` - Optional parameters to include in the dispatch; will be passed to the resolved intent handler
- * @returns An object containing:
- * - `dispatchIntent` - Function to dispatch the intent message
- *
- * @example
- * ```tsx
- * import {useDispatchIntent} from '@sanity/sdk-react'
- * import {Button} from '@sanity/ui'
- * import {Suspense} from 'react'
- *
- * function DispatchIntentButton({documentId, documentType, projectId, dataset}) {
- *   const {dispatchIntent} = useDispatchIntent({
- *     action: 'edit',
- *     documentHandle: {documentId, documentType, projectId, dataset},
- *   })
- *
- *   return (
- *     <Button
- *       onClick={() => dispatchIntent()}
- *       text="Dispatch Intent"
- *     />
- *   )
- * }
- *
- * // Wrap the component with Suspense since the hook may suspend
- * function MyDocumentAction({documentId, documentType, projectId, dataset}) {
- *   return (
- *     <Suspense fallback={<Button text="Loading..." disabled />}>
- *       <DispatchIntentButton
- *         documentId={documentId}
- *         documentType={documentType}
- *         projectId={projectId}
- *         dataset={dataset}
- *       />
- *     </Suspense>
- *   )
- * }
- * ```
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
  */
-export declare function useDispatchIntent(
-  params: UseDispatchIntentParams,
-): DispatchIntent;
+export declare const useDeleteApplication: () => MutationHookResult<
+  DeleteApplicationInput,
+  DeletedResult
+>;
 
 /**
- * Parameters for the useDispatchIntent hook
- * @beta
+ * Deletes a user application.
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
  */
-declare interface UseDispatchIntentParams {
-  action?: "edit";
-  intentId?: string;
-  documentHandle: DocumentHandle;
-  parameters?: Record<string, unknown>;
-}
+export declare const useDeleteUserApplication: () => MutationHookResult<
+  DeleteUserApplicationInput,
+  DeletedResult
+>;
 
 declare interface UseDocument {
   /** @internal */
@@ -2996,6 +3065,44 @@ export declare const useHandleAuthCallback: () => (
   locationHref?: string | undefined,
 ) => Promise<string | false>;
 
+/**
+ * Returns a single installation by id.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param installationId - The installation id.
+ * @param options - Optional `include` list to expand related resources.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useInstallation: <
+  Include extends InstallationInclude = never,
+>(
+  installationId: string,
+  options?: {
+    include?: Include[];
+  },
+) => FetcherHookResult<Installation<Include>>;
+
+/**
+ * Returns the installations matching the given options.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ * The `include` tokens you pass shape `data.data`: each requested token adds its
+ * field, and omitted ones are absent from the type.
+ *
+ * @public
+ * @param options - Filter and include options for the installations list.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useInstallations: <
+  Include extends InstallationInclude = never,
+>(
+  options: InstallationsOptions<Include>,
+) => FetcherHookResult<InstallationsResponse<Include>>;
+
 /**
  * @internal
  */
@@ -3066,9 +3173,7 @@ export declare function useManageFavorite({
 declare interface UseManageFavoriteProps extends DocumentHandle_2 {
   resourceId?: string;
   resourceType:
-    | StudioResource["type"]
-    | MediaResource["type"]
-    | CanvasResource["type"];
+    StudioResource["type"] | MediaResource["type"] | CanvasResource["type"];
   /**
    * The name of the schema collection this document belongs to.
    * Typically is the name of the workspace when used in the context of a studio.
@@ -3130,20 +3235,21 @@ export declare function useNavigateToStudioDocument(
  *
  * @category Organizations
  * @param options - Configuration options
- * @returns The metadata for the organisation. `members` is included only when
- *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @returns A {@link FetcherHookResult} whose `data` is the metadata for the
+ *   organisation. `members` is included only when `includeMembers: true`;
+ *   `features` is included only when `includeFeatures: true`.
  * @example
  * ```tsx
  * function OrganizationName({organizationId}: {organizationId: string}) {
- *   const organization = useOrganization({organizationId})
+ *   const {data: organization} = useOrganization({organizationId})
  *
  *   return <h1>{organization.name}</h1>
  * }
  * ```
  * @example
  * ```tsx
- * const organizationWithMembers = useOrganization({organizationId, includeMembers: true})
- * const organizationWithFeatures = useOrganization({organizationId, includeFeatures: true})
+ * const {data: organizationWithMembers} = useOrganization({organizationId, includeMembers: true})
+ * const {data: organizationWithFeatures} = useOrganization({organizationId, includeFeatures: true})
  * ```
  * @public
  * @function
@@ -3153,18 +3259,19 @@ export declare const useOrganization: <
   IncludeFeatures extends boolean = false,
 >(
   options: OrganizationOptions<IncludeMembers, IncludeFeatures>,
-) => Organization<IncludeMembers, IncludeFeatures>;
+) => FetcherHookResult<Organization<IncludeMembers, IncludeFeatures>>;
 
 /**
  * Returns metadata for each organisation the current user has access to.
  *
  * @category Organizations
  * @param options - Configuration options
- * @returns An array of organisation metadata. `members` is included only when
- *   `includeMembers: true`; `features` is included only when `includeFeatures: true`.
+ * @returns A {@link FetcherHookResult} whose `data` is an array of organisation
+ *   metadata. `members` is included only when `includeMembers: true`; `features`
+ *   is included only when `includeFeatures: true`.
  * @example
  * ```tsx
- * const organizations = useOrganizations()
+ * const {data: organizations} = useOrganizations()
  *
  * return (
  *   <select>
@@ -3176,9 +3283,9 @@ export declare const useOrganization: <
  * ```
  * @example
  * ```tsx
- * const organizationsWithMembers = useOrganizations({includeMembers: true})
- * const organizationsWithFeatures = useOrganizations({includeFeatures: true})
- * const organizationsIncludingImplicit = useOrganizations({includeImplicitMemberships: true})
+ * const {data: organizationsWithMembers} = useOrganizations({includeMembers: true})
+ * const {data: organizationsWithFeatures} = useOrganizations({includeFeatures: true})
+ * const {data: organizationsIncludingImplicit} = useOrganizations({includeImplicitMemberships: true})
  * ```
  * @public
  * @function
@@ -3188,7 +3295,7 @@ export declare const useOrganizations: <
   IncludeFeatures extends boolean = false,
 >(
   options?: OrganizationsOptions<IncludeMembers, IncludeFeatures>,
-) => Organizations<IncludeMembers, IncludeFeatures>;
+) => FetcherHookResult<Organizations<IncludeMembers, IncludeFeatures>>;
 
 /**
  * Retrieves pages of {@link DocumentHandle}s, narrowed by optional filters, text searches, and custom ordering,
@@ -3324,12 +3431,13 @@ export declare function usePresence(options?: ResourceHandle): {
  *
  * @category Projects
  * @param options - Configuration options
- * @returns The metadata for the project. `members` is included only when
- *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
+ * @returns A {@link FetcherHookResult} whose `data` is the metadata for the
+ *   project. `members` is included only when `includeMembers: true`; `features`
+ *   is included unless `includeFeatures: false`.
  * @example
  * ```tsx
  * function ProjectMetadata({projectId}: {projectId: string}) {
- *   const project = useProject({projectId})
+ *   const {data: project} = useProject({projectId})
  *
  *   return (
  *     <figure style={{backgroundColor: project.metadata.color || 'lavender'}}>
@@ -3340,10 +3448,10 @@ export declare function usePresence(options?: ResourceHandle): {
  * ```
  * @example
  * ```tsx
- * const projectWithMembersAndFeatures = useProject({projectId})
- * const projectWithMembers = useProject({projectId, includeMembers: true})
- * const projectWithoutMembers = useProject({projectId, includeMembers: false})
- * const projectWithoutFeatures = useProject({projectId, includeFeatures: false})
+ * const {data: projectWithMembersAndFeatures} = useProject({projectId})
+ * const {data: projectWithMembers} = useProject({projectId, includeMembers: true})
+ * const {data: projectWithoutMembers} = useProject({projectId, includeMembers: false})
+ * const {data: projectWithoutFeatures} = useProject({projectId, includeFeatures: false})
  * ```
  * @remarks
  * The `projectId` is resolved in order from:
@@ -3359,18 +3467,19 @@ export declare const useProject: <
   IncludeFeatures extends boolean = true,
 >(
   options?: ProjectOptions<IncludeMembers, IncludeFeatures>,
-) => Project<IncludeMembers, IncludeFeatures>;
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>>;
 
 /**
  * Returns metadata for each project you have access to.
  *
  * @category Projects
  * @param options - Configuration options
- * @returns An array of project metadata. `members` is included only when
- *   `includeMembers: true`; `features` is included unless `includeFeatures: false`.
+ * @returns A {@link FetcherHookResult} whose `data` is an array of project
+ *   metadata. `members` is included only when `includeMembers: true`; `features`
+ *   is included unless `includeFeatures: false`.
  * @example
  * ```tsx
- * const projects = useProjects()
+ * const {data: projects} = useProjects()
  *
  * return (
  *   <select>
@@ -3382,11 +3491,11 @@ export declare const useProject: <
  * ```
  * @example
  * ```tsx
- * const projects = useProjects()
- * const projectsWithFeatures = useProjects()
- * const projectsWithMembers = useProjects({includeMembers: true})
- * const projectsWithoutMembers = useProjects({includeMembers: false})
- * const projectsWithoutFeatures = useProjects({includeFeatures: false})
+ * const {data: projects} = useProjects()
+ * const {data: projectsWithFeatures} = useProjects()
+ * const {data: projectsWithMembers} = useProjects({includeMembers: true})
+ * const {data: projectsWithoutMembers} = useProjects({includeMembers: false})
+ * const {data: projectsWithoutFeatures} = useProjects({includeFeatures: false})
  * ```
  * @public
  * @function
@@ -3396,7 +3505,7 @@ export declare const useProjects: <
   IncludeFeatures extends boolean = true,
 >(
   options?: ProjectsOptions<IncludeMembers, IncludeFeatures>,
-) => Project<IncludeMembers, IncludeFeatures>[];
+) => FetcherHookResult<Project<IncludeMembers, IncludeFeatures>[]>;
 
 /**
  * @public
@@ -3567,9 +3676,7 @@ export declare function useRecordDocumentHistoryEvent({
  */
 declare interface UseRecordDocumentHistoryEventProps extends DocumentHandle_2 {
   resourceType:
-    | StudioResource["type"]
-    | MediaResource["type"]
-    | CanvasResource["type"];
+    StudioResource["type"] | MediaResource["type"] | CanvasResource["type"];
   resourceId?: string;
   /**
    * The name of the schema collection this document belongs to.
@@ -3700,6 +3807,28 @@ export declare const useSanityInstance: (
  */
 export declare function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult;
 
+/**
+ * Updates an application's mutable properties (title, icon, visibility).
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
+ */
+export declare const useUpdateApplication: () => MutationHookResult<
+  UpdateApplicationInput,
+  ApplicationBase
+>;
+
+/**
+ * Updates a user application.
+ *
+ * @internal
+ * @returns The mutation envelope `{mutate, isPending, error, data, reset}`.
+ */
+export declare const useUpdateUserApplication: () => MutationHookResult<
+  UpdateUserApplicationInput,
+  UserApplication
+>;
+
 /**
  *
  * @public
@@ -3734,6 +3863,32 @@ export declare function useStudioWorkspacesByProjectIdDataset(): StudioWorkspace
  */
 export declare function useUser(options: GetUserOptions): UserResult;
 
+/**
+ * Returns a single user application by id.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ *
+ * @public
+ * @param userApplicationId - The user application id.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useUserApplication: (
+  userApplicationId: string,
+) => FetcherHookResult<UserApplication>;
+
+/**
+ * Returns the current user's applications for the given organisation.
+ *
+ * The hook suspends until the first fetch succeeds, so `data` is always present.
+ *
+ * @public
+ * @param options - Options identifying the organisation.
+ * @returns The result envelope `{data, isFetching, error, refetch}`.
+ */
+export declare const useUserApplications: (
+  options: UserApplicationsOptions,
+) => FetcherHookResult<UserApplication[]>;
+
 /**
  *
  * @public