@datocms/cma-client 5.1.1 → 5.1.3

package/src/fieldTypes/color.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { ColorPickerEditorConfiguration } from './appearance/color_picker';
 import type { RequiredValidator } from './validators/required';
 
@@ -20,6 +21,16 @@ export function isColorFieldValue(value: unknown): value is ColorFieldValue {
   );
 }
 
+export function isLocalizedColorFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<ColorFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isColorFieldValue)
+  );
+}
+
 export type ColorFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/date.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { DatePickerEditorConfiguration } from './appearance/date_picker';
 import type { DateRangeValidator } from './validators/date_range';
 import type { RequiredValidator } from './validators/required';
@@ -9,6 +10,16 @@ export function isDateFieldValue(value: unknown): value is DateFieldValue {
   return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value);
 }
 
+export function isLocalizedDateFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<DateFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isDateFieldValue)
+  );
+}
+
 export type DateFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/date_time.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { DateTimePickerEditorConfiguration } from './appearance/date_time_picker';
 import type { DateTimeRangeValidator } from './validators/date_time_range';
 import type { RequiredValidator } from './validators/required';
@@ -14,6 +15,16 @@ export function isDateTimeFieldValue(
   );
 }
 
+export function isLocalizedDateTimeFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<DateTimeFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isDateTimeFieldValue)
+  );
+}
+
 export type DateTimeFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/file.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { FileEditorConfiguration } from './appearance/file';
 import type { ExtensionValidator } from './validators/extension';
 import type { FileSizeValidator } from './validators/file_size';
@@ -22,6 +23,16 @@ export function isFileFieldValue(value: unknown): value is FileFieldValue {
   return typeof value === 'object' && value !== null && 'upload_id' in value;
 }
 
+export function isLocalizedFileFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<FileFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isFileFieldValue)
+  );
+}
+
 export type FileFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/float.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { FloatEditorConfiguration } from './appearance/float';
 import type { NumberRangeValidator } from './validators/number_range';
 import type { RequiredValidator } from './validators/required';
@@ -8,6 +9,16 @@ export function isFloatFieldValue(value: unknown): value is FloatFieldValue {
   return typeof value === 'number' || value === null;
 }
 
+export function isLocalizedFloatFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<FloatFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isFloatFieldValue)
+  );
+}
+
 export type FloatFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/gallery.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { GalleryEditorConfiguration } from './appearance/gallery';
 import type { ExtensionValidator } from './validators/extension';
 import type { FileSizeValidator } from './validators/file_size';
@@ -30,6 +31,16 @@ export function isGalleryFieldValue(
   );
 }
 
+export function isLocalizedGalleryFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<GalleryFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isGalleryFieldValue)
+  );
+}
+
 export type GalleryFieldValidators = {
   /** Only accept a number of items within the specified range */
   size?: SizeValidator;

package/src/fieldTypes/integer.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { IntegerEditorConfiguration } from './appearance/integer';
 import type { NumberRangeValidator } from './validators/number_range';
 import type { RequiredValidator } from './validators/required';
@@ -10,6 +11,16 @@ export function isIntegerFieldValue(
   return typeof value === 'number' || value === null;
 }
 
+export function isLocalizedIntegerFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<IntegerFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isIntegerFieldValue)
+  );
+}
+
 export type IntegerFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/json.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { JsonEditorConfiguration } from './appearance/json';
 import type { StringCheckboxGroupEditorConfiguration } from './appearance/string_checkbox_group';
 import type { StringMultiSelectEditorConfiguration } from './appearance/string_multi_select';
@@ -16,6 +17,16 @@ export function isJsonFieldValue(value: unknown): value is JsonFieldValue {
   }
 }
 
+export function isLocalizedJsonFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<JsonFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isJsonFieldValue)
+  );
+}
+
 export type JsonFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/lat_lon.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { MapEditorConfiguration } from './appearance/map';
 import type { RequiredValidator } from './validators/required';
 
@@ -18,6 +19,16 @@ export function isLocationFieldValue(
   );
 }
 
+export function isLocalizedLocationFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<LocationFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isLocationFieldValue)
+  );
+}
+
 export type LocationFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;

package/src/fieldTypes/link.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { LinkEmbedEditorConfiguration } from './appearance/link_embed';
 import type { LinkSelectEditorConfiguration } from './appearance/link_select';
 import type { ItemItemTypeValidator } from './validators/item_item_type';
@@ -10,6 +11,16 @@ export function isLinkFieldValue(value: unknown): value is LinkFieldValue {
   return typeof value === 'string' || value === null;
 }
 
+export function isLocalizedLinkFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<LinkFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isLinkFieldValue)
+  );
+}
+
 export type LinkFieldValidators = {
   /** Only accept references to records of the specified models */
   item_item_type: ItemItemTypeValidator;

package/src/fieldTypes/links.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { LinksEmbedEditorConfiguration } from './appearance/links_embed';
 import type { LinksSelectEditorConfiguration } from './appearance/links_select';
 import type { ItemsItemTypeValidator } from './validators/items_item_type';
@@ -12,6 +13,16 @@ export function isLinksFieldValue(value: unknown): value is LinksFieldValue {
   );
 }
 
+export function isLocalizedLinksFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<LinksFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isLinksFieldValue)
+  );
+}
+
 export type LinksFieldValidators = {
   /** Only accept references to records of the specified models */
   items_item_type: ItemsItemTypeValidator;

package/src/fieldTypes/rich_text.ts

@@ -1,10 +1,14 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import type { RichTextEditorConfiguration } from './appearance/rich_text';
 import {
   type BlockItemInARequest,
-  isBlockObject,
-  isBlockObjectWithId,
-  isBlockStringId,
+  isItemId,
+  isItemWithOptionalIdAndMeta,
+  isItemWithOptionalMeta,
 } from './single_block';
+import type { RichTextBlocksValidator } from './validators/rich_text_blocks';
+import type { SizeValidator } from './validators/size';
 
 /**
  * MODULAR CONTENT FIELD TYPE SYSTEM FOR DATOCMS
@@ -53,8 +57,8 @@ export type RichTextFieldValue = string[] | null;
 /**
  * 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)
+ * - RawApiTypes.Item: Full block object with ID (for updates)
+ * - Omit<RawApiTypes.Item, 'id'>: Block object without ID (for creation)
  */
 export type RichTextFieldValueAsRequest = BlockItemInARequest[] | null;
 
@@ -64,14 +68,14 @@ export type RichTextFieldValueAsRequest = BlockItemInARequest[] | null;
  * =============================================================================
  *
  * When using the ?nested=true query parameter, the API returns Modular Content data
- * with embedded blocks fully populated as complete SchemaTypes.Item objects instead
+ * with embedded blocks fully populated as complete RawApiTypes.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 RichTextFieldValueWithNestedBlocks = SchemaTypes.Item[] | null;
+export type RichTextFieldValueWithNestedBlocks = RawApiTypes.Item[] | null;
 
 /**
  * =============================================================================
@@ -93,6 +97,16 @@ export function isRichTextFieldValue(
   );
 }
 
+export function isLocalizedRichTextFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<RichTextFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isRichTextFieldValue)
+  );
+}
+
 /**
  * Type guard for Modular Content field values in API request format.
  * Allows blocks as string IDs, full objects with IDs, or objects without IDs.
@@ -106,16 +120,26 @@ export function isRichTextFieldValueAsRequest(
 
   return value.every((block) => {
     // String ID - referencing existing block
-    if (isBlockStringId(block)) return true;
+    if (isItemId(block)) return true;
 
     // Object (either with or without ID for updates/creation)
-    return isBlockObject(block);
+    return isItemWithOptionalIdAndMeta(block);
   });
 }
 
+export function isLocalizedRichTextFieldValueAsRequest(
+  value: unknown,
+): value is LocalizedFieldValue<RichTextFieldValueAsRequest> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isRichTextFieldValueAsRequest)
+  );
+}
+
 /**
  * Type guard for Modular Content field values with nested blocks (?nested=true format).
- * Ensures all blocks are full SchemaTypes.Item objects with complete data.
+ * Ensures all blocks are full RawApiTypes.Item objects with complete data.
  */
 export function isRichTextFieldValueWithNestedBlocks(
   value: unknown,
@@ -126,13 +150,19 @@ export function isRichTextFieldValueWithNestedBlocks(
 
   return value.every((block) => {
     // Must be a full object with ID (nested format always includes complete block objects)
-    return isBlockObjectWithId(block);
+    return isItemWithOptionalMeta(block);
   });
 }
 
-import type { RichTextEditorConfiguration } from './appearance/rich_text';
-import type { RichTextBlocksValidator } from './validators/rich_text_blocks';
-import type { SizeValidator } from './validators/size';
+export function isLocalizedRichTextFieldValueWithNestedBlocks(
+  value: unknown,
+): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isRichTextFieldValueWithNestedBlocks)
+  );
+}
 
 export type RichTextFieldValidators = {
   /** Only accept references to block records of the specified block models */

package/src/fieldTypes/seo.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { SeoEditorConfiguration } from './appearance/seo';
 import type { DescriptionLengthValidator } from './validators/description_length';
 import type { FileSizeValidator } from './validators/file_size';
@@ -27,6 +28,16 @@ export function isSeoFieldValue(value: unknown): value is SeoFieldValue {
   );
 }
 
+export function isLocalizedSeoFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<SeoFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isSeoFieldValue)
+  );
+}
+
 export type SeoFieldValidators = {
   /** SEO field has to specify one or more properties, or it won't be valid */
   required_seo_fields?: RequiredSeoFieldsValidator;

package/src/fieldTypes/single_block.ts

@@ -1,4 +1,10 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
+
+import type { FramedSingleBlockEditorConfiguration } from './appearance/framed_single_block';
+import type { FramelessSingleBlockEditorConfiguration } from './appearance/frameless_single_block';
+import type { RequiredValidator } from './validators/required';
+import type { SingleBlockBlocksValidator } from './validators/single_block_blocks';
 
 /**
  * SINGLE BLOCK FIELD TYPE SYSTEM FOR DATOCMS
@@ -44,23 +50,34 @@ export type SingleBlockFieldValue = string | null;
  * - Omit ID for new blocks being created
  */
 
+/** Represents an existing block in a CMA request */
+export type UnchangedBlockInARequest = string;
+/** Represents a block we want to update in a CMA request */
+export type UpdatedBlockInARequest = OptionalFields<RawApiTypes.Item, 'meta'>;
+/** Represents a new block to create in a CMA request */
+export type NewBlockInARequest = OptionalFields<
+  RawApiTypes.Item,
+  'id' | 'meta'
+>;
+
 /**
  * Union type representing the different ways a block can be specified in API requests:
- * - string: Just the block ID (most common case)
- * - Full block object with ID (for updates)
- * - Block object without ID (for creation)
+ * - string: Just the block ID (to keep existing blocks unchanged)
+ * - Full block object with ID (to update an existing block)
+ * - Block object without ID (to create a new block)
  *
  * Also, 'meta' can always be omitted
  */
 export type BlockItemInARequest =
-  | string
-  | OptionalFields<SchemaTypes.Item, 'id' | 'meta'>;
+  | UnchangedBlockInARequest
+  | UpdatedBlockInARequest
+  | NewBlockInARequest;
 
 /**
  * Single Block 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)
+ * - string: Just the block ID (to keep existing blocks unchanged)
+ * - Full block object with ID (to update an existing block)
+ * - Block object without ID (to create a new block)
  */
 export type SingleBlockFieldValueAsRequest = BlockItemInARequest | null;
 
@@ -70,14 +87,14 @@ export type SingleBlockFieldValueAsRequest = BlockItemInARequest | null;
  * =============================================================================
  *
  * When using the ?nested=true query parameter, the API returns Single Block data
- * with embedded block fully populated as complete SchemaTypes.Item object instead
+ * with embedded block fully populated as complete RawApiTypes.Item object instead
  * of just string ID. This provides type safety for working with fully resolved data.
  */
 
 /**
  * Single Block field value with nested block - fully populated block object
  */
-export type SingleBlockFieldValueWithNestedBlocks = SchemaTypes.Item | null;
+export type SingleBlockFieldValueWithNestedBlocks = RawApiTypes.Item | null;
 
 /**
  * =============================================================================
@@ -87,21 +104,21 @@ export type SingleBlockFieldValueWithNestedBlocks = SchemaTypes.Item | null;
  */
 
 /**
- * Validates if a single block item is a string ID
+ * Validates if the input is a valid item (either block or record) ID
  */
-export function isBlockStringId(block: unknown): block is string {
-  return typeof block === 'string';
+export function isItemId(input: unknown): input is string {
+  return typeof input === 'string';
 }
 
 export type ItemWithOptionalIdAndMeta = OptionalFields<
-  SchemaTypes.Item,
+  RawApiTypes.Item,
   'id' | 'meta'
 >;
 
 /**
- * Validates if a single block item is a SchemaTypes.Item object (with or without ID)
+ * Validates if the input is a RawApiTypes.Item object (with optional `id` and `meta`)
  */
-export function isBlockObject(
+export function isItemWithOptionalIdAndMeta(
   block: unknown,
 ): block is ItemWithOptionalIdAndMeta {
   return (
@@ -112,15 +129,19 @@ export function isBlockObject(
   );
 }
 
-export type ItemWithOptionalMeta = OptionalFields<SchemaTypes.Item, 'meta'>;
+export type ItemWithOptionalMeta = OptionalFields<RawApiTypes.Item, 'meta'>;
 
 /**
- * Validates if a single block item is a complete SchemaTypes.Item object with ID
+ * Validates if the input is a a complete RawApiTypes.Item object with optional `meta`
  */
-export function isBlockObjectWithId(
+export function isItemWithOptionalMeta(
   block: unknown,
 ): block is ItemWithOptionalMeta {
-  return isBlockObject(block) && 'id' in block && typeof block.id === 'string';
+  return (
+    isItemWithOptionalIdAndMeta(block) &&
+    'id' in block &&
+    typeof block.id === 'string'
+  );
 }
 
 /**
@@ -139,6 +160,16 @@ export function isSingleBlockFieldValue(
   return typeof value === 'string' || value === null;
 }
 
+export function isLocalizedSingleBlockFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<SingleBlockFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isSingleBlockFieldValue)
+  );
+}
+
 /**
  * Type guard for Single Block field values in API request format.
  * Allows block as string ID, full object with ID, or object without ID.
@@ -148,16 +179,26 @@ export function isSingleBlockFieldValueAsRequest(
 ): value is SingleBlockFieldValueAsRequest {
   if (value === null) return true;
 
-  // String ID _ referencing existing block
-  if (isBlockStringId(value)) return true;
+  // String ID - referencing existing block
+  if (isItemId(value)) return true;
 
   // Object (either with or without ID for updates/creation)
-  return isBlockObject(value);
+  return isItemWithOptionalIdAndMeta(value);
+}
+
+export function isLocalizedSingleBlockFieldValueAsRequest(
+  value: unknown,
+): value is LocalizedFieldValue<SingleBlockFieldValueAsRequest> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isSingleBlockFieldValueAsRequest)
+  );
 }
 
 /**
  * Type guard for Single Block field values with nested blocks (?nested=true format).
- * Ensures block is a full SchemaTypes.Item object with complete data.
+ * Ensures block is a full RawApiTypes.Item object with complete data.
  */
 export function isSingleBlockFieldValueWithNestedBlocks(
   value: unknown,
@@ -165,13 +206,18 @@ export function isSingleBlockFieldValueWithNestedBlocks(
   if (value === null) return true;
 
   // Must be a full object with ID (nested format always includes complete block objects)
-  return isBlockObjectWithId(value);
+  return isItemWithOptionalMeta(value);
 }
 
-import type { FramedSingleBlockEditorConfiguration } from './appearance/framed_single_block';
-import type { FramelessSingleBlockEditorConfiguration } from './appearance/frameless_single_block';
-import type { RequiredValidator } from './validators/required';
-import type { SingleBlockBlocksValidator } from './validators/single_block_blocks';
+export function isLocalizedSingleBlockFieldValueWithNestedBlocks(
+  value: unknown,
+): value is LocalizedFieldValue<SingleBlockFieldValueWithNestedBlocks> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isSingleBlockFieldValueWithNestedBlocks)
+  );
+}
 
 export type SingleBlockFieldValidators = {
   /** Only accept references to block records of the specified block models */

package/src/fieldTypes/slug.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { SlugEditorConfiguration } from './appearance/slug';
 import type { LengthValidator } from './validators/length';
 import type { RequiredValidator } from './validators/required';
@@ -8,7 +9,17 @@ export type SlugFieldValue = string | null;
 
 export function isSlugFieldValue(value: unknown): value is SlugFieldValue {
   if (value === null) return true;
-  return typeof value === 'string' && /^[a-z0-9_]+(?:-[a-z0-9]+)*$/.test(value);
+  return typeof value === 'string';
+}
+
+export function isLocalizedSlugFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<SlugFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isSlugFieldValue)
+  );
 }
 
 export type SlugFieldValidators = {

package/src/fieldTypes/string.ts

@@ -1,3 +1,4 @@
+import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { SingleLineEditorConfiguration } from './appearance/single_line';
 import type { StringRadioGroupEditorConfiguration } from './appearance/string_radio_group';
 import type { StringSelectEditorConfiguration } from './appearance/string_select';
@@ -13,6 +14,16 @@ export function isStringFieldValue(value: unknown): value is StringFieldValue {
   return typeof value === 'string' || value === null;
 }
 
+export function isLocalizedStringFieldValue(
+  value: unknown,
+): value is LocalizedFieldValue<StringFieldValue> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.values(value).every(isStringFieldValue)
+  );
+}
+
 export type StringFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;