@sanity/client 7.14.1 → 7.16.0

package/src/data/listen.ts

@@ -11,6 +11,10 @@ import {
   type MutationEvent,
   type OpenEvent,
   type ReconnectEvent,
+  type ResetEvent,
+  type ResumableListenEventNames,
+  type ResumableListenOptions,
+  type WelcomeBackEvent,
   type WelcomeEvent,
 } from '../types'
 import defaults from '../util/defaults'
@@ -33,6 +37,7 @@ const possibleOptions = [
   'includeAllVersions',
   'visibility',
   'effectFormat',
+  'enableResume',
   'tag',
 ]
 
@@ -51,7 +56,10 @@ const defaultOptions = {
  */
 export type MapListenEventNamesToListenEvents<
   R extends Record<string, Any> = Record<string, Any>,
-  Events extends ListenEventName[] = ListenEventName[],
+  Events extends (ResumableListenEventNames | ListenEventName)[] = (
+    | ResumableListenEventNames
+    | ListenEventName
+  )[],
 > = Events extends (infer E)[]
   ? E extends 'welcome'
     ? WelcomeEvent
@@ -59,9 +67,13 @@ export type MapListenEventNamesToListenEvents<
       ? MutationEvent<R>
       : E extends 'reconnect'
         ? ReconnectEvent
-        : E extends 'open'
-          ? OpenEvent
-          : never
+        : E extends 'welcomeback'
+          ? WelcomeBackEvent
+          : E extends 'reset'
+            ? ResetEvent
+            : E extends 'open'
+              ? OpenEvent
+              : never
   : never
 
 /**
@@ -75,9 +87,9 @@ export type MapListenEventNamesToListenEvents<
  */
 export type ListenEventFromOptions<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions | undefined = undefined,
-> = Opts extends ListenOptions
-  ? Opts['events'] extends ListenEventName[]
+  Opts extends ListenOptions | ResumableListenOptions | undefined = undefined,
+> = Opts extends ListenOptions | ResumableListenOptions
+  ? Opts['events'] extends (ResumableListenEventNames | ListenEventName)[]
     ? MapListenEventNamesToListenEvents<R, Opts['events']>
     : // fall back to ListenEvent if opts events is present, but we can't infer the literal event names
       ListenEvent<R>
@@ -106,7 +118,7 @@ export function _listen<R extends Record<string, Any> = Record<string, Any>>(
  */
 export function _listen<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions = ListenOptions,
+  Opts extends ListenOptions | ResumableListenOptions = ListenOptions | ResumableListenOptions,
 >(
   this: SanityClient | ObservableSanityClient,
   query: string,
@@ -116,7 +128,7 @@ export function _listen<
 /** @public */
 export function _listen<
   R extends Record<string, Any> = Record<string, Any>,
-  Opts extends ListenOptions = ListenOptions,
+  Opts extends ListenOptions | ResumableListenOptions = ListenOptions | ResumableListenOptions,
 >(
   this: SanityClient | ObservableSanityClient,
   query: string,

package/src/datasets/DatasetsClient.ts

@@ -2,7 +2,15 @@ import {lastValueFrom, type Observable} from 'rxjs'
 
 import {_request} from '../data/dataMethods'
 import type {ObservableSanityClient, SanityClient} from '../SanityClient'
-import type {DatasetAclMode, DatasetResponse, DatasetsResponse, HttpRequest} from '../types'
+import type {
+  DatasetCreateOptions,
+  DatasetEditOptions,
+  DatasetResponse,
+  DatasetsResponse,
+  EmbeddingsSettings,
+  EmbeddingsSettingsBody,
+  HttpRequest,
+} from '../types'
 import * as validate from '../validators'
 
 /** @internal */
@@ -18,9 +26,9 @@ export class ObservableDatasetsClient {
    * Create a new dataset with the given name
    *
    * @param name - Name of the dataset to create
-   * @param options - Options for the dataset
+   * @param options - Options for the dataset, including optional embeddings configuration
    */
-  create(name: string, options?: {aclMode?: DatasetAclMode}): Observable<DatasetResponse> {
+  create(name: string, options?: DatasetCreateOptions): Observable<DatasetResponse> {
     return _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PUT', name, options)
   }
 
@@ -30,7 +38,7 @@ export class ObservableDatasetsClient {
    * @param name - Name of the dataset to edit
    * @param options - New options for the dataset
    */
-  edit(name: string, options?: {aclMode?: DatasetAclMode}): Observable<DatasetResponse> {
+  edit(name: string, options?: DatasetEditOptions): Observable<DatasetResponse> {
     return _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PATCH', name, options)
   }
 
@@ -60,6 +68,37 @@ export class ObservableDatasetsClient {
       tag: null,
     })
   }
+
+  /**
+   * Get embeddings settings for a dataset
+   *
+   * @param name - Name of the dataset
+   */
+  getEmbeddingsSettings(name: string): Observable<EmbeddingsSettings> {
+    validate.resourceGuard('dataset', this.#client.config())
+    validate.dataset(name)
+    return _request<EmbeddingsSettings>(this.#client, this.#httpRequest, {
+      uri: _embeddingsSettingsUri(this.#client, name),
+      tag: null,
+    })
+  }
+
+  /**
+   * Edit embeddings settings for a dataset
+   *
+   * @param name - Name of the dataset
+   * @param settings - Embeddings settings to apply
+   */
+  editEmbeddingsSettings(name: string, settings: EmbeddingsSettingsBody): Observable<void> {
+    validate.resourceGuard('dataset', this.#client.config())
+    validate.dataset(name)
+    return _request<void>(this.#client, this.#httpRequest, {
+      method: 'PUT',
+      uri: _embeddingsSettingsUri(this.#client, name),
+      body: settings,
+      tag: null,
+    })
+  }
 }
 
 /** @internal */
@@ -75,9 +114,9 @@ export class DatasetsClient {
    * Create a new dataset with the given name
    *
    * @param name - Name of the dataset to create
-   * @param options - Options for the dataset
+   * @param options - Options for the dataset, including optional embeddings configuration
    */
-  create(name: string, options?: {aclMode?: DatasetAclMode}): Promise<DatasetResponse> {
+  create(name: string, options?: DatasetCreateOptions): Promise<DatasetResponse> {
     validate.resourceGuard('dataset', this.#client.config())
     return lastValueFrom(
       _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PUT', name, options),
@@ -90,7 +129,7 @@ export class DatasetsClient {
    * @param name - Name of the dataset to edit
    * @param options - New options for the dataset
    */
-  edit(name: string, options?: {aclMode?: DatasetAclMode}): Promise<DatasetResponse> {
+  edit(name: string, options?: DatasetEditOptions): Promise<DatasetResponse> {
     validate.resourceGuard('dataset', this.#client.config())
     return lastValueFrom(
       _modify<DatasetResponse>(this.#client, this.#httpRequest, 'PATCH', name, options),
@@ -123,6 +162,52 @@ export class DatasetsClient {
       _request<DatasetsResponse>(this.#client, this.#httpRequest, {uri, tag: null}),
     )
   }
+
+  /**
+   * Get embeddings settings for a dataset
+   *
+   * @param name - Name of the dataset
+   */
+  getEmbeddingsSettings(name: string): Promise<EmbeddingsSettings> {
+    validate.resourceGuard('dataset', this.#client.config())
+    validate.dataset(name)
+    return lastValueFrom(
+      _request<EmbeddingsSettings>(this.#client, this.#httpRequest, {
+        uri: _embeddingsSettingsUri(this.#client, name),
+        tag: null,
+      }),
+    )
+  }
+
+  /**
+   * Edit embeddings settings for a dataset
+   *
+   * @param name - Name of the dataset
+   * @param settings - Embeddings settings to apply
+   */
+  editEmbeddingsSettings(name: string, settings: EmbeddingsSettingsBody): Promise<void> {
+    validate.resourceGuard('dataset', this.#client.config())
+    validate.dataset(name)
+    return lastValueFrom(
+      _request<void>(this.#client, this.#httpRequest, {
+        method: 'PUT',
+        uri: _embeddingsSettingsUri(this.#client, name),
+        body: settings,
+        tag: null,
+      }),
+    )
+  }
+}
+
+function _embeddingsSettingsUri(
+  client: SanityClient | ObservableSanityClient,
+  name: string,
+): string {
+  const config = client.config()
+  if (config.useProjectHostname === false) {
+    return `/projects/${config.projectId}/datasets/${name}/settings/embeddings`
+  }
+  return `/datasets/${name}/settings/embeddings`
 }
 
 function _modify<R = unknown>(
@@ -130,7 +215,7 @@ function _modify<R = unknown>(
   httpRequest: HttpRequest,
   method: 'DELETE' | 'PATCH' | 'PUT',
   name: string,
-  options?: {aclMode?: DatasetAclMode},
+  options?: DatasetCreateOptions | DatasetEditOptions,
 ) {
   validate.resourceGuard('dataset', client.config())
   validate.dataset(name)

package/src/types.ts

@@ -463,6 +463,33 @@ export type AuthProviderResponse = {providers: AuthProvider[]}
 /** @public */
 export type DatasetAclMode = 'public' | 'private' | 'custom'
 
+/** @public */
+export type DatasetCreateOptions = {
+  aclMode?: DatasetAclMode
+  embeddings?: {
+    enabled: boolean
+    projection?: string
+  }
+}
+
+/** @public */
+export type DatasetEditOptions = {
+  aclMode?: DatasetAclMode
+}
+
+/** @public */
+export type EmbeddingsSettings = {
+  enabled: boolean
+  projection?: string
+  status: string
+}
+
+/** @public */
+export type EmbeddingsSettingsBody = {
+  enabled: boolean
+  projection?: string
+}
+
 /** @public */
 export type DatasetResponse = {datasetName: string; aclMode: DatasetAclMode}
 /** @public */
@@ -1151,8 +1178,14 @@ export type OpenEvent = {
 }
 
 /**
- * The listener has been established, and will start receiving events.
- * Note that this is also emitted upon _reconnection_.
+ * Emitted when the listener connection has been successfully established
+ * and is ready to receive events.
+ *
+ * If the listener was created with `enableResume: true` and resume support
+ * is available, the `welcome` event will only be emitted on the initial
+ * connection. On subsequent reconnects, a `welcomeback` event will be
+ * emitted instead, followed by any events that were missed while the
+ * connection was disconnected.
  *
  * @public
  */
@@ -1161,10 +1194,44 @@ export type WelcomeEvent = {
   listenerName: string
 }
 
+/**
+ * Emitted when the listener reconnects and successfully resumes from
+ * its previous position.
+ *
+ * Even if the listener is created with `enableResume: true`, resume support
+ * may not be available. In that case, a reconnect will emit `welcome`
+ * instead of `welcomeback`.
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export type WelcomeBackEvent = {
+  type: 'welcomeback'
+  listenerName: string
+}
+
+/**
+ * The listener can't be resumed or otherwise need to reset its local state
+ *
+ * If resumability is unavailable, even listeners created with `enableResume: true` may still
+ * emit `welcome` when reconnected. Subscribers should therefore treat `welcome` after a reconnect
+ * the same way they would otherwise treat a `reset` event.
+ *
+ * @public
+ */
+export type ResetEvent = {
+  type: 'reset'
+}
+
 /** @public */
-export type ListenEvent<R extends Record<string, Any>> =
+export type ListenEvent<R extends Record<string, Any> = Record<string, Any>> =
   | MutationEvent<R>
   | ReconnectEvent
+  | WelcomeBackEvent
+  | ResetEvent
   | WelcomeEvent
   | OpenEvent
 
@@ -1182,6 +1249,14 @@ export type ListenEventName =
    */
   | 'open'
 
+/** @public */
+export type ResumableListenEventNames =
+  | ListenEventName
+  /** The listener has reconnected and successfully resumed from where it left off */
+  | 'welcomeback'
+  /** The listener can't be resumed or otherwise need to reset its local state */
+  | 'reset'
+
 /** @public */
 export type ListenParams = {[key: string]: Any}
 
@@ -1233,7 +1308,7 @@ export interface ListenOptions {
 
   /**
    * Array of event names to include in the observable. By default, only mutation events are included.
-   *
+   * Note: `welcomeback` and `reset` events requires `enableResume: true`
    * @defaultValue `['mutation']`
    */
   events?: ListenEventName[]
@@ -1255,6 +1330,32 @@ export interface ListenOptions {
    * @defaultValue `undefined`
    */
   tag?: string
+
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * When if enabling this, you should also add the `reset` to the events array and handle the case where the backend is unable to resume.
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume?: boolean
+}
+
+/** @public */
+export interface ResumableListenOptions extends Omit<ListenOptions, 'events' | 'enableResume'> {
+  /**
+   * If this is enabled, the client will normally resume events upon reconnect
+   * Note that you should also subscribe to `reset`-events and handle the case where the backend is unable to resume
+   * @beta
+   * @defaultValue `false`
+   */
+  enableResume: true
+
+  /**
+   * Array of event names to include in the observable. By default, only mutation events are included.
+   *
+   * @defaultValue `['mutation']`
+   */
+  events?: ResumableListenEventNames[]
 }
 
 /** @public */

package/umd/sanityClient.js

@@ -3346,6 +3346,7 @@ ${selectionOpts}`);
     "includeAllVersions",
     "visibility",
     "effectFormat",
+    "enableResume",
     "tag"
   ], defaultOptions = {
     includeResult: true
@@ -3494,7 +3495,7 @@ ${selectionOpts}`);
      * Create a new dataset with the given name
      *
      * @param name - Name of the dataset to create
-     * @param options - Options for the dataset
+     * @param options - Options for the dataset, including optional embeddings configuration
      */
     create(name, options) {
       return _modify(this.#client, this.#httpRequest, "PUT", name, options);
@@ -3528,6 +3529,31 @@ ${selectionOpts}`);
         tag: null
       });
     }
+    /**
+     * Get embeddings settings for a dataset
+     *
+     * @param name - Name of the dataset
+     */
+    getEmbeddingsSettings(name) {
+      return resourceGuard("dataset", this.#client.config()), dataset(name), _request(this.#client, this.#httpRequest, {
+        uri: _embeddingsSettingsUri(this.#client, name),
+        tag: null
+      });
+    }
+    /**
+     * Edit embeddings settings for a dataset
+     *
+     * @param name - Name of the dataset
+     * @param settings - Embeddings settings to apply
+     */
+    editEmbeddingsSettings(name, settings) {
+      return resourceGuard("dataset", this.#client.config()), dataset(name), _request(this.#client, this.#httpRequest, {
+        method: "PUT",
+        uri: _embeddingsSettingsUri(this.#client, name),
+        body: settings,
+        tag: null
+      });
+    }
   }
   class DatasetsClient {
     #client;
@@ -3539,7 +3565,7 @@ ${selectionOpts}`);
      * Create a new dataset with the given name
      *
      * @param name - Name of the dataset to create
-     * @param options - Options for the dataset
+     * @param options - Options for the dataset, including optional embeddings configuration
      */
     create(name, options) {
       return resourceGuard("dataset", this.#client.config()), lastValueFrom(
@@ -3576,6 +3602,39 @@ ${selectionOpts}`);
         _request(this.#client, this.#httpRequest, { uri, tag: null })
       );
     }
+    /**
+     * Get embeddings settings for a dataset
+     *
+     * @param name - Name of the dataset
+     */
+    getEmbeddingsSettings(name) {
+      return resourceGuard("dataset", this.#client.config()), dataset(name), lastValueFrom(
+        _request(this.#client, this.#httpRequest, {
+          uri: _embeddingsSettingsUri(this.#client, name),
+          tag: null
+        })
+      );
+    }
+    /**
+     * Edit embeddings settings for a dataset
+     *
+     * @param name - Name of the dataset
+     * @param settings - Embeddings settings to apply
+     */
+    editEmbeddingsSettings(name, settings) {
+      return resourceGuard("dataset", this.#client.config()), dataset(name), lastValueFrom(
+        _request(this.#client, this.#httpRequest, {
+          method: "PUT",
+          uri: _embeddingsSettingsUri(this.#client, name),
+          body: settings,
+          tag: null
+        })
+      );
+    }
+  }
+  function _embeddingsSettingsUri(client, name) {
+    const config = client.config();
+    return config.useProjectHostname === false ? `/projects/${config.projectId}/datasets/${name}/settings/embeddings` : `/datasets/${name}/settings/embeddings`;
   }
   function _modify(client, httpRequest, method, name, options) {
     return resourceGuard("dataset", client.config()), dataset(name), _request(client, httpRequest, {