@cloudinary/asset-management-mcp 0.9.0-rc.0 → 0.9.1

package/src/models/uploadrequest.ts

@@ -9,74 +9,50 @@ import {
   AccessControlItem,
   AccessControlItem$zodSchema,
 } from "./accesscontrolitem.js";
+import {
+  ResponsiveBreakpoint,
+  ResponsiveBreakpoint$zodSchema,
+} from "./responsivebreakpoint.js";
+import {
+  StructuredMetadataParam,
+  StructuredMetadataParam$zodSchema,
+} from "./structuredmetadataparam.js";
+import { TagsParam, TagsParam$zodSchema } from "./tagsparam.js";
+import {
+  UploadDeliveryType,
+  UploadDeliveryType$zodSchema,
+} from "./uploaddeliverytype.js";
 
 /**
  * Configuration object for automatic video transcription with translation options.
  */
-export type AutoTranscription = { translate?: Array<string> | undefined };
+export type UploadRequestAutoTranscription = {
+  translate?: Array<string> | undefined;
+};
 
-export const AutoTranscription$zodSchema: z.ZodType<AutoTranscription> = z
-  .object({
-    translate: z.array(z.string()).optional().describe(
-      "Array of target language codes for transcription translation.",
-    ),
-  }).describe(
-    "Configuration object for automatic video transcription with translation options.",
-  );
+export const UploadRequestAutoTranscription$zodSchema: z.ZodType<
+  UploadRequestAutoTranscription
+> = z.object({
+  translate: z.array(z.string()).optional().describe(
+    "Array of target language codes for transcription translation.",
+  ),
+}).describe(
+  "Configuration object for automatic video transcription with translation options.",
+);
 
-export type AutoTranscriptionUnion = boolean | AutoTranscription;
+export type UploadRequestAutoTranscriptionUnion =
+  | boolean
+  | UploadRequestAutoTranscription;
 
-export const AutoTranscriptionUnion$zodSchema: z.ZodType<
-  AutoTranscriptionUnion
+export const UploadRequestAutoTranscriptionUnion$zodSchema: z.ZodType<
+  UploadRequestAutoTranscriptionUnion
 > = z.union([
   z.boolean(),
-  z.lazy(() => AutoTranscription$zodSchema),
+  z.lazy(() => UploadRequestAutoTranscription$zodSchema),
 ]);
 
-export type ResponsiveBreakpoint = {
-  create_derived?: boolean | undefined;
-  max_width?: number | undefined;
-  min_width?: number | undefined;
-  bytes_step?: number | undefined;
-  max_images?: number | undefined;
-  transformation?: string | undefined;
-};
-
-export const ResponsiveBreakpoint$zodSchema: z.ZodType<ResponsiveBreakpoint> = z
-  .object({
-    bytes_step: z.int().optional(),
-    create_derived: z.boolean().optional(),
-    max_images: z.int().optional(),
-    max_width: z.int().optional(),
-    min_width: z.int().optional(),
-    transformation: z.string().optional(),
-  });
-
-/**
- * The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload). Possible values are upload, authenticated, private or asset.
- */
-export const UploadRequestType = {
-  Upload: "upload",
-  Authenticated: "authenticated",
-  Private: "private",
-  Asset: "asset",
-} as const;
 /**
- * The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload). Possible values are upload, authenticated, private or asset.
- */
-export type UploadRequestType = ClosedEnum<typeof UploadRequestType>;
-
-export const UploadRequestType$zodSchema = z.enum([
-  "upload",
-  "authenticated",
-  "private",
-  "asset",
-]).describe(
-  "The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload). Possible values are upload, authenticated, private or asset.",
-);
-
-/**
- * Allows the asset to behave as if it's of the authenticated 'type' (see above) while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs. Valid values: public, and authenticated.
+ * Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.
  *
  * @remarks
  *
@@ -87,7 +63,7 @@ export const UploadRequestAccessMode = {
   Authenticated: "authenticated",
 } as const;
 /**
- * Allows the asset to behave as if it's of the authenticated 'type' (see above) while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs. Valid values: public, and authenticated.
+ * Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.
  *
  * @remarks
  *
@@ -101,70 +77,109 @@ export const UploadRequestAccessMode$zodSchema = z.enum([
   "public",
   "authenticated",
 ]).describe(
-  "Allows the asset to behave as if it's of the authenticated 'type' (see above) while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs. Valid values: public, and authenticated.\n",
+  "Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.\n",
+);
+
+/**
+ * Named region coordinate groups for cropping with region gravity.
+ *
+ * @remarks
+ * Can be a JSON-encoded string or an object. Each region name may contain
+ * only letters, numbers, or hyphens, and must have at least two coordinate pairs.
+ */
+export type UploadRequestRegions = string | {
+  [k: string]: Array<Array<number>>;
+};
+
+export const UploadRequestRegions$zodSchema: z.ZodType<UploadRequestRegions> = z
+  .union([
+    z.string(),
+    z.record(z.string(), z.array(z.array(z.int()))),
+  ]).describe(
+    "Named region coordinate groups for cropping with region gravity.\nCan be a JSON-encoded string or an object. Each region name may contain\nonly letters, numbers, or hyphens, and must have at least two coordinate pairs.\n",
+  );
+
+/**
+ * Settings to automatically generate breakpoints for responsive images.
+ */
+export type UploadRequestResponsiveBreakpoints =
+  | Array<ResponsiveBreakpoint>
+  | ResponsiveBreakpoint;
+
+export const UploadRequestResponsiveBreakpoints$zodSchema: z.ZodType<
+  UploadRequestResponsiveBreakpoints
+> = z.union([
+  z.array(ResponsiveBreakpoint$zodSchema),
+  ResponsiveBreakpoint$zodSchema,
+]).describe(
+  "Settings to automatically generate breakpoints for responsive images.",
 );
 
+/**
+ * Parameters for configuring asset uploads, including transformation, tagging, metadata, and delivery options.
+ */
 export type UploadRequest = {
-  api_key?: string | undefined;
-  timestamp?: number | undefined;
-  signature?: string | undefined;
   accessibility_analysis?: boolean | undefined;
   asset_folder?: string | undefined;
   async?: boolean | undefined;
   auto_chaptering?: boolean | undefined;
-  auto_transcription?: boolean | AutoTranscription | undefined;
+  auto_tagging?: number | undefined;
+  auto_transcription?: boolean | UploadRequestAutoTranscription | undefined;
+  access_control?: Array<AccessControlItem> | undefined;
+  access_mode?: UploadRequestAccessMode | undefined;
+  backup?: boolean | undefined;
+  background_removal?: string | undefined;
+  callback?: string | undefined;
+  categorization?: string | undefined;
   cinemagraph_analysis?: boolean | undefined;
   colors?: boolean | undefined;
-  context?: string | undefined;
-  custom_coordinates?: string | undefined;
+  detection?: string | undefined;
+  discard_original_filename?: boolean | undefined;
   display_name?: string | undefined;
-  eager?: string | undefined;
   eager_async?: boolean | undefined;
   eager_notification_url?: string | undefined;
-  face_coordinates?: string | undefined;
+  eval?: string | undefined;
   faces?: boolean | undefined;
-  headers?: string | undefined;
+  filename_override?: string | undefined;
+  folder?: string | undefined;
+  format?: string | undefined;
   invalidate?: boolean | undefined;
   media_metadata?: boolean | undefined;
-  metadata?: string | undefined;
+  metadata?: StructuredMetadataParam | undefined;
+  clear_invalid?: boolean | undefined;
   moderation?: string | undefined;
   notification_url?: string | undefined;
-  phash?: boolean | undefined;
-  quality_analysis?: boolean | undefined;
-  regions?: string | undefined;
-  responsive_breakpoints?: Array<ResponsiveBreakpoint> | undefined;
-  tags?: string | undefined;
-  callback?: string | undefined;
-  backup?: boolean | undefined;
-  discard_original_filename?: boolean | undefined;
-  overwrite?: boolean | undefined;
-  return_delete_token?: boolean | undefined;
-  type?: UploadRequestType | undefined;
-  access_mode?: UploadRequestAccessMode | undefined;
-  categorization?: string | undefined;
   ocr?: string | undefined;
-  raw_convert?: string | undefined;
-  background_removal?: string | undefined;
-  public_id?: string | undefined;
-  transformation?: string | undefined;
-  format?: string | undefined;
+  on_success?: string | undefined;
+  overwrite?: boolean | undefined;
+  phash?: boolean | undefined;
   proxy?: string | undefined;
-  folder?: string | undefined;
-  allowed_formats?: string | undefined;
-  auto_tagging?: number | undefined;
-  access_control?: Array<AccessControlItem> | undefined;
-  eval?: string | undefined;
-  detection?: string | undefined;
-  filename_override?: string | undefined;
+  public_id?: string | undefined;
   public_id_prefix?: string | undefined;
+  quality_analysis?: boolean | undefined;
+  raw_convert?: string | undefined;
+  regions?: string | { [k: string]: Array<Array<number>> } | undefined;
+  responsive_breakpoints?:
+    | Array<ResponsiveBreakpoint>
+    | ResponsiveBreakpoint
+    | undefined;
+  return_delete_token?: boolean | undefined;
+  upload_preset?: string | undefined;
   use_asset_folder_as_public_id_prefix?: boolean | undefined;
-  unique_display_name?: boolean | undefined;
-  visual_search?: boolean | undefined;
-  use_filename_as_display_name?: boolean | undefined;
   use_filename?: boolean | undefined;
+  use_filename_as_display_name?: boolean | undefined;
+  unique_display_name?: boolean | undefined;
   unique_filename?: boolean | undefined;
-  upload_preset?: string | undefined;
-  on_success?: string | undefined;
+  visual_search?: boolean | undefined;
+  tags?: TagsParam | undefined;
+  context?: string | undefined;
+  eager?: string | undefined;
+  transformation?: string | undefined;
+  allowed_formats?: string | undefined;
+  headers?: string | undefined;
+  face_coordinates?: string | undefined;
+  custom_coordinates?: string | undefined;
+  type?: UploadDeliveryType | undefined;
   file: string;
 };
 
@@ -173,16 +188,13 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
     "Restricts access to the asset by specifying one or more access types.\nThe asset is restricted unless at least one listed access type is valid.\n",
   ),
   access_mode: UploadRequestAccessMode$zodSchema.optional().describe(
-    "Allows the asset to behave as if it's of the authenticated 'type' (see above) while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs. Valid values: public, and authenticated.\n",
+    "Deprecated. Use access_control instead. Allows the asset to behave as if it's of the authenticated delivery type while still using the default 'upload' type in delivery URLs. The asset can later be made public by changing its access_mode via the Admin API, without having to update any delivery URLs.\n",
   ),
   accessibility_analysis: z.boolean().optional().describe(
-    "Whether to return return accessibility analysis values for the image.",
+    "Whether to return accessibility analysis values for the image.",
   ),
   allowed_formats: z.string().optional().describe(
-    "A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions.\nNote: You can also add the `format` parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload wont be converted.\n",
-  ),
-  api_key: z.string().optional().describe(
-    "The API key to use for the request. This is automatically computed by the Cloudinary's SDKs.",
+    "A comma-separated list of file formats that are allowed for uploading. Files of other types will be rejected. The formats can be any combination of image types, video formats or raw file extensions.\nNote: You can also add the `format` parameter to convert other file types instead of rejecting them. In this case, only files that would normally be rejected are converted, any file format allowed for upload won't be converted.\n",
   ),
   asset_folder: z.string().optional().describe(
     "The asset folder to assign to the asset.",
@@ -198,7 +210,7 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
   ),
   auto_transcription: z.union([
     z.boolean(),
-    z.lazy(() => AutoTranscription$zodSchema),
+    z.lazy(() => UploadRequestAutoTranscription$zodSchema),
   ]).optional(),
   background_removal: z.string().optional().describe(
     "Automatically remove the background of an image using an add-on.\n- Set to cloudinary_ai to use the deep-learning based Cloudinary AI Background Removal add-on.\n  Optionally append a template suffix (e.g., cloudinary_ai:fine_edges).\n- Note: this feature has been superseded by background removal on the fly.\n- Set to pixelz to use the human-powered Pixelz Remove-The-Background Editing add-on service.\nRelevant for images only.\n",
@@ -215,14 +227,17 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
   cinemagraph_analysis: z.boolean().optional().describe(
     "Whether to return a cinemagraph analysis value for the media asset between 0 and 1, where 0 means the asset is not a cinemagraph and 1 means the asset is a cinemagraph. Relevant for animated images and video only. A static image will return 0.",
   ),
+  clear_invalid: z.boolean().default(false).describe(
+    "Whether to clear metadata field values that have become invalid due to a change in metadata rules. If false, the API returns an error if any existing metadata value is no longer valid. Default: false.",
+  ),
   colors: z.boolean().default(false).describe(
     "Whether to retrieve predominant colors & color histogram of the uploaded image. Note: If all returned colors are opaque, then 6-digit RGB hex values are returned. If one or more colors contain an alpha channel, then 8-digit RGBA hex quadruplet values are returned.",
   ),
   context: z.string().optional().describe(
-    "Key-value pairs of general textual context metadata to attach to the asset.",
+    "A pipe-separated list of key-value pairs of general textual context metadata to attach to the asset (e.g., \"alt=My image|caption=Nice photo\"). The =, \", and | characters can be escaped with a prepending backslash (\\).",
   ),
   custom_coordinates: z.string().optional().describe(
-    "An array of coordinates for custom cropping.",
+    "Custom coordinates as comma-separated values, with multiple coordinates separated by pipes.",
   ),
   detection: z.string().optional().describe(
     "Invokes the relevant add-on to return a list of detected content.\nSet to:\n- <content-aware model>_[<version>] (e.g. coco_v2) to return a list of detected content using the Cloudinary AI Content Analysis add-on. Can be used together with the auto_tagging parameter to apply tags automatically.\n- captioning to analyze an image and suggest a caption based on the image's contents.\n- iqa to analyze the quality of an image.\n- watermark-detection to detect watermarks in an image.\n- adv_face to return a list of facial attributes using the Advanced Facial Attribute Detection add-on.\n- aws_rek_face to return a list of detected celebrities and facial attributes using the Amazon Rekognition Celebrity Detection add-on. Can be used together with the auto_tagging parameter to apply tags automatically.\n",
@@ -244,7 +259,7 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
     "Allows you to modify upload parameters by specifying custom logic with JavaScript. This can be useful for conditionally adding tags, contextual metadata, structured metadata or eager transformations depending on specific criteria of the uploaded file.",
   ),
   face_coordinates: z.string().optional().describe(
-    "An array of coordinates representing detected faces in the asset, used for custom cropping or overlays.",
+    "Face coordinates as comma-separated values, with multiple faces separated by pipes.",
   ),
   faces: z.boolean().optional().describe(
     "Whether to detect faces in the asset.",
@@ -270,8 +285,8 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
   media_metadata: z.boolean().optional().describe(
     "Whether to return IPTC, XMP, and detailed Exif metadata of the uploaded asset in the response.\nSupported for images, video, and audio.\n- Returned metadata for images includes: PixelsPerUnitX, PixelsPerUnitY, PixelUnits, Colorspace, and DPI.\n- Returned metadata for audio and video includes: audio_codec, audio_bit_rate, audio_frequency, channels, channel_layout.\n- Additional metadata for video includes: pix_format, codec, level, profile, video_bit_rate, dar.\n",
   ),
-  metadata: z.string().optional().describe(
-    "Structured metadata to attach to the asset based on the metadata fields defined for your account.",
+  metadata: StructuredMetadataParam$zodSchema.optional().describe(
+    "A pipe-separated list or a map of custom metadata fields (by external_id) and the values to assign to each of them. The = \" and | characters can be supported as values when escaped with a prepended backslash (\\). For a multi-select field, you can set a maximum of 3000 different metadata values on an asset.\n",
   ),
   moderation: z.string().optional().describe(
     "For all asset types, set to:\n- manual to add the uploaded asset to a list of pending assets that can be moderated using the Admin API or the Cloudinary Console.\n- perception_point to automatically moderate the uploaded asset using the Perception Point Malware Detection add-on.\n\nFor images only, set to:\n- webpurify to automatically moderate the uploaded image using the WebPurify Image Moderation add-on.\n- aws_rek to automatically moderate the uploaded image using the Amazon Rekognition AI Moderation add-on.\n- duplicate:<threshold> to detect if the same or a similar image already exists using the Cloudinary Duplicate Image Detection add-on. Set threshold to a float greater than 0 and less than or equal to 1.0 to specify how similar an image needs to be in order to be considered a duplicate. Set threshold to 0 to add an image to the index of images that are searched when duplicate detection is invoked for another image.\n\nFor videos only, set to:\n- aws_rek_video to automatically moderate the uploaded video using the Amazon Rekognition Video Moderation add-on.\n- google_video_moderation automatically moderate the uploaded video using the Google AI Video Moderation add-on.\n\nTo request multiple moderations in a single API call:\n- Send the desired list of moderations as a pipe-separated string with manual moderation, if relevant, being last.\n\nNote: Rejected assets are automatically invalidated on the CDN within approximately ten minutes.\n",
@@ -306,28 +321,29 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
   raw_convert: z.string().optional().describe(
     "Generates a related file based on the uploaded file.\n- Set to aspose to automatically create a PDF or other image format from a raw Office document using the Aspose Document Conversion add-on. (Asynchronous)\n- Set to google_speech to instruct the Google AI Video Transcription add-on to generate an automatic transcript raw file from an uploaded video. (Asynchronous)\n- Set to extract_text to extract all the text from a PDF file and store it in a raw JSON file with a public ID in the format: [pdf_public_id].extract_text.json. The full URL of the generated JSON file is included in the API response. Unlike the above raw_convert options, this option doesn't require registering for an add-on.(Synchronous)\n- Set to azure_video_indexer to generate AI-powered video insights from Microsoft Azure. (Asynchronous)\n",
   ),
-  regions: z.string().optional().describe("Regions to detect in the asset."),
-  responsive_breakpoints: z.array(z.lazy(() => ResponsiveBreakpoint$zodSchema))
-    .optional().describe(
-      "Settings to automatically generate breakpoints for responsive images.",
-    ),
-  return_delete_token: z.boolean().optional().describe(
-    "Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within approximately 10 minutes using an unauthenticated API call.",
+  regions: z.union([
+    z.string(),
+    z.record(z.string(), z.array(z.array(z.int()))),
+  ]).optional().describe(
+    "Named region coordinate groups for cropping with region gravity.\nCan be a JSON-encoded string or an object. Each region name may contain\nonly letters, numbers, or hyphens, and must have at least two coordinate pairs.\n",
   ),
-  signature: z.string().optional().describe(
-    "(Required for signed REST API calls) Used to authenticate the request and based on the parameters you use in the request. When using the Cloudinary SDKs for signed requests, the signature is automatically generated and added to the request. If you manually generate your own signed POST request, you need to manually generate the signature parameter and add it to the request together with the api_key and timestamp parameters.\n",
+  responsive_breakpoints: z.union([
+    z.array(ResponsiveBreakpoint$zodSchema),
+    ResponsiveBreakpoint$zodSchema,
+  ]).optional().describe(
+    "Settings to automatically generate breakpoints for responsive images.",
   ),
-  tags: z.string().optional().describe(
-    "A comma-separated list of tag names to assign to the asset.",
+  return_delete_token: z.boolean().optional().describe(
+    "Whether to return a deletion token in the upload response. The token can be used to delete the uploaded asset within approximately 10 minutes using an unauthenticated API call.",
   ),
-  timestamp: z.int().optional().describe(
-    "The timestamp to use for the request in unix time. This is automatically computed by the Cloudinary's SDKs.",
+  tags: TagsParam$zodSchema.optional().describe(
+    "A comma-separated list of tag names, or an array of tag names.",
   ),
   transformation: z.string().optional().describe(
     "An incoming transformation to run on the uploaded asset before its storage. In contrast to eager, this parameter is applied before the file is stored.",
   ),
-  type: UploadRequestType$zodSchema.optional().describe(
-    "The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload). Possible values are upload, authenticated, private or asset.",
+  type: UploadDeliveryType$zodSchema.optional().describe(
+    "The delivery type that defines if and how the uploaded asset is available for public delivery. By default, all uploaded assets are public (upload).",
   ),
   unique_display_name: z.boolean().optional().describe(
     "Whether the display name should be unique.",
@@ -350,4 +366,6 @@ export const UploadRequest$zodSchema: z.ZodType<UploadRequest> = z.object({
   visual_search: z.boolean().optional().describe(
     "Whether to index the image for use with visual searches. Relevant for images only.",
   ),
-});
+}).describe(
+  "Parameters for configuring asset uploads, including transformation, tagging, metadata, and delivery options.",
+);

package/src/models/uploadresponse.ts

@@ -4,6 +4,14 @@
  */
 
 import * as z from "zod";
+import {
+  ContextFullResponse,
+  ContextFullResponse$zodSchema,
+} from "./contextfullresponse.js";
+import {
+  CoordinatesResponse,
+  CoordinatesResponse$zodSchema,
+} from "./coordinatesresponse.js";
 
 /**
  * The image metadata of the uploaded file.
@@ -47,7 +55,9 @@ export type UploadResponse = {
   format?: string | undefined;
   resource_type?: string | undefined;
   created_at?: string | undefined;
-  tags?: Array<string> | undefined;
+  tags?: Array<string> | null | undefined;
+  context?: ContextFullResponse | null | undefined;
+  metadata?: { [k: string]: any } | undefined;
   pages?: number | undefined;
   bytes?: number | undefined;
   type?: string | undefined;
@@ -58,7 +68,11 @@ export type UploadResponse = {
   illustration_score?: number | undefined;
   semi_transparent?: boolean | undefined;
   grayscale?: boolean | undefined;
+  faces?: Array<Array<number>> | null | undefined;
+  coordinates?: CoordinatesResponse | null | undefined;
   eager?: Array<Eager> | undefined;
+  asset_folder?: string | null | undefined;
+  display_name?: string | undefined;
   api_key?: string | undefined;
 };
 
@@ -66,15 +80,30 @@ export const UploadResponse$zodSchema: z.ZodType<UploadResponse> = z.object({
   api_key: z.string().optional().describe(
     "The API key used to upload the file.",
   ),
+  asset_folder: z.string().nullable().optional().describe(
+    "The asset folder where the file is stored.",
+  ),
   asset_id: z.string().optional().describe(
-    "The asset ID of the uploaded file. This is the ID of the uploaded file in the Cloudinary database.",
+    "A 32-character hexadecimal asset ID.",
   ),
   bytes: z.int().optional().describe("The size of the uploaded file in bytes."),
-  created_at: z.string().optional().describe(
+  context: ContextFullResponse$zodSchema.nullable().optional().describe(
+    "Contextual metadata grouped by kind. Custom user context appears under the 'custom' key. Other context kinds may also appear as additional keys.",
+  ),
+  coordinates: CoordinatesResponse$zodSchema.nullable().optional().describe(
+    "Coordinate data for faces and custom regions.",
+  ),
+  created_at: z.iso.datetime({ offset: true }).optional().describe(
     "The date and time the file was uploaded.",
   ),
+  display_name: z.string().optional().describe(
+    "The display name of the uploaded file.",
+  ),
   eager: z.array(z.lazy(() => Eager$zodSchema)).optional(),
   etag: z.string().optional().describe("The ETag of the uploaded file."),
+  faces: z.array(z.array(z.int())).nullable().optional().describe(
+    "Detected face coordinate rectangles [x, y, width, height].",
+  ),
   format: z.string().optional().describe("The format of the uploaded file."),
   grayscale: z.boolean().optional().describe(
     "Whether the uploaded file is grayscale.",
@@ -85,6 +114,9 @@ export const UploadResponse$zodSchema: z.ZodType<UploadResponse> = z.object({
   ),
   image_metadata: z.lazy(() => UploadResponseImageMetadata$zodSchema).optional()
     .describe("The image metadata of the uploaded file."),
+  metadata: z.record(z.string(), z.any()).optional().describe(
+    "Structured metadata associated with the uploaded file.",
+  ),
   original_filename: z.string().optional().describe(
     "The original filename of the uploaded file.",
   ),
@@ -109,14 +141,14 @@ export const UploadResponse$zodSchema: z.ZodType<UploadResponse> = z.object({
   signature: z.string().optional().describe(
     "The signature of the uploaded file.",
   ),
-  tags: z.array(z.string()).optional().describe(
-    "The tags of the uploaded file.",
+  tags: z.array(z.string()).nullable().optional().describe(
+    "Tag names assigned to the asset.",
   ),
   type: z.string().optional().describe("The type of the uploaded file."),
   url: z.string().optional().describe("The URL of the uploaded file."),
   version: z.int().optional().describe("The version of the uploaded file."),
   version_id: z.string().optional().describe(
-    "The version ID of the uploaded file.",
+    "Hexadecimal version ID; length is a positive multiple of 32 (typically 32 or 64).",
   ),
   width: z.int().optional().describe("The width of the uploaded file."),
 });

package/src/models/videoview.ts

@@ -0,0 +1,48 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 764f09dd1b96
+ */
+
+import * as z from "zod";
+
+export type VideoView = {
+  video_public_id?: string | undefined;
+  video_duration?: number | null | undefined;
+  video_transformation?: string | null | undefined;
+  video_extension?: string | null | undefined;
+  viewer_application_name?: string | null | undefined;
+  viewer_location_country_code?: string | null | undefined;
+  viewer_os_identifier?: string | null | undefined;
+  view_watch_time?: number | null | undefined;
+  view_ended_at?: string | undefined;
+};
+
+export const VideoView$zodSchema: z.ZodType<VideoView> = z.object({
+  video_duration: z.number().nullable().optional().describe(
+    "The duration in seconds of the video.",
+  ),
+  video_extension: z.string().nullable().optional().describe(
+    "The file extension of the video.",
+  ),
+  video_public_id: z.string().optional().describe(
+    "The full public ID of the video.",
+  ),
+  video_transformation: z.string().nullable().optional().describe(
+    "The transformation applied to the video.",
+  ),
+  view_ended_at: z.iso.datetime({ offset: true }).optional().describe(
+    "The date when the video view ended.",
+  ),
+  view_watch_time: z.number().nullable().optional().describe(
+    "The length of time the video was viewed.",
+  ),
+  viewer_application_name: z.string().nullable().optional().describe(
+    "The application used to view the video.",
+  ),
+  viewer_location_country_code: z.string().nullable().optional().describe(
+    "The 2-digit ISO country code of the viewer location.",
+  ),
+  viewer_os_identifier: z.string().nullable().optional().describe(
+    "The full identifier for the viewer's operating system.",
+  ),
+});

package/src/models/videoviewsresponse.ts

@@ -0,0 +1,22 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: 6e6558f619e6
+ */
+
+import * as z from "zod";
+import { VideoView, VideoView$zodSchema } from "./videoview.js";
+
+export type VideoViewsResponse = {
+  request_id?: string | undefined;
+  next_cursor?: string | undefined;
+  data?: Array<VideoView> | undefined;
+};
+
+export const VideoViewsResponse$zodSchema: z.ZodType<VideoViewsResponse> = z
+  .object({
+    data: z.array(VideoView$zodSchema).optional(),
+    next_cursor: z.string().optional().describe("Cursor value for pagination."),
+    request_id: z.string().optional().describe(
+      "Unique identifier for the request.",
+    ),
+  });

package/src/tool-names.ts

@@ -18,19 +18,19 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "delete-asset",
-    "description": "Delete asset by asset-id\n\nDeletes an asset using its asset ID. This endpoint replaces the legacy /resources/by_asset_id endpoint.\nReturns the deletion status and asset folder information when folder decoupling is enabled.\n"
+    "description": "Delete asset by asset ID\n\nDeletes an asset using its immutable asset ID.\n"
   },
   {
     "name": "list-images",
-    "description": "Get image assets\n\nRetrieves a list of image assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+    "description": "Get image assets\n\nRetrieves a list of image assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.\n"
   },
   {
     "name": "list-videos",
-    "description": "Get video assets\n\nRetrieves a list of video assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+    "description": "Get video assets\n\nRetrieves a list of video assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.\n"
   },
   {
     "name": "list-files",
-    "description": "Get raw assets\n\nRetrieves a list of raw assets. Results can be filtered by various criteria like tags, moderation status, prefix, or specific public IDs.\n"
+    "description": "Get raw assets\n\nRetrieves a list of raw assets. Results can be filtered by various criteria like tags, prefix, or specific public IDs.\n"
   },
   {
     "name": "get-asset-details",
@@ -38,7 +38,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "asset-update",
-    "description": "Updates an existing asset's metadata, tags, and other attributes using its asset ID\n\nUpdates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. Note that you can also update many attributes of an existing asset using the explicit method, which is not rate-limited.\n"
+    "description": "Updates an existing asset's metadata, tags, and other attributes using its asset ID\n\nUpdates one or more attributes of a specified resource (asset) by its asset ID. This enables you to update details of an asset by its unique and immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. Note that you can also update attributes of an existing asset using the explicit API endpoint.\n"
   },
   {
     "name": "list-tags",
@@ -54,11 +54,11 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "create-asset-relations",
-    "description": "Add related assets by asset ID\n\nRelates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other."
+    "description": "Add related assets by asset ID\n\nRelates an asset to other assets by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be added as a related_asset to all the other assets specified. The relation is also a one to many relationship, where the asset is related to all the assets specified, but those assets aren't also related to each other."
   },
   {
     "name": "delete-asset-relations",
-    "description": "Delete asset relations by asset ID\n\nUnrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or deliver type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified."
+    "description": "Delete asset relations by asset ID\n\nUnrelates the asset from other assets, specified by their asset IDs, an immutable identifier, regardless of public ID, display name, asset folder, resource type or delivery type. This is a bidirectional process, meaning that the asset will also be removed as a related_asset from all the other assets specified."
   },
   {
     "name": "move-folder",
@@ -78,11 +78,11 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "search-assets",
-    "description": "Provides a powerful query interface to filter and retrieve assets and their details\n\nReturns a list of resources matching the specified search criteria.\n\nUses Lucene-like query language to search by descriptive attributes (public_id, filename, folder, tags, context), file details (resource_type, format, bytes, width, height), embedded data (image_metadata), and analyzed data (face_count, colors, quality_score). Supports aggregate counts and complex Boolean expressions.\n\nExamples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics\n"
+    "description": "Provides a powerful query interface to filter and retrieve assets and their details\n\nReturns a list of resources matching the specified search criteria.\n\nUses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference.\n\n## Expression syntax\n\n- **Match**: `field:value` (token match) or `field=value` (exact match). Examples: `tags:shirt`, `tags=cotton`.\n- **Comparisons**: `>`, `<`, `>=`, `<=` for numbers and dates. Example: `bytes>10000000`.\n- **Ranges**: `field:[from TO to]` inclusive, `field:{from TO to}` exclusive. Example: `width:{200 TO 1028}`.\n- **Booleans**: `AND`, `OR`, `NOT` (uppercase), or `+` (must), `-` (must not). `NOT` must appear between clauses — a bare leading `NOT` is a parse error; use `-field:value` to negate the first clause. Group with parentheses: `(shirt OR pants) AND clothes`.\n- **Wildcards**: trailing `*` only, for prefix match (`public_id:shoes_*`, `format:jp*`, `tags:shirt*`). Not supported on `folder`, `asset_folder`, `resource_type`, or `type`. Leading `*`, middle `*`, `?`, and bare `*` (`folder:*`, `context.alt:*`) are all parse errors — wildcards cannot be used as a \"field is present\" probe.\n- **Tokenized vs exact fields**: `tags`, `filename`, `display_name`, `context.<key>`, and `metadata.<id>` match on tokens split by whitespace and punctuation — `tags:analysis` matches the tag `full-analysis`. `public_id`, `folder`, `asset_folder`, and `format` match the whole value — `public_id:dog` will not match `dog_pldcwy`; use `public_id=\"dog_pldcwy\"` (exact) or `public_id:dog*` (prefix). These exact-match fields still accept a trailing `*` for prefix match (except `folder` / `asset_folder`, where wildcards are ignored).\n- **Dates**: ISO-8601 in quotes (`uploaded_at>\"2024-01-15\"`) or relative shorthand `Nh`, `Nd`, `Nw`, `Nm`, `Ny` (`uploaded_at>1d`, `created_at:[4w TO 1w]`). Send raw `<`/`>`, never HTML-escaped.\n- **Quoting**: wrap any value containing a space, colon, or other reserved character (`! ( ) { } [ ] ^ ~ ?  \\ = & < > |`) in double quotes, or escape each character with `\\`. Examples: `tags:\"service:mantels\"`, `aspect_ratio:\"16:9\"`, `folder:\"My Folder\"`.\n\n## Common mistakes\n\n- Use `folder:` or `asset_folder:` (singular); `folders:`, `asset_folder_id:`, and other invented variants are not valid fields. Pass the exact folder name — wildcards do not apply here.\n- There is no \"has any value\" / presence probe. `folder:*`, `metadata.alt:*`, `context.key:*`, `tags:*`, and `-tags:*` are all parse errors. See *\"Which assets have any value for `metadata.<id>`?\"* under **Common tasks** for workarounds.\n- `NOT foo AND bar` is a parse error. Write it as `bar AND NOT foo` or `-foo AND bar`, and keep every `NOT` between two clauses (`a AND NOT b AND NOT c` is fine; `NOT b AND NOT c …` is not).\n- `public_id:dog` will not match `dog_pldcwy`. Use `public_id=\"dog_pldcwy\"` (exact) or `public_id:dog*` (prefix).\n- `tags=service:mantels` fails because the unquoted colon is parsed as a field separator. Use `tags=\"service:mantels\"` or `tags=service\\:mantels`.\n- Do not HTML-escape operators. Send `uploaded_at<1h`, not `uploaded_at&lt;1h`.\n- Do not leave an operand empty (e.g. `tags: AND -tags:foo`). Omit the empty clause entirely.\n\n## Tips\n\n- Set `max_results: 0` to return only `total_count` and `aggregations` without any resource payload — useful for counts and aggregation-only queries.\n- `total_count` is always present in the response; prefer it over running an aggregation just to get a count.\n- `aggregate` (both simple and range variants) and the `metadata`, `image_metadata`, `image_analysis` values of `with_field` require a Tier 2 search plan.\n- Range aggregations require each range to include a `key` label (1–20 chars, `[a-zA-Z0-9_-]+`) and at least one of `from` / `to`.\n\n## Common tasks\n\n- **Count matching assets** — put the filter in `expression` with `max_results: 0` and read `total_count` from the response. Works on every tier; no `aggregate` needed.\n- **Preview one matching asset** — set `max_results: 1`; add `with_field: [\"tags\", \"context\"]` (or `metadata`, Tier 2) to inspect values. Prefer this over fetching and scanning a full page.\n- **Distribution of values for a field** — Tier 2: `aggregate: [format|resource_type|type]` for enum counts, or range aggregations on `bytes`, `image_pixels`, `video_pixels`, or `duration`. Tier 1 fallback: run N small queries with `max_results: 0`, one per candidate value, and read `total_count` from each.\n- **\"Which assets have any value for `metadata.<id>`?\"** — not expressible directly (`metadata.X:*` is a parse error; there is no presence probe). Workarounds: (a) if the field has a known value set, enumerate — `metadata.region:(apac OR emea OR amer)`; (b) query broadly with `with_field: [\"metadata\"]` (Tier 2) and filter client-side for entries where the field is set; (c) at ingest time, attach a sentinel tag whenever the field is set, then search by that tag.\n- **Newest / largest N** — keep the filter in `expression` and sort explicitly: `sort_by: [{uploaded_at: \"desc\"}]` with `max_results: 10`.\n- **Filter by folder** — both `asset_folder:\"parent/child\"` and `folder:\"parent/child\"` match an exact folder path; there is no wildcard or \"contains\". To query across multiple folders, enumerate: `asset_folder:(\"campaigns/2024\" OR \"campaigns/2025\")`.\n- **Filter by metadata when you only know the label** — first call `list-metadata-fields` to resolve the label to an `external_id`, then query `metadata.<external_id>:value`.\n- **Multiple independent filters in one turn** — prefer one `expression` with `OR` / parentheses over firing many parallel calls: `metadata.region:apac OR metadata.region:emea` in a single request is faster and more reliable than two parallel requests.\n\n## Examples\n\n- `tags:shirt AND uploaded_at>1d`\n- `resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)`\n- `folder:products AND context.category:electronics`\n- `tags:\"service:mantels\" AND -tags:discontinued`\n"
   },
   {
     "name": "visual-search-assets",
-    "description": "Finds images in your asset library based on visual similarity or content\n\nReturns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways:\n- Provide a URL of an image\n- Specify the public ID or asset ID of an existing image\n- Provide a textual description\n"
+    "description": "Finds images in your asset library based on visual similarity or content\n\nReturns a list of resources that are visually similar to a specified image. You can provide the source image for comparison in one of three ways:\n- Provide a URL of an image\n- Specify the asset ID of an existing image\n- Provide a textual description\n"
   },
   {
     "name": "get-tx-reference",