@datocms/cma-client 5.1.10 → 5.1.12

package/src/fieldTypes/single_block.ts

@@ -1,6 +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,
+  ToItemAttributesInRequest,
+} 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';
@@ -52,17 +59,31 @@ export type SingleBlockFieldValue = string | null;
  */
 
 /** Represents an existing block in a CMA request */
-export type UnchangedBlockInARequest<
-  D extends ItemDefinition = ItemDefinition,
-> = RawApiTypes.Item<D>['id'];
+export type UnchangedBlockInRequest = RawApiTypes.ItemIdentity;
 
 /** Represents a block we want to update in a CMA request */
-export type UpdatedBlockInARequest<D extends ItemDefinition = ItemDefinition> =
-  D extends any ? OptionalFields<RawApiTypes.Item<D>, 'meta'> : never;
+export type UpdatedBlockInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = {
+  __itemTypeId?: D['itemTypeId'];
+  type: RawApiTypes.ItemType1;
+  id: RawApiTypes.ItemIdentity;
+  relationships?: RawApiTypes.ItemRelationships<D>;
+  meta?: RawApiTypes.ItemMeta;
+  attributes: ToItemAttributesInRequest<D>;
+};
 
 /** Represents a new block to create in a CMA request */
-export type NewBlockInARequest<D extends ItemDefinition = ItemDefinition> =
-  D extends any ? OptionalFields<RawApiTypes.Item<D>, 'id' | 'meta'> : never;
+export type NewBlockInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = {
+  __itemTypeId?: D['itemTypeId'];
+  type: RawApiTypes.ItemType1;
+  id?: RawApiTypes.ItemIdentity;
+  relationships: RawApiTypes.ItemRelationships<D>;
+  meta?: RawApiTypes.ItemMeta;
+  attributes: ToItemAttributesInRequest<D>;
+};
 
 /**
  * Union type representing the different ways a block can be specified in API requests:
@@ -72,10 +93,14 @@ export type NewBlockInARequest<D extends ItemDefinition = ItemDefinition> =
  *
  * Also, 'meta' can always be omitted
  */
-export type BlockItemInARequest<D extends ItemDefinition = ItemDefinition> =
-  | UnchangedBlockInARequest
-  | UpdatedBlockInARequest<D>
-  | NewBlockInARequest<D>;
+export type BlockInRequest<D extends ItemTypeDefinition = ItemTypeDefinition> =
+  | UnchangedBlockInRequest
+  | UpdatedBlockInRequest<D>
+  | NewBlockInRequest<D>;
+
+export type BlockInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = D extends unknown ? RawApiTypes.ItemInNestedResponse<D> : never;
 
 /**
  * Single Block field value for API requests - allows flexible block representations:
@@ -83,9 +108,9 @@ export type BlockItemInARequest<D extends ItemDefinition = ItemDefinition> =
  * - Full block object with ID (to update an existing block)
  * - Block object without ID (to create a new block)
  */
-export type SingleBlockFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
-> = BlockItemInARequest<D> | null;
+export type SingleBlockFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInRequest<D> | null;
 
 /**
  * =============================================================================
@@ -100,9 +125,9 @@ export type SingleBlockFieldValueAsRequest<
 /**
  * Single Block field value with nested block - fully populated block object
  */
-export type SingleBlockFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
-> = RawApiTypes.Item<D> | null;
+export type SingleBlockFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInNestedResponse<D> | null;
 
 /**
  * =============================================================================
@@ -119,31 +144,34 @@ export function isItemId(input: unknown): input is string {
 }
 
 export type ItemWithOptionalIdAndMeta<
-  D extends ItemDefinition = ItemDefinition,
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 > = D extends any ? OptionalFields<RawApiTypes.Item<D>, 'id' | 'meta'> : never;
 
 /**
  * Validates if the input is a RawApiTypes.Item object (with optional `id` and `meta`)
  */
 export function isItemWithOptionalIdAndMeta<
-  D extends ItemDefinition = ItemDefinition,
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(block: unknown): block is ItemWithOptionalIdAndMeta<D> {
   return (
     typeof block === 'object' &&
     block !== null &&
     'type' in block &&
-    'attributes' in block
+    block.type === 'item' &&
+    'attributes' in block &&
+    'relationships' in block
   );
 }
 
-export type ItemWithOptionalMeta<D extends ItemDefinition = ItemDefinition> =
-  D extends any ? OptionalFields<RawApiTypes.Item<D>, 'meta'> : never;
+export type ItemWithOptionalMeta<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = D extends any ? OptionalFields<RawApiTypes.Item<D>, 'meta'> : never;
 
 /**
  * Validates if the input is a a complete RawApiTypes.Item object with optional `meta`
  */
 export function isItemWithOptionalMeta<
-  D extends ItemDefinition = ItemDefinition,
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(block: unknown): block is ItemWithOptionalMeta<D> {
   return (
     isItemWithOptionalIdAndMeta(block) &&
@@ -165,15 +193,14 @@ export function isItemWithOptionalMeta<
 export function isSingleBlockFieldValue(
   value: unknown,
 ): value is SingleBlockFieldValue {
-  return typeof value === 'string' || value === null;
+  return (typeof value === 'string' && isValidId(value)) || value === null;
 }
 
 export function isLocalizedSingleBlockFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<SingleBlockFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isSingleBlockFieldValue)
   );
 }
@@ -182,9 +209,9 @@ export function isLocalizedSingleBlockFieldValue(
  * Type guard for Single Block field values in API request format.
  * Allows block as string ID, full object with ID, or object without ID.
  */
-export function isSingleBlockFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is SingleBlockFieldValueAsRequest<D> {
+export function isSingleBlockFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is SingleBlockFieldValueInRequest<D> {
   if (value === null) return true;
 
   // String ID - referencing existing block
@@ -194,15 +221,14 @@ export function isSingleBlockFieldValueAsRequest<
   return isItemWithOptionalIdAndMeta(value);
 }
 
-export function isLocalizedSingleBlockFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedSingleBlockFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<SingleBlockFieldValueAsRequest<D>> {
+): value is LocalizedFieldValue<SingleBlockFieldValueInRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isSingleBlockFieldValueAsRequest)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isSingleBlockFieldValueInRequest)
   );
 }
 
@@ -210,24 +236,23 @@ export function isLocalizedSingleBlockFieldValueAsRequest<
  * Type guard for Single Block field values with nested blocks (?nested=true format).
  * Ensures block is a full RawApiTypes.Item object with complete data.
  */
-export function isSingleBlockFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is SingleBlockFieldValueWithNestedBlocks<D> {
+export function isSingleBlockFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is SingleBlockFieldValueInNestedResponse<D> {
   if (value === null) return true;
 
   // Must be a full object with ID (nested format always includes complete block objects)
   return isItemWithOptionalMeta(value);
 }
 
-export function isLocalizedSingleBlockFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedSingleBlockFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<SingleBlockFieldValueWithNestedBlocks<D>> {
+): value is LocalizedFieldValue<SingleBlockFieldValueInNestedResponse<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isSingleBlockFieldValueWithNestedBlocks)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isSingleBlockFieldValueInNestedResponse)
   );
 }
 

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

@@ -8,12 +8,16 @@ import {
   isDocument,
   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 { isValidId } from '../utilities/id';
+import type { ItemTypeDefinition } from '../utilities/itemDefinition';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { StructuredTextEditorConfiguration } from './appearance/structured_text';
 import {
-  type BlockItemInARequest,
+  type BlockInNestedResponse,
+  type BlockInRequest,
   isItemId,
   isItemWithOptionalIdAndMeta,
   isItemWithOptionalMeta,
@@ -57,25 +61,26 @@ import type { StructuredTextLinksValidator } from './validators/structured_text_
 /**
  * Variant of 'block' structured text node for API requests
  */
-export type BlockAsRequest<D extends ItemDefinition = ItemDefinition> = Block<
-  BlockItemInARequest<D>
->;
+export type BlockNodeInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = Block<BlockInRequest<D>>;
 
 /**
  * Variant of 'inlineBlock' structured text node for API requests
  */
-export type InlineBlockAsRequest<D extends ItemDefinition = ItemDefinition> =
-  InlineBlock<BlockItemInARequest<D>>;
+export type InlineBlockNodeInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = InlineBlock<BlockInRequest<D>>;
 
 /**
  * Variant of Structured Text document for API requests
  */
-export type DocumentAsRequest<
-  BlockItemDefinition extends ItemDefinition = ItemDefinition,
-  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+export type DocumentInRequest<
+  BlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+  InlineBlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
 > = Document<
-  BlockItemInARequest<BlockItemDefinition>,
-  BlockItemInARequest<InlineBlockItemDefinition>
+  BlockInRequest<BlockItemTypeDefinition>,
+  BlockInRequest<InlineBlockItemTypeDefinition>
 >;
 
 /**
@@ -91,25 +96,26 @@ export type DocumentAsRequest<
 /**
  * Variant of 'block' structured text node for ?nested=true API responses
  */
-export type BlockWithNestedBlocks<D extends ItemDefinition = ItemDefinition> =
-  Block<RawApiTypes.Item<D>>;
+export type BlockNodeInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = Block<BlockInNestedResponse<D>>;
 
 /**
  * Variant of 'inlineBlock' structured text node for ?nested=true API responses
  */
-export type InlineBlockWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
-> = InlineBlock<RawApiTypes.Item<D>>;
+export type InlineBlockNodeInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = InlineBlock<BlockInNestedResponse<D>>;
 
 /**
  * Variant of Structured Text document for ?nested=true API responses
  */
-export type DocumentWithNestedBlocks<
-  BlockItemDefinition extends ItemDefinition = ItemDefinition,
-  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+export type DocumentInNestedResponse<
+  BlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+  InlineBlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
 > = Document<
-  RawApiTypes.Item<BlockItemDefinition>,
-  RawApiTypes.Item<InlineBlockItemDefinition>
+  BlockInNestedResponse<BlockItemTypeDefinition>,
+  BlockInNestedResponse<InlineBlockItemTypeDefinition>
 >;
 
 /**
@@ -123,16 +129,19 @@ export type DocumentWithNestedBlocks<
  * Can be null (empty field) or a document with blocks as string IDs
  */
 export type StructuredTextFieldValue = Document | null;
-export type StructuredTextFieldValueAsRequest<
-  BlockItemDefinition extends ItemDefinition = ItemDefinition,
-  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
-> = DocumentAsRequest<BlockItemDefinition, InlineBlockItemDefinition> | null;
-export type StructuredTextFieldValueWithNestedBlocks<
-  BlockItemDefinition extends ItemDefinition = ItemDefinition,
-  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
-> = DocumentWithNestedBlocks<
-  BlockItemDefinition,
-  InlineBlockItemDefinition
+export type StructuredTextFieldValueInRequest<
+  BlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+  InlineBlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+> = DocumentInRequest<
+  BlockItemTypeDefinition,
+  InlineBlockItemTypeDefinition
+> | null;
+export type StructuredTextFieldValueInNestedResponse<
+  BlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+  InlineBlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+> = DocumentInNestedResponse<
+  BlockItemTypeDefinition,
+  InlineBlockItemTypeDefinition
 > | null;
 
 /**
@@ -168,7 +177,7 @@ export function isStructuredTextFieldValue(
 
   // Check that all block/inlineBlock nodes have string item IDs
   return validateAllBlockNodes(value.document, (node) => {
-    return typeof node.item === 'string';
+    return typeof node.item === 'string' && isValidId(node.item);
   });
 }
 
@@ -176,8 +185,7 @@ export function isLocalizedStructuredTextFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<StructuredTextFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isStructuredTextFieldValue)
   );
 }
@@ -186,14 +194,14 @@ export function isLocalizedStructuredTextFieldValue(
  * Type guard for structured text field values in API request format.
  * Allows blocks as string IDs, full objects with IDs, or objects without IDs.
  */
-export function isStructuredTextFieldValueAsRequest<
-  BlockItemDefinition extends ItemDefinition = ItemDefinition,
-  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+export function isStructuredTextFieldValueInRequest<
+  BlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
+  InlineBlockItemTypeDefinition extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is StructuredTextFieldValueAsRequest<
-  BlockItemDefinition,
-  InlineBlockItemDefinition
+): value is StructuredTextFieldValueInRequest<
+  BlockItemTypeDefinition,
+  InlineBlockItemTypeDefinition
 > {
   if (value === null) return true;
 
@@ -213,15 +221,14 @@ export function isStructuredTextFieldValueAsRequest<
   });
 }
 
-export function isLocalizedStructuredTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedStructuredTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<StructuredTextFieldValueAsRequest<D>> {
+): value is LocalizedFieldValue<StructuredTextFieldValueInRequest<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isStructuredTextFieldValueAsRequest)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isStructuredTextFieldValueInRequest)
   );
 }
 
@@ -229,9 +236,9 @@ export function isLocalizedStructuredTextFieldValueAsRequest<
  * Type guard for structured text field values with nested blocks (?nested=true format).
  * Ensures all block/inlineBlock nodes have full RawApiTypes.Item objects.
  */
-export function isStructuredTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is StructuredTextFieldValueWithNestedBlocks<D> {
+export function isStructuredTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is StructuredTextFieldValueInNestedResponse<D> {
   if (value === null) return true;
 
   if (!isDocument<unknown>(value)) {
@@ -247,15 +254,14 @@ export function isStructuredTextFieldValueWithNestedBlocks<
   });
 }
 
-export function isLocalizedStructuredTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedStructuredTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<StructuredTextFieldValueWithNestedBlocks<D>> {
+): value is LocalizedFieldValue<StructuredTextFieldValueInNestedResponse<D>> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isStructuredTextFieldValueWithNestedBlocks)
+    isLocalizedFieldValue(value) &&
+    Object.values(value).every(isStructuredTextFieldValueInNestedResponse)
   );
 }
 

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)
   );
 }