@datocms/cma-client 5.1.10 → 5.1.12

package/src/fieldTypes/gallery.ts

@@ -1,5 +1,14 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { GalleryEditorConfiguration } from './appearance/gallery';
+import {
+  type FileFieldValue,
+  type FileFieldValueInRequest,
+  isFileFieldValue,
+  isFileFieldValueInRequest,
+} from './file';
 import type { ExtensionValidator } from './validators/extension';
 import type { FileSizeValidator } from './validators/file_size';
 import type { ImageAspectRatioValidator } from './validators/image_aspect_ratio';
@@ -7,39 +16,63 @@ 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;
-}>;
+/**
+ * Gallery field type system - similar to File field but for arrays.
+ * See file.ts for detailed explanation of request/response duality.
+ */
 
+/**
+ * Individual gallery item types - extracted from File field types
+ */
+export type GalleryItem = NonNullable<FileFieldValue>;
+export type GalleryItemInRequest = NonNullable<FileFieldValueInRequest>;
+
+/**
+ * Gallery field value - response format with all metadata fields present
+ */
+export type GalleryFieldValue = Array<GalleryItem>;
+
+/**
+ * Gallery field value for API requests - metadata fields are optional
+ */
+export type GalleryFieldValueInRequest = Array<GalleryItemInRequest>;
+
+/**
+ * Type guard for Gallery field values - validates each item using File field validation
+ */
 export function isGalleryFieldValue(
   value: unknown,
 ): value is GalleryFieldValue {
-  return (
-    Array.isArray(value) &&
-    value.every(
-      (item) =>
-        typeof item === 'object' && item !== null && 'upload_id' in item,
-    )
-  );
+  return Array.isArray(value) && value.every(isFileFieldValue);
+}
+
+/**
+ * Type guard for Gallery field values in API request format
+ */
+export function isGalleryFieldValueInRequest(
+  value: unknown,
+): value is GalleryFieldValueInRequest {
+  return Array.isArray(value) && value.every(isFileFieldValueInRequest);
 }
 
 export function isLocalizedGalleryFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<GalleryFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isGalleryFieldValue)
   );
 }
 
+export function isLocalizedGalleryFieldValueInRequest(
+  value: unknown,
+): value is LocalizedFieldValue<GalleryFieldValueInRequest> {
+  return (
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isGalleryFieldValueInRequest)
+  );
+}
+
 export type GalleryFieldValidators = {
   /** Only accept a number of items within the specified range */
   size?: SizeValidator;

package/src/fieldTypes/index.ts

@@ -1,3 +1,4 @@
+export * from './appearance';
 export * from './boolean';
 export * from './color';
 export * from './date';
@@ -17,7 +18,5 @@ export * from './slug';
 export * from './string';
 export * from './structured_text';
 export * from './text';
-export * from './video';
-
-export * from './appearance';
 export * from './validators';
+export * from './video';

package/src/fieldTypes/integer.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { IntegerEditorConfiguration } from './appearance/integer';
 import type { NumberRangeValidator } from './validators/number_range';
 import type { RequiredValidator } from './validators/required';
@@ -15,8 +18,7 @@ export function isLocalizedIntegerFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<IntegerFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isIntegerFieldValue)
   );
 }

package/src/fieldTypes/json.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { JsonEditorConfiguration } from './appearance/json';
 import type { StringCheckboxGroupEditorConfiguration } from './appearance/string_checkbox_group';
 import type { StringMultiSelectEditorConfiguration } from './appearance/string_multi_select';
@@ -21,9 +24,7 @@ export function isLocalizedJsonFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<JsonFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isJsonFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isJsonFieldValue)
   );
 }
 

package/src/fieldTypes/lat_lon.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { MapEditorConfiguration } from './appearance/map';
 import type { RequiredValidator } from './validators/required';
 
@@ -21,8 +24,7 @@ export function isLocalizedLatLonFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<LatLonFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isLatLonFieldValue)
   );
 }

package/src/fieldTypes/link.ts

@@ -1,4 +1,8 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import { isValidId } from '../utilities/id';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { LinkEmbedEditorConfiguration } from './appearance/link_embed';
 import type { LinkSelectEditorConfiguration } from './appearance/link_select';
 import type { ItemItemTypeValidator } from './validators/item_item_type';
@@ -8,16 +12,14 @@ 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;
+  return (typeof value === 'string' && isValidId(value)) || value === null;
 }
 
 export function isLocalizedLinkFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<LinkFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isLinkFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isLinkFieldValue)
   );
 }
 

package/src/fieldTypes/links.ts

@@ -1,4 +1,8 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import { isValidId } from '../utilities/id';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { LinksEmbedEditorConfiguration } from './appearance/links_embed';
 import type { LinksSelectEditorConfiguration } from './appearance/links_select';
 import type { ItemsItemTypeValidator } from './validators/items_item_type';
@@ -8,7 +12,8 @@ export type LinksFieldValue = string[];
 
 export function isLinksFieldValue(value: unknown): value is LinksFieldValue {
   return (
-    Array.isArray(value) && value.every((item) => typeof item === 'string')
+    Array.isArray(value) &&
+    value.every((item) => typeof item === 'string' && isValidId(item))
   );
 }
 
@@ -16,8 +21,7 @@ export function isLocalizedLinksFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<LinksFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isLinksFieldValue)
   );
 }

package/src/fieldTypes/rich_text.ts

@@ -1,9 +1,13 @@
-import type * as RawApiTypes from '../generated/RawApiTypes';
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
-import type { ItemDefinition } from '../utilities/itemDefinition';
+import { isValidId } from '../utilities/id';
+import type { ItemTypeDefinition } from '../utilities/itemDefinition';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { RichTextEditorConfiguration } from './appearance/rich_text';
 import {
-  type BlockItemInARequest,
+  type BlockInNestedResponse,
+  type BlockInRequest,
   isItemId,
   isItemWithOptionalIdAndMeta,
   isItemWithOptionalMeta,
@@ -61,9 +65,9 @@ export type RichTextFieldValue = string[];
  * - RawApiTypes.Item: Full block object with ID (for updates)
  * - Omit<RawApiTypes.Item, 'id'>: Block object without ID (for creation)
  */
-export type RichTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
-> = BlockItemInARequest<D>[] | null;
+export type RichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInRequest<D>[] | null;
 
 /**
  * =============================================================================
@@ -78,9 +82,9 @@ export type RichTextFieldValueAsRequest<
 /**
  * Modular Content field value with nested blocks - array of fully populated block objects
  */
-export type RichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
-> = RawApiTypes.Item<D>[];
+export type RichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInNestedResponse<D>[];
 
 /**
  * =============================================================================
@@ -96,7 +100,8 @@ export function isRichTextFieldValue(
   value: unknown,
 ): value is RichTextFieldValue {
   return (
-    Array.isArray(value) && value.every((block) => typeof block === 'string')
+    Array.isArray(value) &&
+    value.every((block) => typeof block === 'string' && isValidId(block))
   );
 }
 
@@ -104,8 +109,7 @@ export function isLocalizedRichTextFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<RichTextFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isRichTextFieldValue)
   );
 }
@@ -114,9 +118,9 @@ export function isLocalizedRichTextFieldValue(
  * 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<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is RichTextFieldValueAsRequest<D> {
+export function isRichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is RichTextFieldValueInRequest<D> {
   if (value === null) return true;
 
   if (!Array.isArray(value)) return false;
@@ -130,15 +134,14 @@ export function isRichTextFieldValueAsRequest<
   });
 }
 
-export function isLocalizedRichTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedRichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueAsRequest<D>> {
+): value is LocalizedFieldValue<RichTextFieldValueInRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isRichTextFieldValueAsRequest)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isRichTextFieldValueInRequest)
   );
 }
 
@@ -146,9 +149,9 @@ export function isLocalizedRichTextFieldValueAsRequest<
  * Type guard for Modular Content field values with nested blocks (?nested=true format).
  * Ensures all blocks are full RawApiTypes.Item objects with complete data.
  */
-export function isRichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is RichTextFieldValueWithNestedBlocks<D> {
+export function isRichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is RichTextFieldValueInNestedResponse<D> {
   if (!Array.isArray(value)) return false;
 
   return value.every((block) => {
@@ -157,15 +160,14 @@ export function isRichTextFieldValueWithNestedBlocks<
   });
 }
 
-export function isLocalizedRichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedRichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks<D>> {
+): value is LocalizedFieldValue<RichTextFieldValueInNestedResponse<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isRichTextFieldValueWithNestedBlocks)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isRichTextFieldValueInNestedResponse)
   );
 }