@sanity/client 7.4.0 → 7.5.0

package/dist/stega.browser.d.cts

@@ -1866,6 +1866,24 @@ export declare type IdentifiedSanityDocumentStub<
   _id: string
 } & SanityDocumentStub
 
+/**
+ *
+ * @see #TransformOperation
+ * @beta
+ */
+export declare interface ImageDescriptionOperation {
+  type: 'image-description'
+  /**
+   * When omitted, parent image value will be inferred from the arget path.
+   *
+   * When specified, the `sourcePath` should be a path to an image (or image asset) field:
+   * - `['image']`
+   * - `['wrapper', 'mainImage']`
+   * - `['heroImage', 'asset'] // the asset segment is optional, but supported`
+   */
+  sourcePath?: AgentActionPath
+}
+
 /** @public */
 export declare interface InitializedClientConfig extends ClientConfig {
   apiHost: string
@@ -5764,6 +5782,39 @@ declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
 declare type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
   TransformRequestBase & AgentActionSync
 
+/**
+ *
+ * ## `set` by default
+ * By default, Transform will change the value of every target field in place using a set operation.
+ *
+ * ## Image description
+ *
+ * ### Targeting image fields
+ * Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+ * with `operation: {type: 'image-description'}`.
+ *
+ * Custom instructions for image description targets will be used to generate the description.
+ *
+ * Such targets must be a descendant field of an image object.
+ *
+ * For example:
+ * - `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+ * - `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+ * - `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * ### Targeting non-image fields
+ * If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+ * `sourcePath` must be an image or image asset field.
+ *
+ * For example:
+ * - `target: {path: ['description'], operation: operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+ * - `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+ * - `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * @beta
+ */
+export declare type TransformOperation = 'set' | ImageDescriptionOperation
+
 /** @beta */
 declare interface TransformRequestBase extends AgentActionRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
@@ -5905,7 +5956,10 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
   target?: TransformTarget | TransformTarget[]
 }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
@@ -5921,6 +5975,11 @@ export declare interface TransformTarget extends AgentActionTarget {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /**
@@ -5946,7 +6005,10 @@ export declare type TransformTargetDocument =
       _id: string
     }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTargetInclude extends AgentActionTargetInclude {
   /**
    * Specifies a tailored instruction of this target.
@@ -5961,6 +6023,11 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /** @beta */

package/dist/stega.browser.d.ts

@@ -1866,6 +1866,24 @@ export declare type IdentifiedSanityDocumentStub<
   _id: string
 } & SanityDocumentStub
 
+/**
+ *
+ * @see #TransformOperation
+ * @beta
+ */
+export declare interface ImageDescriptionOperation {
+  type: 'image-description'
+  /**
+   * When omitted, parent image value will be inferred from the arget path.
+   *
+   * When specified, the `sourcePath` should be a path to an image (or image asset) field:
+   * - `['image']`
+   * - `['wrapper', 'mainImage']`
+   * - `['heroImage', 'asset'] // the asset segment is optional, but supported`
+   */
+  sourcePath?: AgentActionPath
+}
+
 /** @public */
 export declare interface InitializedClientConfig extends ClientConfig {
   apiHost: string
@@ -5764,6 +5782,39 @@ declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
 declare type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
   TransformRequestBase & AgentActionSync
 
+/**
+ *
+ * ## `set` by default
+ * By default, Transform will change the value of every target field in place using a set operation.
+ *
+ * ## Image description
+ *
+ * ### Targeting image fields
+ * Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+ * with `operation: {type: 'image-description'}`.
+ *
+ * Custom instructions for image description targets will be used to generate the description.
+ *
+ * Such targets must be a descendant field of an image object.
+ *
+ * For example:
+ * - `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+ * - `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+ * - `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * ### Targeting non-image fields
+ * If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+ * `sourcePath` must be an image or image asset field.
+ *
+ * For example:
+ * - `target: {path: ['description'], operation: operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+ * - `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+ * - `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * @beta
+ */
+export declare type TransformOperation = 'set' | ImageDescriptionOperation
+
 /** @beta */
 declare interface TransformRequestBase extends AgentActionRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
@@ -5905,7 +5956,10 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
   target?: TransformTarget | TransformTarget[]
 }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
@@ -5921,6 +5975,11 @@ export declare interface TransformTarget extends AgentActionTarget {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /**
@@ -5946,7 +6005,10 @@ export declare type TransformTargetDocument =
       _id: string
     }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTargetInclude extends AgentActionTargetInclude {
   /**
    * Specifies a tailored instruction of this target.
@@ -5961,6 +6023,11 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /** @beta */

package/dist/stega.d.cts

@@ -1866,6 +1866,24 @@ export declare type IdentifiedSanityDocumentStub<
   _id: string
 } & SanityDocumentStub
 
+/**
+ *
+ * @see #TransformOperation
+ * @beta
+ */
+export declare interface ImageDescriptionOperation {
+  type: 'image-description'
+  /**
+   * When omitted, parent image value will be inferred from the arget path.
+   *
+   * When specified, the `sourcePath` should be a path to an image (or image asset) field:
+   * - `['image']`
+   * - `['wrapper', 'mainImage']`
+   * - `['heroImage', 'asset'] // the asset segment is optional, but supported`
+   */
+  sourcePath?: AgentActionPath
+}
+
 /** @public */
 export declare interface InitializedClientConfig extends ClientConfig {
   apiHost: string
@@ -5764,6 +5782,39 @@ declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
 declare type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
   TransformRequestBase & AgentActionSync
 
+/**
+ *
+ * ## `set` by default
+ * By default, Transform will change the value of every target field in place using a set operation.
+ *
+ * ## Image description
+ *
+ * ### Targeting image fields
+ * Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+ * with `operation: {type: 'image-description'}`.
+ *
+ * Custom instructions for image description targets will be used to generate the description.
+ *
+ * Such targets must be a descendant field of an image object.
+ *
+ * For example:
+ * - `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+ * - `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+ * - `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * ### Targeting non-image fields
+ * If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+ * `sourcePath` must be an image or image asset field.
+ *
+ * For example:
+ * - `target: {path: ['description'], operation: operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+ * - `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+ * - `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * @beta
+ */
+export declare type TransformOperation = 'set' | ImageDescriptionOperation
+
 /** @beta */
 declare interface TransformRequestBase extends AgentActionRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
@@ -5905,7 +5956,10 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
   target?: TransformTarget | TransformTarget[]
 }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
@@ -5921,6 +5975,11 @@ export declare interface TransformTarget extends AgentActionTarget {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /**
@@ -5946,7 +6005,10 @@ export declare type TransformTargetDocument =
       _id: string
     }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTargetInclude extends AgentActionTargetInclude {
   /**
    * Specifies a tailored instruction of this target.
@@ -5961,6 +6023,11 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /** @beta */

package/dist/stega.d.ts

@@ -1866,6 +1866,24 @@ export declare type IdentifiedSanityDocumentStub<
   _id: string
 } & SanityDocumentStub
 
+/**
+ *
+ * @see #TransformOperation
+ * @beta
+ */
+export declare interface ImageDescriptionOperation {
+  type: 'image-description'
+  /**
+   * When omitted, parent image value will be inferred from the arget path.
+   *
+   * When specified, the `sourcePath` should be a path to an image (or image asset) field:
+   * - `['image']`
+   * - `['wrapper', 'mainImage']`
+   * - `['heroImage', 'asset'] // the asset segment is optional, but supported`
+   */
+  sourcePath?: AgentActionPath
+}
+
 /** @public */
 export declare interface InitializedClientConfig extends ClientConfig {
   apiHost: string
@@ -5764,6 +5782,39 @@ declare type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
 declare type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
   TransformRequestBase & AgentActionSync
 
+/**
+ *
+ * ## `set` by default
+ * By default, Transform will change the value of every target field in place using a set operation.
+ *
+ * ## Image description
+ *
+ * ### Targeting image fields
+ * Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+ * with `operation: {type: 'image-description'}`.
+ *
+ * Custom instructions for image description targets will be used to generate the description.
+ *
+ * Such targets must be a descendant field of an image object.
+ *
+ * For example:
+ * - `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+ * - `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+ * - `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * ### Targeting non-image fields
+ * If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+ * `sourcePath` must be an image or image asset field.
+ *
+ * For example:
+ * - `target: {path: ['description'], operation: operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+ * - `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+ * - `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * @beta
+ */
+export declare type TransformOperation = 'set' | ImageDescriptionOperation
+
 /** @beta */
 declare interface TransformRequestBase extends AgentActionRequestBase {
   /** schemaId as reported by sanity deploy / sanity schema store */
@@ -5905,7 +5956,10 @@ declare interface TransformRequestBase extends AgentActionRequestBase {
   target?: TransformTarget | TransformTarget[]
 }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
@@ -5921,6 +5975,11 @@ export declare interface TransformTarget extends AgentActionTarget {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /**
@@ -5946,7 +6005,10 @@ export declare type TransformTargetDocument =
       _id: string
     }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export declare interface TransformTargetInclude extends AgentActionTargetInclude {
   /**
    * Specifies a tailored instruction of this target.
@@ -5961,6 +6023,11 @@ export declare interface TransformTargetInclude extends AgentActionTargetInclude
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /** @beta */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/client",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "Client for retrieving, creating and patching data from Sanity.io",
   "keywords": [
     "sanity",
@@ -164,7 +164,7 @@
     "typescript": "5.8.3",
     "vitest": "3.1.1"
   },
-  "packageManager": "npm@11.3.0",
+  "packageManager": "npm@11.4.1",
   "engines": {
     "node": ">=20"
   }

package/src/agent/actions/transform.ts

@@ -2,7 +2,13 @@ import {type Observable} from 'rxjs'
 
 import {_request} from '../../data/dataMethods'
 import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
-import type {AgentActionParams, Any, HttpRequest, IdentifiedSanityDocumentStub} from '../../types'
+import type {
+  AgentActionParams,
+  AgentActionPath,
+  Any,
+  HttpRequest,
+  IdentifiedSanityDocumentStub,
+} from '../../types'
 import {hasDataset} from '../../validators'
 import type {
   AgentActionAsync,
@@ -169,7 +175,61 @@ export type TransformTargetDocument =
   | {operation: 'createIfNotExists'; _id: string}
   | {operation: 'createOrReplace'; _id: string}
 
-/**  @beta */
+/**
+ *
+ * @see #TransformOperation
+ * @beta
+ */
+export interface ImageDescriptionOperation {
+  type: 'image-description'
+  /**
+   * When omitted, parent image value will be inferred from the arget path.
+   *
+   * When specified, the `sourcePath` should be a path to an image (or image asset) field:
+   * - `['image']`
+   * - `['wrapper', 'mainImage']`
+   * - `['heroImage', 'asset'] // the asset segment is optional, but supported`
+   */
+  sourcePath?: AgentActionPath
+}
+
+/**
+ *
+ * ## `set` by default
+ * By default, Transform will change the value of every target field in place using a set operation.
+ *
+ * ## Image description
+ *
+ * ### Targeting image fields
+ * Images can be transformed to a textual description by targeting a `string`, `text` or Portable Text field (`array` with `block`)
+ * with `operation: {type: 'image-description'}`.
+ *
+ * Custom instructions for image description targets will be used to generate the description.
+ *
+ * Such targets must be a descendant field of an image object.
+ *
+ * For example:
+ * - `target: {path: ['image', 'description'], operation: {type: 'image-description'} }`
+ * - `target: {path: ['array', {_key: 'abc'}, 'alt'], operation: {type: 'image-description'} } //assuming the item in the array on the key-ed path is an image`
+ * - `target: {path: ['image'], include: ['portableTextField'], operation: {type: 'image-description'}, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * ### Targeting non-image fields
+ * If the target image description lives outside an image object, use the `sourcePath` option to specify the path to the image field.
+ * `sourcePath` must be an image or image asset field.
+ *
+ * For example:
+ * - `target: {path: ['description'], operation: operation: {type: 'image-description', sourcePath: ['image', 'asset'] }`
+ * - `target: {path: ['wrapper', 'title'], operation: {type: 'image-description', sourcePath: ['array', {_key: 'abc'}, 'image'] }`
+ * - `target: {path: ['wrapper'], include: ['portableTextField'], operation: {type: 'image-description', sourcePath: ['image', 'asset'] }, instruction: 'Use formatting and headings to describe the image in great detail' }`
+ *
+ * @beta
+ */
+export type TransformOperation = 'set' | ImageDescriptionOperation
+
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export interface TransformTargetInclude extends AgentActionTargetInclude {
   /**
    * Specifies a tailored instruction of this target.
@@ -185,9 +245,18 @@ export interface TransformTargetInclude extends AgentActionTargetInclude {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
-/**  @beta */
+/**
+ * @see #TransformOperation
+ * @beta
+ * */
 export interface TransformTarget extends AgentActionTarget {
   /**
    * Specifies a tailored instruction of this target.
@@ -204,6 +273,12 @@ export interface TransformTarget extends AgentActionTarget {
    * Fields or array items not on the include list, are implicitly excluded.
    */
   include?: (AgentActionPathSegment | TransformTargetInclude)[]
+
+  /**
+   * Default: `set`
+   * @see #TransformOperation
+   */
+  operation?: TransformOperation
 }
 
 /** @beta */

package/src/data/encodeQueryString.ts

@@ -18,7 +18,7 @@ export const encodeQueryString = ({
 
   // Iterate params, the keys are prefixed with `$` and their values JSON stringified
   for (const [key, value] of Object.entries(params)) {
-    searchParams.append(`$${key}`, JSON.stringify(value))
+    if (value !== undefined) searchParams.append(`$${key}`, JSON.stringify(value))
   }
   // Options are passed as-is
   for (const [key, value] of Object.entries(opts)) {

package/src/types.ts

@@ -1635,7 +1635,9 @@ export type {
 export type {PatchDocument, PatchOperation, PatchTarget} from './agent/actions/patch'
 export type {PromptRequest} from './agent/actions/prompt'
 export type {
+  ImageDescriptionOperation,
   TransformDocument,
+  TransformOperation,
   TransformTarget,
   TransformTargetDocument,
   TransformTargetInclude,

package/umd/sanityClient.js

@@ -2813,7 +2813,7 @@ ${selectionOpts}`);
     const searchParams = new URLSearchParams(), { tag, includeMutations, returnQuery, ...opts } = options;
     tag && searchParams.append("tag", tag), searchParams.append("query", query);
     for (const [key, value] of Object.entries(params))
-      searchParams.append(`$${key}`, JSON.stringify(value));
+      value !== void 0 && searchParams.append(`$${key}`, JSON.stringify(value));
     for (const [key, value] of Object.entries(opts))
       value && searchParams.append(key, `${value}`);
     return returnQuery === false && searchParams.append("returnQuery", "false"), includeMutations === false && searchParams.append("includeMutations", "false"), `?${searchParams}`;