@datocms/cma-client 5.1.10 → 5.1.11

package/src/fieldTypes/file.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { FileEditorConfiguration } from './appearance/file';
 import type { ExtensionValidator } from './validators/extension';
 import type { FileSizeValidator } from './validators/file_size';
@@ -7,7 +10,63 @@ import type { ImageDimensionsValidator } from './validators/image_dimensions';
 import type { RequiredValidator } from './validators/required';
 import type { RequiredAltTitleValidator } from './validators/required_alt_title';
 
+/**
+ * FILE FIELD TYPE SYSTEM FOR DATOCMS
+ *
+ * This module defines a comprehensive type system for handling DatoCMS File fields,
+ * which contain file uploads with optional metadata like alt text, title, custom data, and focal points.
+ *
+ * The challenge we're solving:
+ * - DatoCMS File fields can have optional metadata fields (alt, title, custom_data, focal_point)
+ * - For API requests, all these fields are optional and can be omitted
+ * - For API responses, DatoCMS provides default values for missing fields:
+ *   - alt: null
+ *   - title: null
+ *   - custom_data: {}
+ *   - focal_point: null
+ * - This creates a need for different type variants for the same conceptual data structure
+ *
+ * This module provides separate types for:
+ * 1. API request format (optional metadata fields)
+ * 2. API response format (all fields present with defaults)
+ */
+
+/**
+ * =============================================================================
+ * BASIC FILE TYPE - Default API response format
+ * =============================================================================
+ *
+ * The standard File field value with all metadata fields present and default values applied.
+ * This is what you get from API responses where DatoCMS has applied default values.
+ */
+
+/**
+ * Basic File field value - all metadata fields present with defaults applied
+ */
 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;
+
+/**
+ * =============================================================================
+ * REQUEST VARIANT - Type for sending data TO the DatoCMS API
+ * =============================================================================
+ *
+ * When making API requests, metadata fields are optional and can be omitted.
+ * DatoCMS will apply default values for any missing fields in the response.
+ */
+
+/**
+ * File field value for API requests - metadata fields are optional
+ */
+export type FileFieldValueAsRequest = {
   upload_id: string;
   alt?: string | null;
   title?: string | null;
@@ -18,7 +77,35 @@ export type FileFieldValue = {
   } | null;
 } | null;
 
+/**
+ * =============================================================================
+ * TYPE GUARDS - Runtime validation functions
+ * =============================================================================
+ */
+
+/**
+ * Type guard for basic File field values (response format with all fields present).
+ * Validates that all required metadata fields are present.
+ */
 export function isFileFieldValue(value: unknown): value is FileFieldValue {
+  if (value === null) return true;
+  return (
+    isLocalizedFieldValue(value) &&
+    'upload_id' in value &&
+    'alt' in value &&
+    'title' in value &&
+    'custom_data' in value &&
+    'focal_point' in value
+  );
+}
+
+/**
+ * Type guard for File field values in API request format.
+ * Allows metadata fields to be optional or omitted.
+ */
+export function isFileFieldValueAsRequest(
+  value: unknown,
+): value is FileFieldValueAsRequest {
   if (value === null) return true;
   return typeof value === 'object' && value !== null && 'upload_id' in value;
 }
@@ -27,9 +114,16 @@ export function isLocalizedFileFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<FileFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isFileFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isFileFieldValue)
+  );
+}
+
+export function isLocalizedFileFieldValueAsRequest(
+  value: unknown,
+): value is LocalizedFieldValue<FileFieldValueAsRequest> {
+  return (
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isFileFieldValueAsRequest)
   );
 }
 

package/src/fieldTypes/float.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { FloatEditorConfiguration } from './appearance/float';
 import type { NumberRangeValidator } from './validators/number_range';
 import type { RequiredValidator } from './validators/required';
@@ -13,8 +16,7 @@ export function isLocalizedFloatFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<FloatFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isFloatFieldValue)
   );
 }

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 FileFieldValueAsRequest,
+  isFileFieldValue,
+  isFileFieldValueAsRequest,
+} 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 GalleryItemAsRequest = NonNullable<FileFieldValueAsRequest>;
+
+/**
+ * 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 GalleryFieldValueAsRequest = Array<GalleryItemAsRequest>;
+
+/**
+ * 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 isGalleryFieldValueAsRequest(
+  value: unknown,
+): value is GalleryFieldValueAsRequest {
+  return Array.isArray(value) && value.every(isFileFieldValueAsRequest);
 }
 
 export function isLocalizedGalleryFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<GalleryFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isGalleryFieldValue)
   );
 }
 
+export function isLocalizedGalleryFieldValueAsRequest(
+  value: unknown,
+): value is LocalizedFieldValue<GalleryFieldValueAsRequest> {
+  return (
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isGalleryFieldValueAsRequest)
+  );
+}
+
 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,6 +1,9 @@
 import type * as RawApiTypes from '../generated/RawApiTypes';
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { ItemDefinition } from '../utilities/itemDefinition';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { RichTextEditorConfiguration } from './appearance/rich_text';
 import {
   type BlockItemInARequest,
@@ -104,8 +107,7 @@ export function isLocalizedRichTextFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<RichTextFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isRichTextFieldValue)
   );
 }
@@ -136,8 +138,7 @@ export function isLocalizedRichTextFieldValueAsRequest<
   value: unknown,
 ): value is LocalizedFieldValue<RichTextFieldValueAsRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isRichTextFieldValueAsRequest)
   );
 }
@@ -163,8 +164,7 @@ export function isLocalizedRichTextFieldValueWithNestedBlocks<
   value: unknown,
 ): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isRichTextFieldValueWithNestedBlocks)
   );
 }

package/src/fieldTypes/seo.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { SeoEditorConfiguration } from './appearance/seo';
 import type { DescriptionLengthValidator } from './validators/description_length';
 import type { FileSizeValidator } from './validators/file_size';
@@ -32,9 +35,7 @@ export function isLocalizedSeoFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<SeoFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isSeoFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isSeoFieldValue)
   );
 }
 

package/src/fieldTypes/single_block.ts

@@ -1,6 +1,9 @@
 import type * as RawApiTypes from '../generated/RawApiTypes';
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { ItemDefinition } from '../utilities/itemDefinition';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 
 import type { FramedSingleBlockEditorConfiguration } from './appearance/framed_single_block';
 import type { FramelessSingleBlockEditorConfiguration } from './appearance/frameless_single_block';
@@ -132,7 +135,9 @@ export function isItemWithOptionalIdAndMeta<
     typeof block === 'object' &&
     block !== null &&
     'type' in block &&
-    'attributes' in block
+    block.type === 'item' &&
+    'attributes' in block &&
+    'relationships' in block
   );
 }
 
@@ -172,8 +177,7 @@ export function isLocalizedSingleBlockFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<SingleBlockFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isSingleBlockFieldValue)
   );
 }
@@ -200,8 +204,7 @@ export function isLocalizedSingleBlockFieldValueAsRequest<
   value: unknown,
 ): value is LocalizedFieldValue<SingleBlockFieldValueAsRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isSingleBlockFieldValueAsRequest)
   );
 }
@@ -225,8 +228,7 @@ export function isLocalizedSingleBlockFieldValueWithNestedBlocks<
   value: unknown,
 ): value is LocalizedFieldValue<SingleBlockFieldValueWithNestedBlocks<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isSingleBlockFieldValueWithNestedBlocks)
   );
 }

package/src/fieldTypes/slug.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { SlugEditorConfiguration } from './appearance/slug';
 import type { LengthValidator } from './validators/length';
 import type { RequiredValidator } from './validators/required';
@@ -16,9 +19,7 @@ export function isLocalizedSlugFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<SlugFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isSlugFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isSlugFieldValue)
   );
 }
 

package/src/fieldTypes/string.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { SingleLineEditorConfiguration } from './appearance/single_line';
 import type { StringRadioGroupEditorConfiguration } from './appearance/string_radio_group';
 import type { StringSelectEditorConfiguration } from './appearance/string_select';
@@ -18,8 +21,7 @@ export function isLocalizedStringFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<StringFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isStringFieldValue)
   );
 }

package/src/fieldTypes/structured_text.ts

@@ -9,8 +9,11 @@ import {
   isInlineBlock,
 } from 'datocms-structured-text-utils';
 import type * as RawApiTypes from '../generated/RawApiTypes';
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { ItemDefinition } from '../utilities/itemDefinition';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { StructuredTextEditorConfiguration } from './appearance/structured_text';
 import {
   type BlockItemInARequest,
@@ -176,8 +179,7 @@ export function isLocalizedStructuredTextFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<StructuredTextFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isStructuredTextFieldValue)
   );
 }
@@ -219,8 +221,7 @@ export function isLocalizedStructuredTextFieldValueAsRequest<
   value: unknown,
 ): value is LocalizedFieldValue<StructuredTextFieldValueAsRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isStructuredTextFieldValueAsRequest)
   );
 }
@@ -253,8 +254,7 @@ export function isLocalizedStructuredTextFieldValueWithNestedBlocks<
   value: unknown,
 ): value is LocalizedFieldValue<StructuredTextFieldValueWithNestedBlocks<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isStructuredTextFieldValueWithNestedBlocks)
   );
 }

package/src/fieldTypes/text.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { MarkdownEditorConfiguration } from './appearance/markdown';
 import type { TextareaEditorConfiguration } from './appearance/textarea';
 import type { WysiwygEditorConfiguration } from './appearance/wysiwyg';
@@ -17,9 +20,7 @@ export function isLocalizedTextFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<TextFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isTextFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isTextFieldValue)
   );
 }
 

package/src/fieldTypes/video.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { VideoEditorConfiguration } from './appearance/video';
 import type { RequiredValidator } from './validators/required';
 
@@ -27,8 +30,7 @@ export function isLocalizedVideoFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<VideoFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isVideoFieldValue)
   );
 }

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.1.10',
+      userAgent: '@datocms/cma-client v5.1.11',
       baseUrl: this.baseUrl,
       preCallStack: new Error().stack,
       extraHeaders: {

package/src/index.ts

@@ -1,17 +1,17 @@
 export { ApiError, LogLevel, TimeoutError } from '@datocms/rest-client-utils';
 export * from './buildClient';
+export * from './fieldTypes';
 export { Client } from './generated/Client';
 export type { ClientConfigOptions } from './generated/Client';
 export * as Resources from './generated/resources';
-export * from './utilities/blocks';
 export * from './utilities/buildBlockRecord';
 export * from './utilities/fieldsContainingReferences';
-export * from './utilities/fieldValue';
 export * from './utilities/id';
+export * from './utilities/inspectItem';
+export * from './utilities/itemDefinition';
+export * from './utilities/normalizedFieldValues';
 export * from './utilities/recursiveBlocks';
 export * from './utilities/schemaRepository';
-export * from './utilities/itemDefinition';
-export * from './fieldTypes';
 export type { ApiTypes, RawApiTypes };
 // Legacy names
 export type { ApiTypes as SchemaTypes, RawApiTypes as SimpleSchemaTypes };