@datocms/cma-client 5.0.1 → 5.1.1

package/src/fieldTypes/validators/extension.ts

@@ -0,0 +1,14 @@
+/**
+ * Only accept assets with specific file extensions.
+ */
+export type ExtensionValidator =
+  | {
+      /** Set of allowed file extensions */
+      extensions: string[];
+      predefined_list?: never;
+    }
+  | {
+      extensions?: never;
+      /** Allowed file type */
+      predefined_list: 'image' | 'transformable_image' | 'video' | 'document';
+    };

package/src/fieldTypes/validators/file_size.ts

@@ -0,0 +1,18 @@
+/**
+ * Accept assets only within a specified file size range.
+ */
+export type FileSizeValidator =
+  | {
+      /** Numeric value for minimum filesize */
+      min_value: number /** Unit for minimum filesize */;
+      min_unit: 'B' | 'KB' | 'MB' /** Numeric value for maximum filesize */;
+      max_value?: number /** Unit for maximum filesize */;
+      max_unit?: 'B' | 'KB' | 'MB';
+    }
+  | {
+      /** Numeric value for minimum filesize */
+      min_value?: number /** Unit for minimum filesize */;
+      min_unit?: 'B' | 'KB' | 'MB' /** Numeric value for maximum filesize */;
+      max_value: number /** Unit for maximum filesize */;
+      max_unit: 'B' | 'KB' | 'MB';
+    };

package/src/fieldTypes/validators/format.ts

@@ -0,0 +1,18 @@
+/**
+ * Accepts only strings that match a specified format.
+ * Only one of `custom_pattern` or `predefined_pattern` should be specified.
+ * If `custom_pattern` is used, an additional `description` parameter can be provided
+ * to serve as a hint for the user with a simple explanation of the expected pattern.
+ */
+export type FormatValidator = {
+  /** Custom regular expression for validation */
+  custom_pattern?: string;
+  /** Specifies a pre-defined format (email or URL) */
+  predefined_pattern?: 'email' | 'url';
+  /**
+   * Description that serves as a hint for the user when using custom_pattern.
+   * Offers a simple explanation of the expected pattern, such as "The field must end with an 's'",
+   * instead of the default message like "Field must match the pattern: /s$/".
+   */
+  description?: string;
+};

package/src/fieldTypes/validators/image_aspect_ratio.ts

@@ -0,0 +1,31 @@
+/**
+ * Accept assets only within a specified aspect ratio range.
+ */
+export type ImageAspectRatioValidator =
+  | {
+      /** Numerator part of the minimum aspect ratio */
+      min_ar_numerator: number /** Denominator part of the minimum aspect ratio */;
+      min_ar_denominator: number /** Numerator part for the required aspect ratio */;
+      eq_ar_numerator?: number /** Denominator part for the required aspect ratio */;
+      eq_ar_denominator?: number /** Numerator part of the maximum aspect ratio */;
+      max_ar_numerator?: number /** Denominator part of the maximum aspect ratio */;
+      max_ar_denominator?: number;
+    }
+  | {
+      /** Numerator part of the minimum aspect ratio */
+      min_ar_numerator?: number /** Denominator part of the minimum aspect ratio */;
+      min_ar_denominator?: number /** Numerator part for the required aspect ratio */;
+      eq_ar_numerator: number /** Denominator part for the required aspect ratio */;
+      eq_ar_denominator: number /** Numerator part of the maximum aspect ratio */;
+      max_ar_numerator?: number /** Denominator part of the maximum aspect ratio */;
+      max_ar_denominator?: number;
+    }
+  | {
+      /** Numerator part of the minimum aspect ratio */
+      min_ar_numerator?: number /** Denominator part of the minimum aspect ratio */;
+      min_ar_denominator?: number /** Numerator part for the required aspect ratio */;
+      eq_ar_numerator?: number /** Denominator part for the required aspect ratio */;
+      eq_ar_denominator?: number /** Numerator part of the maximum aspect ratio */;
+      max_ar_numerator: number /** Denominator part of the maximum aspect ratio */;
+      max_ar_denominator: number;
+    };

package/src/fieldTypes/validators/image_dimensions.ts

@@ -0,0 +1,32 @@
+/**
+ * Accept assets only within a specified height and width range.
+ */
+export type ImageDimensionsValidator =
+  | {
+      /** Numeric value for minimum width */
+      width_min_value: number /** Numeric value for maximum width */;
+      width_max_value?: number /** Numeric value for minimum height */;
+      height_min_value?: number /** Numeric value for maximum height */;
+      height_max_value?: number;
+    }
+  | {
+      /** Numeric value for minimum width */
+      width_min_value?: number /** Numeric value for maximum width */;
+      width_max_value: number /** Numeric value for minimum height */;
+      height_min_value?: number /** Numeric value for maximum height */;
+      height_max_value?: number;
+    }
+  | {
+      /** Numeric value for minimum width */
+      width_min_value?: number /** Numeric value for maximum width */;
+      width_max_value?: number /** Numeric value for minimum height */;
+      height_min_value: number /** Numeric value for maximum height */;
+      height_max_value?: number;
+    }
+  | {
+      /** Numeric value for minimum width */
+      width_min_value?: number /** Numeric value for maximum width */;
+      width_max_value?: number /** Numeric value for minimum height */;
+      height_min_value?: number /** Numeric value for maximum height */;
+      height_max_value: number;
+    };

package/src/fieldTypes/validators/index.ts

@@ -0,0 +1,27 @@
+export * from './date_range';
+export * from './date_time_range';
+export * from './description_length';
+export * from './enum';
+export * from './extension';
+export * from './file_size';
+export * from './format';
+export * from './image_aspect_ratio';
+export * from './image_dimensions';
+export * from './item_item_type';
+export * from './items_item_type';
+export * from './length';
+export * from './number_range';
+export * from './required';
+export * from './required_alt_title';
+export * from './required_seo_fields';
+export * from './rich_text_blocks';
+export * from './sanitization';
+export * from './single_block_blocks';
+export * from './size';
+export * from './slug_format';
+export * from './slug_title_field';
+export * from './structured_text_blocks';
+export * from './structured_text_inline_blocks';
+export * from './structured_text_links';
+export * from './title_length';
+export * from './unique';

package/src/fieldTypes/validators/item_item_type.ts

@@ -0,0 +1,31 @@
+/**
+ * Only accept references to records of the specified models.
+ */
+export type ItemItemTypeValidator = {
+  /** Set of allowed model IDs */
+  item_types: string[];
+  /**
+   * Strategy to apply when a publishing is requested and this field references some unpublished records.
+   * - "fail": Fail the operation and notify the user
+   * - "publish_references": Publish also the referenced records
+   * @default "fail"
+   */
+  on_publish_with_unpublished_references_strategy?:
+    | 'fail'
+    | 'publish_references';
+  /**
+   * Strategy to apply when unpublishing is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "unpublish": Unpublish also this record
+   * - "delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)
+   * @default "fail"
+   */
+  on_reference_unpublish_strategy?: 'fail' | 'unpublish' | 'delete_references';
+  /**
+   * Strategy to apply when deletion is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)
+   * @default "delete_references"
+   */
+  on_reference_delete_strategy?: 'fail' | 'delete_references';
+};

package/src/fieldTypes/validators/items_item_type.ts

@@ -0,0 +1,31 @@
+/**
+ * Only accept references to records of the specified models.
+ */
+export type ItemsItemTypeValidator = {
+  /** Set of allowed model IDs */
+  item_types: string[];
+  /**
+   * Strategy to apply when a publishing is requested and this field references some unpublished records.
+   * - "fail": Fail the operation and notify the user
+   * - "publish_references": Publish also the referenced records
+   * @default "fail"
+   */
+  on_publish_with_unpublished_references_strategy?:
+    | 'fail'
+    | 'publish_references';
+  /**
+   * Strategy to apply when unpublishing is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "unpublish": Unpublish also this record
+   * - "delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)
+   * @default "fail"
+   */
+  on_reference_unpublish_strategy?: 'fail' | 'unpublish' | 'delete_references';
+  /**
+   * Strategy to apply when deletion is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)
+   * @default "delete_references"
+   */
+  on_reference_delete_strategy?: 'fail' | 'delete_references';
+};

package/src/fieldTypes/validators/length.ts

@@ -0,0 +1,22 @@
+/**
+ * Accept strings only with a specified number of characters.
+ */
+export type LengthValidator =
+  | {
+      /** Minimum length */
+      min: number /** Expected length */;
+      eq?: number /** Maximum length */;
+      max?: number;
+    }
+  | {
+      /** Minimum length */
+      min?: number /** Expected length */;
+      eq: number /** Maximum length */;
+      max?: number;
+    }
+  | {
+      /** Minimum length */
+      min?: number /** Expected length */;
+      eq?: number /** Maximum length */;
+      max: number;
+    };

package/src/fieldTypes/validators/number_range.ts

@@ -0,0 +1,12 @@
+/**
+ * Accept numbers only inside a specified range.
+ */
+export type NumberRangeValidator =
+  | {
+      /** Minimum value */ min: number /** Maximum value */;
+      max?: number;
+    }
+  | {
+      /** Minimum value */ min?: number /** Maximum value */;
+      max: number;
+    };

package/src/fieldTypes/validators/required.ts

@@ -0,0 +1,4 @@
+/**
+ * Value must be specified or it won't be valid.
+ */
+export type RequiredValidator = Record<string, never>;

package/src/fieldTypes/validators/required_alt_title.ts

@@ -0,0 +1,14 @@
+/**
+ * Assets contained in the field are required to specify custom title or alternate text, or they won't be valid.
+ */
+export type RequiredAltTitleValidator =
+  | {
+      /** Whether the title for the asset must be specified */
+      title: boolean /** Whether the alternate text for the asset must be specified */;
+      alt?: boolean;
+    }
+  | {
+      /** Whether the title for the asset must be specified */
+      title?: boolean /** Whether the alternate text for the asset must be specified */;
+      alt: boolean;
+    };

package/src/fieldTypes/validators/required_seo_fields.ts

@@ -0,0 +1,32 @@
+/**
+ * SEO field has to specify one or more properties, or it won't be valid.
+ */
+export type RequiredSeoFieldsValidator =
+  | {
+      /** Whether the meta title must be specified */
+      title: boolean /** Whether the meta description must be specified */;
+      description?: boolean /** Whether the social sharing image must be specified */;
+      image?: boolean /** Whether the type of Twitter card must be specified */;
+      twitter_card?: boolean;
+    }
+  | {
+      /** Whether the meta title must be specified */
+      title?: boolean /** Whether the meta description must be specified */;
+      description: boolean /** Whether the social sharing image must be specified */;
+      image?: boolean /** Whether the type of Twitter card must be specified */;
+      twitter_card?: boolean;
+    }
+  | {
+      /** Whether the meta title must be specified */
+      title?: boolean /** Whether the meta description must be specified */;
+      description?: boolean /** Whether the social sharing image must be specified */;
+      image: boolean /** Whether the type of Twitter card must be specified */;
+      twitter_card?: boolean;
+    }
+  | {
+      /** Whether the meta title must be specified */
+      title?: boolean /** Whether the meta description must be specified */;
+      description?: boolean /** Whether the social sharing image must be specified */;
+      image?: boolean /** Whether the type of Twitter card must be specified */;
+      twitter_card: boolean;
+    };

package/src/fieldTypes/validators/rich_text_blocks.ts

@@ -0,0 +1,7 @@
+/**
+ * Only accept references to block records of the specified block models.
+ */
+export type RichTextBlocksValidator = {
+  /** Set of allowed Block Model IDs */
+  item_types: string[];
+};

package/src/fieldTypes/validators/sanitization.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks for the presence of malicious code in HTML fields: content is valid if no dangerous code is present.
+ */
+export type SanitizationValidator = {
+  /** Content is actively sanitized before applying the validation */
+  sanitize_before_validation: boolean;
+};

package/src/fieldTypes/validators/single_block_blocks.ts

@@ -0,0 +1,7 @@
+/**
+ * Only accept references to block records of the specified block models.
+ */
+export type SingleBlockBlocksValidator = {
+  /** Set of allowed Block Model IDs */
+  item_types: string[];
+};

package/src/fieldTypes/validators/size.ts

@@ -0,0 +1,32 @@
+/**
+ * Only accept a number of items within the specified range.
+ */
+export type SizeValidator =
+  | {
+      /** Minimum length */
+      min: number /** Expected length */;
+      eq?: number /** Maximum length */;
+      max?: number /** The number of items must be multiple of this value */;
+      multiple_of?: number;
+    }
+  | {
+      /** Minimum length */
+      min?: number /** Expected length */;
+      eq: number /** Maximum length */;
+      max?: number /** The number of items must be multiple of this value */;
+      multiple_of?: number;
+    }
+  | {
+      /** Minimum length */
+      min?: number /** Expected length */;
+      eq?: number /** Maximum length */;
+      max: number /** The number of items must be multiple of this value */;
+      multiple_of?: number;
+    }
+  | {
+      /** Minimum length */
+      min?: number /** Expected length */;
+      eq?: number /** Maximum length */;
+      max?: number /** The number of items must be multiple of this value */;
+      multiple_of: number;
+    };

package/src/fieldTypes/validators/slug_format.ts

@@ -0,0 +1,14 @@
+/**
+ * Only accept slugs having a specific format.
+ */
+export type SlugFormatValidator =
+  | {
+      /** Regular expression to be validated */
+      custom_pattern: string;
+      predefined_pattern?: never;
+    }
+  | {
+      custom_pattern?: never;
+      /** Allowed format */
+      predefined_pattern: 'webpage_slug';
+    };

package/src/fieldTypes/validators/slug_title_field.ts

@@ -0,0 +1,7 @@
+/**
+ * Specifies the ID of the Single-line string field that will be used to generate the slug.
+ */
+export type SlugTitleFieldValidator = {
+  /** The field that will be used to generate the slug */
+  title_field_id: string;
+};

package/src/fieldTypes/validators/structured_text_blocks.ts

@@ -0,0 +1,7 @@
+/**
+ * Only accept references to block records of the specified block models.
+ */
+export type StructuredTextBlocksValidator = {
+  /** Set of allowed Block Model IDs */
+  item_types: string[];
+};

package/src/fieldTypes/validators/structured_text_inline_blocks.ts

@@ -0,0 +1,7 @@
+/**
+ * Only accept references to block records of the specified block models.
+ */
+export type StructuredTextInlineBlocksValidator = {
+  /** Set of allowed Block Model IDs */
+  item_types: string[];
+};

package/src/fieldTypes/validators/structured_text_links.ts

@@ -0,0 +1,31 @@
+/**
+ * Only accept `itemLink` to `inlineItem` nodes for records of the specified models.
+ */
+export type StructuredTextLinksValidator = {
+  /** Set of allowed model IDs */
+  item_types: string[];
+  /**
+   * Strategy to apply when a publishing is requested and this field references some unpublished records.
+   * - "fail": Fail the operation and notify the user
+   * - "publish_references": Publish also the referenced records
+   * @default "fail"
+   */
+  on_publish_with_unpublished_references_strategy?:
+    | 'fail'
+    | 'publish_references';
+  /**
+   * Strategy to apply when unpublishing is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "unpublish": Unpublish also this record
+   * - "delete_references": Try to remove the reference to the unpublished record (if the field has a required validation it will fail)
+   * @default "delete_references"
+   */
+  on_reference_unpublish_strategy?: 'fail' | 'unpublish' | 'delete_references';
+  /**
+   * Strategy to apply when deletion is requested for a record referenced by this field.
+   * - "fail": Fail the operation and notify the user
+   * - "delete_references": Try to remove the reference to the deleted record (if the field has a required validation it will fail)
+   * @default "delete_references"
+   */
+  on_reference_delete_strategy?: 'fail' | 'delete_references';
+};

package/src/fieldTypes/validators/title_length.ts

@@ -0,0 +1,13 @@
+/**
+ * Limits the length of the title for a SEO field.
+ * Search engines usually truncate title tags to 60 characters so it is a good practice to keep the title around this length.
+ */
+export type TitleLengthValidator =
+  | {
+      /** Minimum value */ min: number /** Maximum value */;
+      max?: number;
+    }
+  | {
+      /** Minimum value */ min?: number /** Maximum value */;
+      max: number;
+    };

package/src/fieldTypes/validators/unique.ts

@@ -0,0 +1,4 @@
+/**
+ * The value must be unique across the whole collection of records.
+ */
+export type UniqueValidator = Record<string, never>;

package/src/fieldTypes/video.ts

@@ -0,0 +1,37 @@
+import type { VideoEditorConfiguration } from './appearance/video';
+import type { RequiredValidator } from './validators/required';
+
+export type VideoFieldValue = {
+  provider: 'youtube' | 'vimeo' | 'facebook';
+  provider_uid: string;
+  url: string;
+  width: number;
+  height: number;
+  thumbnail_url: string;
+  title: string;
+} | null;
+
+export function isVideoFieldValue(value: unknown): value is VideoFieldValue {
+  if (value === null) return true;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'provider' in value &&
+    'provider_uid' in value &&
+    'url' in value
+  );
+}
+
+export type VideoFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+};
+
+export type VideoFieldAppearance =
+  | { editor: 'video'; parameters: VideoEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/generated/Client.ts

@@ -147,7 +147,7 @@ export class Client {
       ...this.config,
       ...options,
       logFn: this.config.logFn || console.log,
-      userAgent: '@datocms/cma-client v5.0.1',
+      userAgent: '@datocms/cma-client v5.1.1',
       baseUrl: this.baseUrl,
       preCallStack: new Error().stack,
       extraHeaders: {