@sanity/sdk 2.3.0 → 2.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _sanity_client12 from "@sanity/client";
-import { ClientConfig, ClientPerspective, ListenEvent, ResponseQueryOptions, SanityClient, SanityDocument as SanityDocument$1, SanityProject as SanityProject$1, StackablePerspective } from "@sanity/client";
+import { ClientConfig, ClientError, ClientPerspective, ListenEvent, ResponseQueryOptions, SanityClient, SanityDocument as SanityDocument$1, SanityProject as SanityProject$1, StackablePerspective } from "@sanity/client";
 import { Observable, Subject } from "rxjs";
 import { CurrentUser, CurrentUser as CurrentUser$1, Mutation, PatchOperations, Role, SanityDocument, SanityDocument as SanityDocument$2, SanityDocumentLike } from "@sanity/types";
 import * as _sanity_comlink3 from "@sanity/comlink";
@@ -9,17 +9,6 @@ import { SanityDocument as SanityDocument$3, SanityProjectionResult, SanityQuery
 import { ExprNode } from "groq-js";
 import { CanvasResource, MediaResource, StudioResource } from "@sanity/message-protocol";
 import { getIndexForKey, getPathDepth, joinPaths, jsonMatch, slicePath, stringifyPath } from "@sanity/json-match";
-/**
- * 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",
-}
 /**
  * Configuration for an authentication provider
  * @public
@@ -150,6 +139,39 @@ interface SanityConfig extends DatasetHandle, PerspectiveHandle {
     enabled: boolean;
   };
 }
+declare const SOURCE_ID = "__sanity_internal_sourceId";
+/**
+ * A document source can be used for querying.
+ *
+ * @beta
+ * @see datasetSource Construct a document source for a given projectId and dataset.
+ * @see mediaLibrarySource Construct a document source for a mediaLibraryId.
+ * @see canvasSource Construct a document source for a canvasId.
+ */
+type DocumentSource = {
+  [SOURCE_ID]: ['media-library', string] | ['canvas', string] | {
+    projectId: string;
+    dataset: string;
+  };
+};
+/**
+ * Returns a document source for a projectId and dataset.
+ *
+ * @beta
+ */
+declare function datasetSource(projectId: string, dataset: string): DocumentSource;
+/**
+ * Returns a document source for a Media Library.
+ *
+ * @beta
+ */
+declare function mediaLibrarySource(id: string): DocumentSource;
+/**
+ * Returns a document source for a Canvas.
+ *
+ * @beta
+ */
+declare function canvasSource(id: string): DocumentSource;
 /**
  * Represents a Sanity.io resource instance with its own configuration and lifecycle
  * @remarks Instances form a hierarchy through parent/child relationships
@@ -211,6 +233,77 @@ interface SanityInstance {
  * @public
  */
 declare function createSanityInstance(config?: SanityConfig): SanityInstance;
+/** @alpha */
+type AgentGenerateOptions = Parameters<SanityClient['observable']['agent']['action']['generate']>[0];
+/** @alpha */
+type AgentTransformOptions = Parameters<SanityClient['observable']['agent']['action']['transform']>[0];
+/** @alpha */
+type AgentTranslateOptions = Parameters<SanityClient['observable']['agent']['action']['translate']>[0];
+/** @alpha */
+type AgentPromptOptions = Parameters<SanityClient['agent']['action']['prompt']>[0];
+/** @alpha */
+type AgentPatchOptions = Parameters<SanityClient['agent']['action']['patch']>[0];
+/** @alpha */
+type AgentGenerateResult = Awaited<ReturnType<SanityClient['observable']['agent']['action']['generate']>>;
+/** @alpha */
+type AgentTransformResult = Awaited<ReturnType<SanityClient['observable']['agent']['action']['transform']>>;
+/** @alpha */
+type AgentTranslateResult = Awaited<ReturnType<SanityClient['observable']['agent']['action']['translate']>>;
+/** @alpha */
+type AgentPromptResult = Awaited<ReturnType<SanityClient['agent']['action']['prompt']>>;
+/** @alpha */
+type AgentPatchResult = Awaited<ReturnType<SanityClient['agent']['action']['patch']>>;
+/**
+ * Generates a new document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent generate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent generate action.
+ * @alpha
+ */
+declare function agentGenerate(instance: SanityInstance, options: AgentGenerateOptions): AgentGenerateResult;
+/**
+ * Transforms a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent transform action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent transform action.
+ * @alpha
+ */
+declare function agentTransform(instance: SanityInstance, options: AgentTransformOptions): AgentTransformResult;
+/**
+ * Translates a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent translate action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent translate action.
+ * @alpha
+ */
+declare function agentTranslate(instance: SanityInstance, options: AgentTranslateOptions): AgentTranslateResult;
+/**
+ * Prompts the agent using the same instruction template format as the other actions, but returns text or json instead of acting on a document.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent prompt action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent prompt action.
+ * @alpha
+ */
+declare function agentPrompt(instance: SanityInstance, options: AgentPromptOptions): Observable<AgentPromptResult>;
+/**
+ * Patches a document using the agent.
+ * @param instance - The Sanity instance.
+ * @param options - The options for the agent patch action. See the [Agent Actions API](https://www.sanity.io/docs/agent-actions/introduction) for more details.
+ * @returns An Observable emitting the result of the agent patch action.
+ * @alpha
+ */
+declare function agentPatch(instance: SanityInstance, options: AgentPatchOptions): Observable<AgentPatchResult>;
+/**
+ * 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 a store action that has been bound to a specific store instance
  */
@@ -288,6 +381,10 @@ interface DashboardContext {
   env?: string;
   orgId?: string;
 }
+/**
+ * The method of authentication used.
+ * @internal
+ */
 type AuthMethodOptions = 'localstorage' | 'cookie' | undefined;
 /**
  * @public
@@ -370,6 +467,24 @@ declare const handleAuthCallback: BoundStoreAction<AuthStoreState, [locationHref
  * @public
  */
 declare const logout: BoundStoreAction<AuthStoreState, [], Promise<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;
 type AllowedClientConfigKey = 'useCdn' | 'token' | 'perspective' | 'apiHost' | 'proxy' | 'withCredentials' | 'timeout' | 'maxRetries' | 'dataset' | 'projectId' | 'requestTagPrefix' | 'useProjectHostname';
 /**
  * States tracked by the client store
@@ -411,6 +526,10 @@ interface ClientOptions extends Pick<ClientConfig, AllowedClientConfigKey> {
    * @internal
    */
   '~experimental_resource'?: ClientConfig['~experimental_resource'];
+  /**
+   * @internal
+   */
+  'source'?: DocumentSource;
 }
 /**
  * Retrieves a Sanity client instance configured with the provided options.
@@ -592,6 +711,12 @@ declare const resolveDatasets: BoundStoreAction<FetcherStoreState<[options?: Pro
  */
 interface CreateDocumentAction<TDocumentType extends string = string, TDataset extends string = string, TProjectId extends string = string> extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
   type: 'document.create';
+  /**
+   * Optional initial field values for the document.
+   * These values will be set when the document is created.
+   * System fields (_id, _type, _rev, _createdAt, _updatedAt) are omitted as they are set automatically.
+   */
+  initialValue?: Partial<Omit<SanityDocument$3<TDocumentType, `${TProjectId}.${TDataset}`>, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>>;
 }
 /**
  * Represents an action to delete an existing document.
@@ -642,10 +767,11 @@ type DocumentAction<TDocumentType extends string = string, TDataset extends stri
 /**
  * Creates a `CreateDocumentAction` object.
  * @param doc - A handle identifying the document type, dataset, and project. An optional `documentId` can be provided.
+ * @param initialValue - Optional initial field values for the document. (System fields are omitted as they are set automatically.)
  * @returns A `CreateDocumentAction` object ready for dispatch.
  * @beta
  */
-declare function createDocument<TDocumentType extends string = string, TDataset extends string = string, TProjectId extends string = string>(doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>): CreateDocumentAction<TDocumentType, TDataset, TProjectId>;
+declare function createDocument<TDocumentType extends string = string, TDataset extends string = string, TProjectId extends string = string>(doc: DocumentTypeHandle<TDocumentType, TDataset, TProjectId>, initialValue?: Partial<Omit<SanityDocument$3<TDocumentType, `${TProjectId}.${TDataset}`>, '_id' | '_type' | '_rev' | '_createdAt' | '_updatedAt'>>): CreateDocumentAction<TDocumentType, TDataset, TProjectId>;
 /**
  * Creates a `DeleteDocumentAction` object.
  * @param doc - A handle uniquely identifying the document to be deleted.
@@ -1490,6 +1616,7 @@ declare const resolveProjects: BoundStoreAction<FetcherStoreState<[options?: {
 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>;
+  source?: DocumentSource;
 }
 /**
  * @beta
@@ -1575,7 +1702,7 @@ declare const getActiveReleasesState: BoundStoreAction<ReleasesStoreState, [], S
  *
  * @public
  */
-declare const getPerspectiveState: BoundStoreAction<ReleasesStoreState, [options?: PerspectiveHandle | undefined], StateSource<string[] | "previewDrafts" | "published" | "drafts" | "raw" | undefined>>;
+declare const getPerspectiveState: BoundStoreAction<ReleasesStoreState, [options?: PerspectiveHandle | undefined], StateSource<string[] | "raw" | "previewDrafts" | "published" | "drafts" | undefined>>;
 /** @internal */
 declare const getUsersKey: (instance: SanityInstance, {
   resourceType,
@@ -1605,7 +1732,7 @@ declare const parseUsersKey: (key: string) => {
  *
  * @beta
  */
-declare const getUsersState: BoundStoreAction<UsersStoreState, [options?: GetUsersOptions], StateSource<{
+declare const getUsersState: BoundStoreAction<UsersStoreState, [options?: GetUsersOptions | undefined], StateSource<{
   data: SanityUser[];
   totalCount: number;
   hasMore: boolean;
@@ -1654,7 +1781,7 @@ declare const getUserState: BoundStoreAction<UsersStoreState, [GetUserOptions],
 /**
  * @beta
  */
-declare const resolveUser: BoundStoreAction<UsersStoreState, [ResolveUserOptions], Promise<SanityUser | undefined>>;
+declare const resolveUser: BoundStoreAction<UsersStoreState, [ResolveUserOptions], Promise<SanityUser>>;
 interface StoreEntry<TParams extends unknown[], TData> {
   params: TParams;
   instance: SanityInstance;
@@ -1866,4 +1993,4 @@ declare const CORE_SDK_VERSION: {};
  * @public
  */
 type SanityProject = SanityProject$1;
-export { type ActionErrorEvent, type ActionsResult, type ApplyDocumentActionsOptions, type AuthConfig, type AuthProvider, type AuthState, AuthStateType, type AuthStoreState, CORE_SDK_VERSION, type ClientOptions, type ClientStoreState as ClientState, type ComlinkControllerState, type ComlinkNodeState, type CreateDocumentAction, type CurrentUser, type DatasetHandle, type DeleteDocumentAction, type DiscardDocumentAction, type DisconnectEvent, type DocumentAction, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentDiscardedEvent, type DocumentEditedEvent, type DocumentEvent, type DocumentHandle, type DocumentOptions, type DocumentPermissionsResult, type DocumentPublishedEvent, type DocumentTypeHandle, type DocumentUnpublishedEvent, type EditDocumentAction, type ErrorAuthState, type FavoriteStatusResponse, type FetcherStore, type FetcherStoreState, type FrameMessage, type GetPreviewStateOptions, type GetUserOptions, type GetUsersOptions, type Intent, type IntentFilter, type JsonMatch, type LoggedInAuthState, type LoggedOutAuthState, type LoggingInAuthState, type Membership, type NewTokenResponseMessage, type NodeState, type OrgVerificationResult, type PermissionDeniedReason, type PerspectiveHandle, type PresenceLocation, type PreviewStoreState, type PreviewValue, type ProjectHandle, type ProjectionValuePending, type PublishDocumentAction, type QueryOptions, type ReleaseDocument, type ReleasePerspective, type RequestNewTokenMessage, type ResolvePreviewOptions, type ResolveUserOptions, type ResolveUsersOptions, type Role, type RollCallEvent, type SanityConfig, type SanityDocument, type SanityInstance, SanityProject, type SanityUser, type SanityUserResponse, type Selector, type StateEvent, type StateSource, type TransactionAcceptedEvent, type TransactionRevertedEvent, type TransportEvent, type UnpublishDocumentAction, type UserPresence, type UserProfile, type UsersGroupState, type UsersStoreState, type ValidProjection, type ValuePending, type WindowMessage, applyDocumentActions, createDatasetHandle, createDocument, createDocumentHandle, createDocumentTypeHandle, createGroqSearchFilter, createProjectHandle, createSanityInstance, defineIntent, deleteDocument, destroyController, discardDocument, editDocument, getActiveReleasesState, getAuthState, getClient, getClientState, getCorsErrorProjectId, getCurrentUserState, getDashboardOrganizationId, getDatasetsState, getDocumentState, getDocumentSyncStatus, getFavoritesState, getIndexForKey, getIsInDashboardState, getLoginUrlState, getNodeState, getOrCreateChannel, getOrCreateController, getOrCreateNode, getPathDepth, getPermissionsState, getPerspectiveState, getPresence, getPreviewState, getProjectState, getProjectionState, getProjectsState, getQueryKey, getQueryState, getTokenState, getUserState, getUsersKey, getUsersState, handleAuthCallback, joinPaths, jsonMatch, loadMoreUsers, logout, observeOrganizationVerificationState, parseQueryKey, parseUsersKey, publishDocument, releaseChannel, releaseNode, resolveDatasets, resolveDocument, resolveFavoritesState, resolvePermissions, resolvePreview, resolveProject, resolveProjection, resolveProjects, resolveQuery, resolveUser, resolveUsers, setAuthToken, slicePath, stringifyPath, subscribeDocumentEvents, unpublishDocument };
+export { type ActionErrorEvent, type ActionsResult, type AgentGenerateOptions, type AgentGenerateResult, type AgentPatchOptions, type AgentPatchResult, type AgentPromptOptions, type AgentPromptResult, type AgentTransformOptions, type AgentTransformResult, type AgentTranslateOptions, type AgentTranslateResult, type ApiErrorBody, type ApplyDocumentActionsOptions, type AuthConfig, type AuthProvider, type AuthState, AuthStateType, type AuthStoreState, CORE_SDK_VERSION, type ClientOptions, type ClientStoreState as ClientState, type ComlinkControllerState, type ComlinkNodeState, type CreateDocumentAction, type CurrentUser, type DatasetHandle, type DeleteDocumentAction, type DiscardDocumentAction, type DisconnectEvent, type DocumentAction, type DocumentCreatedEvent, type DocumentDeletedEvent, type DocumentDiscardedEvent, type DocumentEditedEvent, type DocumentEvent, type DocumentHandle, type DocumentOptions, type DocumentPermissionsResult, type DocumentPublishedEvent, type DocumentSource, type DocumentTypeHandle, type DocumentUnpublishedEvent, type EditDocumentAction, type ErrorAuthState, type FavoriteStatusResponse, type FetcherStore, type FetcherStoreState, type FrameMessage, type GetPreviewStateOptions, type GetUserOptions, type GetUsersOptions, type Intent, type IntentFilter, type JsonMatch, type LoggedInAuthState, type LoggedOutAuthState, type LoggingInAuthState, type Membership, type NewTokenResponseMessage, type NodeState, type OrgVerificationResult, type PermissionDeniedReason, type PerspectiveHandle, type PresenceLocation, type PreviewStoreState, type PreviewValue, type ProjectHandle, type ProjectionValuePending, type PublishDocumentAction, type QueryOptions, type ReleaseDocument, type ReleasePerspective, type RequestNewTokenMessage, type ResolvePreviewOptions, type ResolveUserOptions, type ResolveUsersOptions, type Role, type RollCallEvent, type SanityConfig, type SanityDocument, type SanityInstance, SanityProject, type SanityUser, type SanityUserResponse, type Selector, type StateEvent, type StateSource, type TransactionAcceptedEvent, type TransactionRevertedEvent, type TransportEvent, type UnpublishDocumentAction, type UserPresence, type UserProfile, type UsersGroupState, type UsersStoreState, type ValidProjection, type ValuePending, type WindowMessage, agentGenerate, agentPatch, agentPrompt, agentTransform, agentTranslate, applyDocumentActions, canvasSource, createDatasetHandle, createDocument, createDocumentHandle, createDocumentTypeHandle, createGroqSearchFilter, createProjectHandle, createSanityInstance, datasetSource, defineIntent, deleteDocument, destroyController, discardDocument, editDocument, getActiveReleasesState, getAuthState, getClient, getClientErrorApiBody, getClientErrorApiDescription, getClientErrorApiType, getClientState, getCorsErrorProjectId, getCurrentUserState, getDashboardOrganizationId, getDatasetsState, getDocumentState, getDocumentSyncStatus, getFavoritesState, getIndexForKey, getIsInDashboardState, getLoginUrlState, getNodeState, getOrCreateChannel, getOrCreateController, getOrCreateNode, getPathDepth, getPermissionsState, getPerspectiveState, getPresence, getPreviewState, getProjectState, getProjectionState, getProjectsState, getQueryKey, getQueryState, getTokenState, getUserState, getUsersKey, getUsersState, handleAuthCallback, isProjectUserNotFoundClientError, joinPaths, jsonMatch, loadMoreUsers, logout, mediaLibrarySource, observeOrganizationVerificationState, parseQueryKey, parseUsersKey, publishDocument, releaseChannel, releaseNode, resolveDatasets, resolveDocument, resolveFavoritesState, resolvePermissions, resolvePreview, resolveProject, resolveProjection, resolveProjects, resolveQuery, resolveUser, resolveUsers, setAuthToken, slicePath, stringifyPath, subscribeDocumentEvents, unpublishDocument };