@sanity/sdk-react 2.3.1 → 2.5.0

package/dist/index.d.ts

@@ -1,4 +1,11 @@
 import {ActionsResult} from '@sanity/sdk'
+import {AgentGenerateOptions} from '@sanity/sdk'
+import {AgentPatchOptions} from '@sanity/sdk'
+import {AgentPatchResult} from '@sanity/sdk'
+import {AgentPromptOptions} from '@sanity/sdk'
+import {AgentPromptResult} from '@sanity/sdk'
+import {AgentTransformOptions} from '@sanity/sdk'
+import {AgentTranslateOptions} from '@sanity/sdk'
 import {ApplyDocumentActionsOptions} from '@sanity/sdk'
 import {AuthState} from '@sanity/sdk'
 import {CanvasResource} from '@sanity/message-protocol'
@@ -11,6 +18,7 @@ import {DocumentEvent} from '@sanity/sdk'
 import {DocumentHandle} from '@sanity/sdk'
 import {DocumentOptions} from '@sanity/sdk'
 import {DocumentPermissionsResult} from '@sanity/sdk'
+import {DocumentSource} from '@sanity/sdk'
 import {FallbackProps} from 'react-error-boundary'
 import {FavoriteStatusResponse} from '@sanity/sdk'
 import {FrameMessage} from '@sanity/sdk'
@@ -44,6 +52,24 @@ import {StudioResource} from '@sanity/message-protocol'
 import {UserPresence} from '@sanity/sdk'
 import {WindowMessage} from '@sanity/sdk'
 
+/**
+ * @public
+ */
+export declare interface AgentResourceContextOptions {
+  /**
+   * The project ID of the current context
+   */
+  projectId: string
+  /**
+   * The dataset of the current context
+   */
+  dataset: string
+  /**
+   * Optional document ID if the user is viewing/editing a specific document
+   */
+  documentId?: string
+}
+
 /**
  * A component that handles authentication flow and error boundaries for a
  * protected section of the application.
@@ -142,6 +168,26 @@ declare interface DashboardResource {
 
 export {DatasetsResponse}
 
+/**
+ * Return type for the useDispatchIntent hook
+ * @beta
+ */
+declare interface DispatchIntent {
+  dispatchIntent: () => void
+}
+
+/**
+ * Document handle that optionally includes a source (e.g., media library source)
+ * or projectId and dataset for traditional dataset sources
+ * (but now marked optional since it's valid to just use a source)
+ * @beta
+ */
+declare interface DocumentHandleWithSource extends Omit<DocumentHandle, 'projectId' | 'dataset'> {
+  source?: DocumentSource
+  projectId?: string
+  dataset?: string
+}
+
 declare interface DocumentInteractionHistory {
   recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
 }
@@ -156,8 +202,8 @@ export declare interface DocumentsOptions<
   TDocumentType extends string = string,
   TDataset extends string = string,
   TProjectId extends string = string,
-> extends DatasetHandle<TDataset, TProjectId>,
-    Pick<QueryOptions, 'perspective' | 'params'> {
+>
+  extends DatasetHandle<TDataset, TProjectId>, Pick<QueryOptions, 'perspective' | 'params'> {
   /**
    * Filter documents by their `_type`. Can be a single type or an array of types.
    */
@@ -269,6 +315,12 @@ export declare interface NavigateToStudioResult {
   navigateToStudioDocument: () => void
 }
 
+declare interface Observer<T> {
+  next?: (value: T) => void
+  error?: (err: unknown) => void
+  complete?: () => void
+}
+
 /**
  * Configuration options for the usePaginatedDocuments hook
  *
@@ -569,6 +621,19 @@ declare interface StudioWorkspacesResult {
   error: string | null
 }
 
+declare interface Subscribable<T> {
+  subscribe(observer: Observer<T>): Subscription
+  subscribe(
+    next: (value: T) => void,
+    error?: (err: unknown) => void,
+    complete?: () => void,
+  ): Subscription
+}
+
+declare interface Subscription {
+  unsubscribe(): void
+}
+
 declare type Updater<TValue> = TValue | ((currentValue: TValue) => TValue)
 
 /**
@@ -595,6 +660,102 @@ declare type UseActiveReleases = {
  */
 export declare const useActiveReleases: UseActiveReleases
 
+/**
+ * @alpha
+ * Generates content for a document (or specific fields) via Sanity Agent Actions.
+ * - Uses instruction templates with `$variables` and supports `instructionParams` (constants, fields, documents, GROQ queries).
+ * - Can target specific paths/fields; supports image generation when targeting image fields.
+ * - Supports optional `temperature`, `async`, `noWrite`, and `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export declare const useAgentGenerate: () => (
+  options: AgentGenerateOptions,
+) => Subscribable<unknown>
+
+/**
+ * @alpha
+ * Schema-aware patching with Sanity Agent Actions.
+ * - Validates provided paths/values against the document schema and merges object values safely.
+ * - Prevents duplicate keys and supports array appends (including after a specific keyed item).
+ * - Accepts `documentId` or `targetDocument` (mutually exclusive).
+ * - Optional `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the patch result.
+ */
+export declare const useAgentPatch: () => (options: AgentPatchOptions) => Promise<AgentPatchResult>
+
+/**
+ * @alpha
+ * Prompts the LLM using the same instruction template format as other actions.
+ * - `format`: 'string' or 'json' (instruction must contain the word "json" for JSON responses).
+ * - Optional `temperature`.
+ *
+ * Returns a stable callback that triggers the action and resolves a Promise with the prompt result.
+ */
+export declare const useAgentPrompt: () => (
+  options: AgentPromptOptions,
+) => Promise<AgentPromptResult>
+
+/**
+ * @public
+ * Hook for emitting agent resource context updates to the Dashboard.
+ * This allows the Agent to understand what resource the user is currently
+ * interacting with (e.g., which document they're editing).
+ *
+ * The hook will automatically emit the context when it changes, and also
+ * emit the initial context when the hook is first mounted.
+ *
+ * @category Agent
+ * @param options - The resource context options containing projectId, dataset, and optional documentId
+ *
+ * @example
+ * ```tsx
+ * import {useAgentResourceContext} from '@sanity/sdk-react'
+ *
+ * function MyComponent() {
+ *   const documentId = 'my-document-id'
+ *
+ *   // Automatically updates the Agent's context whenever the document changes
+ *   useAgentResourceContext({
+ *     projectId: 'my-project',
+ *     dataset: 'production',
+ *     documentId,
+ *   })
+ *
+ *   return <div>Editing document: {documentId}</div>
+ * }
+ * ```
+ */
+export declare function useAgentResourceContext(options: AgentResourceContextOptions): void
+
+/**
+ * @alpha
+ * Transforms an existing document or selected fields using Sanity Agent Actions.
+ * - Accepts `instruction` and `instructionParams` (constants, fields, documents, GROQ queries).
+ * - Can write to the same or a different `targetDocument` (create/edit), and target specific paths.
+ * - Supports per-path image transform instructions and image description operations.
+ * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export declare const useAgentTransform: () => (
+  options: AgentTransformOptions,
+) => Subscribable<unknown>
+
+/**
+ * @alpha
+ * Translates documents or fields using Sanity Agent Actions.
+ * - Configure `fromLanguage`/`toLanguage`, optional `styleGuide`, and `protectedPhrases`.
+ * - Can write into a different `targetDocument`, and/or store language in a field.
+ * - Optional `temperature`, `async`, `noWrite`, `conditionalPaths`.
+ *
+ * Returns a stable callback that triggers the action and yields a Subscribable stream.
+ */
+export declare const useAgentTranslate: () => (
+  options: AgentTranslateOptions,
+) => Subscribable<unknown>
+
 /**
  * @public
  */
@@ -702,6 +863,37 @@ declare interface UseApplyDocumentActions {
  *   )
  * }
  * ```
+ *
+ * @example Create a document with initial field values
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateArticleButton() {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateArticle = () => {
+ *     const newDocHandle = createDocumentHandle({
+ *       documentId: crypto.randomUUID(),
+ *       documentType: 'article'
+ *     })
+ *
+ *     // Create document with initial values in one action
+ *     apply(
+ *       createDocument(newDocHandle, {
+ *         title: 'New Article',
+ *         author: 'John Doe',
+ *         publishedAt: new Date().toISOString(),
+ *       })
+ *     )
+ *   }
+ *
+ *   return <button onClick={handleCreateArticle}>Create Article</button>
+ * }
+ * ```
  */
 export declare const useApplyDocumentActions: UseApplyDocumentActions
 
@@ -762,7 +954,7 @@ export declare const useAuthToken: () => string | null
  * @public
  * @function
  */
-export declare const useClient: (x: ClientOptions) => SanityClient
+export declare const useClient: (options: ClientOptions) => SanityClient
 
 declare type UseCurrentUser = {
   /**
@@ -894,6 +1086,70 @@ declare type UseDatasets = {
  */
 export declare const useDatasets: UseDatasets
 
+/**
+ * @beta
+ *
+ * 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 sources, like `{documentId: '123', documentType: 'book', projectId: 'abc123', dataset: 'production'}`
+ *     - `source` for media library, canvas, or dataset sources, like `{documentId: '123', documentType: 'sanity.asset', source: mediaLibrarySource('ml123')}` or `{documentId: '123', documentType: 'sanity.canvas.document', source: 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>
+ *   )
+ * }
+ * ```
+ */
+export declare function useDispatchIntent(params: UseDispatchIntentParams): DispatchIntent
+
+/**
+ * Parameters for the useDispatchIntent hook
+ * @beta
+ */
+declare interface UseDispatchIntentParams {
+  action?: 'edit'
+  intentId?: string
+  documentHandle: DocumentHandleWithSource
+  parameters?: Record<string, unknown>
+}
+
 declare interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
@@ -2499,7 +2755,7 @@ export declare function useUser(options: GetUserOptions): UserResult
  *         <address>{user.profile.email}</address>
  *       </figure>
  *     ))}
- *     {hasMore && <button onClick={loadMore}>{isPending ? 'Loading...' : 'Load More'</button>}
+ *     {hasMore && <button onClick={loadMore}>{isPending ? 'Loading...' : 'Load More'}</button>}
  *   </div>
  * )
  * ```