@datocms/cma-client 5.0.0 → 5.1.0

package/src/fieldTypes/color.ts

@@ -0,0 +1,35 @@
+import type { ColorPickerEditorConfiguration } from './appearance/color_picker';
+import type { RequiredValidator } from './validators/required';
+
+export type ColorFieldValue = {
+  red: number;
+  green: number;
+  blue: number;
+  alpha: number;
+} | null;
+
+export function isColorFieldValue(value: unknown): value is ColorFieldValue {
+  if (value === null) return true;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'red' in value &&
+    'green' in value &&
+    'blue' in value &&
+    'alpha' in value
+  );
+}
+
+export type ColorFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+};
+
+export type ColorFieldAppearance =
+  | { editor: 'color_picker'; parameters: ColorPickerEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/date.ts

@@ -0,0 +1,26 @@
+import type { DatePickerEditorConfiguration } from './appearance/date_picker';
+import type { DateRangeValidator } from './validators/date_range';
+import type { RequiredValidator } from './validators/required';
+
+export type DateFieldValue = string | null;
+
+export function isDateFieldValue(value: unknown): value is DateFieldValue {
+  if (value === null) return true;
+  return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value);
+}
+
+export type DateFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept dates only inside a specified date range */
+  date_range?: DateRangeValidator;
+};
+
+export type DateFieldAppearance =
+  | { editor: 'date_picker'; parameters: DatePickerEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/date_time.ts

@@ -0,0 +1,34 @@
+import type { DateTimePickerEditorConfiguration } from './appearance/date_time_picker';
+import type { DateTimeRangeValidator } from './validators/date_time_range';
+import type { RequiredValidator } from './validators/required';
+
+export type DateTimeFieldValue = string | null;
+
+export function isDateTimeFieldValue(
+  value: unknown,
+): value is DateTimeFieldValue {
+  if (value === null) return true;
+  return (
+    typeof value === 'string' &&
+    /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)
+  );
+}
+
+export type DateTimeFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept date times only inside a specified date range */
+  date_time_range?: DateTimeRangeValidator;
+};
+
+export type DateTimeFieldAppearance =
+  | {
+      editor: 'date_time_picker';
+      parameters: DateTimePickerEditorConfiguration;
+    }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/file.ts

@@ -0,0 +1,47 @@
+import type { FileEditorConfiguration } from './appearance/file';
+import type { ExtensionValidator } from './validators/extension';
+import type { FileSizeValidator } from './validators/file_size';
+import type { ImageAspectRatioValidator } from './validators/image_aspect_ratio';
+import type { ImageDimensionsValidator } from './validators/image_dimensions';
+import type { RequiredValidator } from './validators/required';
+import type { RequiredAltTitleValidator } from './validators/required_alt_title';
+
+export type FileFieldValue = {
+  upload_id: string;
+  alt?: string | null;
+  title?: string | null;
+  custom_data?: Record<string, unknown>;
+  focal_point?: {
+    x: number;
+    y: number;
+  } | null;
+} | null;
+
+export function isFileFieldValue(value: unknown): value is FileFieldValue {
+  if (value === null) return true;
+  return typeof value === 'object' && value !== null && 'upload_id' in value;
+}
+
+export type FileFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept assets only within a specified file size range */
+  file_size?: FileSizeValidator;
+  /** Accept assets only within a specified height and width range */
+  image_dimensions?: ImageDimensionsValidator;
+  /** Accept assets only within a specified aspect ratio range */
+  image_aspect_ratio?: ImageAspectRatioValidator;
+  /** Only accept assets with specific file extensions */
+  extension?: ExtensionValidator;
+  /** Assets contained in the field are required to specify custom title or alternate text */
+  required_alt_title?: RequiredAltTitleValidator;
+};
+
+export type FileFieldAppearance =
+  | { editor: 'file'; parameters: FileEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/float.ts

@@ -0,0 +1,25 @@
+import type { FloatEditorConfiguration } from './appearance/float';
+import type { NumberRangeValidator } from './validators/number_range';
+import type { RequiredValidator } from './validators/required';
+
+export type FloatFieldValue = number | null;
+
+export function isFloatFieldValue(value: unknown): value is FloatFieldValue {
+  return typeof value === 'number' || value === null;
+}
+
+export type FloatFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept numbers only inside a specified range */
+  number_range?: NumberRangeValidator;
+};
+
+export type FloatFieldAppearance =
+  | { editor: 'float'; parameters: FloatEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/gallery.ts

@@ -0,0 +1,55 @@
+import type { GalleryEditorConfiguration } from './appearance/gallery';
+import type { ExtensionValidator } from './validators/extension';
+import type { FileSizeValidator } from './validators/file_size';
+import type { ImageAspectRatioValidator } from './validators/image_aspect_ratio';
+import type { ImageDimensionsValidator } from './validators/image_dimensions';
+import type { RequiredAltTitleValidator } from './validators/required_alt_title';
+import type { SizeValidator } from './validators/size';
+
+export type GalleryFieldValue = Array<{
+  upload_id: string;
+  alt?: string | null;
+  title?: string | null;
+  custom_data?: Record<string, unknown>;
+  focal_point?: {
+    x: number;
+    y: number;
+  } | null;
+}> | null;
+
+export function isGalleryFieldValue(
+  value: unknown,
+): value is GalleryFieldValue {
+  if (value === null) return true;
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (item) =>
+        typeof item === 'object' && item !== null && 'upload_id' in item,
+    )
+  );
+}
+
+export type GalleryFieldValidators = {
+  /** Only accept a number of items within the specified range */
+  size?: SizeValidator;
+  /** Accept assets only within a specified file size range */
+  file_size?: FileSizeValidator;
+  /** Accept assets only within a specified height and width range */
+  image_dimensions?: ImageDimensionsValidator;
+  /** Accept assets only within a specified aspect ratio range */
+  image_aspect_ratio?: ImageAspectRatioValidator;
+  /** Only accept assets with specific file extensions */
+  extension?: ExtensionValidator;
+  /** Assets contained in the field are required to specify custom title or alternate text */
+  required_alt_title?: RequiredAltTitleValidator;
+};
+
+export type GalleryFieldAppearance =
+  | { editor: 'gallery'; parameters: GalleryEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/index.ts

@@ -0,0 +1,23 @@
+export * from './boolean';
+export * from './color';
+export * from './date';
+export * from './date_time';
+export * from './file';
+export * from './float';
+export * from './gallery';
+export * from './integer';
+export * from './json';
+export * from './lat_lon';
+export * from './link';
+export * from './links';
+export * from './rich_text';
+export * from './seo';
+export * from './single_block';
+export * from './slug';
+export * from './string';
+export * from './structured_text';
+export * from './text';
+export * from './video';
+
+export * from './appearance';
+export * from './validators';

package/src/fieldTypes/integer.ts

@@ -0,0 +1,27 @@
+import type { IntegerEditorConfiguration } from './appearance/integer';
+import type { NumberRangeValidator } from './validators/number_range';
+import type { RequiredValidator } from './validators/required';
+
+export type IntegerFieldValue = number | null;
+
+export function isIntegerFieldValue(
+  value: unknown,
+): value is IntegerFieldValue {
+  return typeof value === 'number' || value === null;
+}
+
+export type IntegerFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept numbers only inside a specified range */
+  number_range?: NumberRangeValidator;
+};
+
+export type IntegerFieldAppearance =
+  | { editor: 'integer'; parameters: IntegerEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/json.ts

@@ -0,0 +1,39 @@
+import type { JsonEditorConfiguration } from './appearance/json';
+import type { StringCheckboxGroupEditorConfiguration } from './appearance/string_checkbox_group';
+import type { StringMultiSelectEditorConfiguration } from './appearance/string_multi_select';
+import type { RequiredValidator } from './validators/required';
+
+export type JsonFieldValue = string | null;
+
+export function isJsonFieldValue(value: unknown): value is JsonFieldValue {
+  if (value === null) return true;
+  if (typeof value !== 'string') return false;
+  try {
+    JSON.parse(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export type JsonFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+};
+
+export type JsonFieldAppearance =
+  | { editor: 'json'; parameters: JsonEditorConfiguration }
+  | {
+      editor: 'string_multi_select';
+      parameters: StringMultiSelectEditorConfiguration;
+    }
+  | {
+      editor: 'string_checkbox_group';
+      parameters: StringCheckboxGroupEditorConfiguration;
+    }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/lat_lon.ts

@@ -0,0 +1,33 @@
+import type { MapEditorConfiguration } from './appearance/map';
+import type { RequiredValidator } from './validators/required';
+
+export type LocationFieldValue = {
+  latitude: number;
+  longitude: number;
+} | null;
+
+export function isLocationFieldValue(
+  value: unknown,
+): value is LocationFieldValue {
+  if (value === null) return true;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'latitude' in value &&
+    'longitude' in value
+  );
+}
+
+export type LocationFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+};
+
+export type LocationFieldAppearance =
+  | { editor: 'map'; parameters: MapEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/link.ts

@@ -0,0 +1,30 @@
+import type { LinkEmbedEditorConfiguration } from './appearance/link_embed';
+import type { LinkSelectEditorConfiguration } from './appearance/link_select';
+import type { ItemItemTypeValidator } from './validators/item_item_type';
+import type { RequiredValidator } from './validators/required';
+import type { UniqueValidator } from './validators/unique';
+
+export type LinkFieldValue = string | null;
+
+export function isLinkFieldValue(value: unknown): value is LinkFieldValue {
+  return typeof value === 'string' || value === null;
+}
+
+export type LinkFieldValidators = {
+  /** Only accept references to records of the specified models */
+  item_item_type: ItemItemTypeValidator;
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** The value must be unique across the whole collection of records */
+  unique?: UniqueValidator;
+};
+
+export type LinkFieldAppearance =
+  | { editor: 'link_select'; parameters: LinkSelectEditorConfiguration }
+  | { editor: 'link_embed'; parameters: LinkEmbedEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/links.ts

@@ -0,0 +1,30 @@
+import type { LinksEmbedEditorConfiguration } from './appearance/links_embed';
+import type { LinksSelectEditorConfiguration } from './appearance/links_select';
+import type { ItemsItemTypeValidator } from './validators/items_item_type';
+import type { SizeValidator } from './validators/size';
+
+export type LinksFieldValue = string[] | null;
+
+export function isLinksFieldValue(value: unknown): value is LinksFieldValue {
+  if (value === null) return true;
+  return (
+    Array.isArray(value) && value.every((item) => typeof item === 'string')
+  );
+}
+
+export type LinksFieldValidators = {
+  /** Only accept references to records of the specified models */
+  items_item_type: ItemsItemTypeValidator;
+  /** Only accept a number of items within the specified range */
+  size?: SizeValidator;
+};
+
+export type LinksFieldAppearance =
+  | { editor: 'links_select'; parameters: LinksSelectEditorConfiguration }
+  | { editor: 'links_embed'; parameters: LinksEmbedEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/rich_text.ts

@@ -0,0 +1,151 @@
+import type * as SchemaTypes from '../generated/SchemaTypes';
+import {
+  type BlockItemInARequest,
+  isBlockObject,
+  isBlockObjectWithId,
+  isBlockStringId,
+} from './single_block';
+
+/**
+ * MODULAR CONTENT FIELD TYPE SYSTEM FOR DATOCMS
+ *
+ * This module defines a comprehensive type system for handling DatoCMS Modular Content fields,
+ * which are arrays of embedded content blocks.
+ *
+ * The challenge we're solving:
+ * - DatoCMS Modular Content fields contain arrays of "blocks" (embedded content items)
+ * - By default, API responses contain blocks as string IDs (lightweight references)
+ * - With ?nested=true parameter, API responses contain blocks as full block objects
+ *   (which in turn can contain other blocks)
+ * - For API requests, blocks can be represented as:
+ *   1. String IDs (referencing existing blocks)
+ *   2. Full block objects with IDs (for updates)
+ *   3. Block objects without IDs (for creation)
+ *
+ * This creates a need for different type variants for the same conceptual data structure.
+ */
+
+/**
+ * =============================================================================
+ * BASIC MODULAR CONTENT TYPE - Default API response format
+ * =============================================================================
+ *
+ * The standard Modular Content field value containing block references as string IDs.
+ * This is what you get from regular API responses without ?nested=true.
+ */
+
+/**
+ * Basic Modular Content field value - array of string block IDs (lightweight references)
+ */
+export type RichTextFieldValue = string[] | null;
+
+/**
+ * =============================================================================
+ * REQUEST VARIANT - Type for sending data TO the DatoCMS API
+ * =============================================================================
+ *
+ * When making API requests, we need flexibility in how we represent embedded blocks:
+ * - Use string IDs to reference existing blocks that do not need to change
+ * - Include full block objects for updates
+ * - Omit IDs for new blocks being created
+ */
+
+/**
+ * Modular Content field value for API requests - allows flexible block representations:
+ * - string: Just the block ID (most common case)
+ * - SchemaTypes.Item: Full block object with ID (for updates)
+ * - Omit<SchemaTypes.Item, 'id'>: Block object without ID (for creation)
+ */
+export type RichTextFieldValueAsRequest = BlockItemInARequest[] | null;
+
+/**
+ * =============================================================================
+ * NESTED VARIANT - Type for API responses with ?nested=true parameter
+ * =============================================================================
+ *
+ * When using the ?nested=true query parameter, the API returns Modular Content data
+ * with embedded blocks fully populated as complete SchemaTypes.Item objects instead
+ * of just string IDs. This provides type safety for working with fully resolved data.
+ */
+
+/**
+ * Modular Content field value with nested blocks - array of fully populated block objects
+ */
+export type RichTextFieldValueWithResolvedBlocks = SchemaTypes.Item[] | null;
+
+/**
+ * =============================================================================
+ * TYPE GUARDS - Runtime validation functions
+ * =============================================================================
+ */
+
+/**
+ * Type guard for basic Modular Content field values (blocks as string IDs only).
+ * Checks for array structure and ensures all blocks are string references.
+ */
+export function isRichTextFieldValue(
+  value: unknown,
+): value is RichTextFieldValue {
+  if (value === null) return true;
+
+  return (
+    Array.isArray(value) && value.every((block) => typeof block === 'string')
+  );
+}
+
+/**
+ * Type guard for Modular Content field values in API request format.
+ * Allows blocks as string IDs, full objects with IDs, or objects without IDs.
+ */
+export function isRichTextFieldValueAsRequest(
+  value: unknown,
+): value is RichTextFieldValueAsRequest {
+  if (value === null) return true;
+
+  if (!Array.isArray(value)) return false;
+
+  return value.every((block) => {
+    // String ID - referencing existing block
+    if (isBlockStringId(block)) return true;
+
+    // Object (either with or without ID for updates/creation)
+    return isBlockObject(block);
+  });
+}
+
+/**
+ * Type guard for Modular Content field values with nested blocks (?nested=true format).
+ * Ensures all blocks are full SchemaTypes.Item objects with complete data.
+ */
+export function isRichTextFieldValueWithResolvedBlocks(
+  value: unknown,
+): value is RichTextFieldValueWithResolvedBlocks {
+  if (value === null) return true;
+
+  if (!Array.isArray(value)) return false;
+
+  return value.every((block) => {
+    // Must be a full object with ID (nested format always includes complete block objects)
+    return isBlockObjectWithId(block);
+  });
+}
+
+import type { RichTextEditorConfiguration } from './appearance/rich_text';
+import type { RichTextBlocksValidator } from './validators/rich_text_blocks';
+import type { SizeValidator } from './validators/size';
+
+export type RichTextFieldValidators = {
+  /** Only accept references to block records of the specified block models */
+  rich_text_blocks: RichTextBlocksValidator;
+  /** Only accept a number of items within the specified range */
+  size?: SizeValidator;
+};
+
+export type RichTextFieldAppearance =
+  | { editor: 'rich_text'; parameters: RichTextEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/seo.ts

@@ -0,0 +1,52 @@
+import type { SeoEditorConfiguration } from './appearance/seo';
+import type { DescriptionLengthValidator } from './validators/description_length';
+import type { FileSizeValidator } from './validators/file_size';
+import type { ImageAspectRatioValidator } from './validators/image_aspect_ratio';
+import type { ImageDimensionsValidator } from './validators/image_dimensions';
+import type { RequiredSeoFieldsValidator } from './validators/required_seo_fields';
+import type { TitleLengthValidator } from './validators/title_length';
+
+export type SeoFieldValue = {
+  title?: string | null;
+  description?: string | null;
+  image?: string | null;
+  twitter_card?: 'summary' | 'summary_large_image' | null;
+  no_index?: boolean;
+} | null;
+
+export function isSeoFieldValue(value: unknown): value is SeoFieldValue {
+  if (value === null) return true;
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ('title' in value ||
+      'description' in value ||
+      'image' in value ||
+      'twitter_card' in value ||
+      'no_index' in value)
+  );
+}
+
+export type SeoFieldValidators = {
+  /** SEO field has to specify one or more properties, or it won't be valid */
+  required_seo_fields?: RequiredSeoFieldsValidator;
+  /** Accept assets only within a specified file size range */
+  file_size?: FileSizeValidator;
+  /** Accept assets only within a specified height and width range */
+  image_dimensions?: ImageDimensionsValidator;
+  /** Accept assets only within a specified aspect ratio range */
+  image_aspect_ratio?: ImageAspectRatioValidator;
+  /** Limits the length of the title for a SEO field */
+  title_length?: TitleLengthValidator;
+  /** Limits the length of the description for a SEO field */
+  description_length?: DescriptionLengthValidator;
+};
+
+export type SeoFieldAppearance =
+  | { editor: 'seo'; parameters: SeoEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };