@datocms/cma-client 5.1.0 → 5.1.2

package/src/fieldTypes/rich_text.ts

@@ -1,9 +1,9 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
 import {
   type BlockItemInARequest,
-  isBlockObject,
-  isBlockObjectWithId,
-  isBlockStringId,
+  isItemId,
+  isItemWithOptionalIdAndMeta,
+  isItemWithOptionalMeta,
 } from './single_block';
 
 /**
@@ -53,8 +53,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 +64,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 RichTextFieldValueWithResolvedBlocks = SchemaTypes.Item[] | null;
+export type RichTextFieldValueWithNestedBlocks = RawApiTypes.Item[] | null;
 
 /**
  * =============================================================================
@@ -106,27 +106,27 @@ 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);
   });
 }
 
 /**
  * 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 isRichTextFieldValueWithResolvedBlocks(
+export function isRichTextFieldValueWithNestedBlocks(
   value: unknown,
-): value is RichTextFieldValueWithResolvedBlocks {
+): value is RichTextFieldValueWithNestedBlocks {
   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);
+    return isItemWithOptionalMeta(block);
   });
 }
 

package/src/fieldTypes/single_block.ts

@@ -1,4 +1,9 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
+
+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 +49,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 +86,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 SingleBlockFieldValueWithResolvedBlocks = SchemaTypes.Item | null;
+export type SingleBlockFieldValueWithNestedBlocks = RawApiTypes.Item | null;
 
 /**
  * =============================================================================
@@ -87,21 +103,21 @@ export type SingleBlockFieldValueWithResolvedBlocks = 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 +128,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'
+  );
 }
 
 /**
@@ -148,31 +168,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);
 }
 
 /**
  * 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 isSingleBlockFieldValueWithResolvedBlocks(
+export function isSingleBlockFieldValueWithNestedBlocks(
   value: unknown,
-): value is SingleBlockFieldValueWithResolvedBlocks {
+): value is SingleBlockFieldValueWithNestedBlocks {
   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 type SingleBlockFieldValidators = {
   /** Only accept references to block records of the specified block models */
   single_block_blocks: SingleBlockBlocksValidator;

package/src/fieldTypes/structured_text.ts

@@ -2,19 +2,24 @@ import {
   type Block,
   type Document,
   type InlineBlock,
-  type Root,
+  type Node,
+  everyNode,
   isBlock,
+  isDocument,
   isInlineBlock,
-  isNode,
 } from 'datocms-structured-text-utils';
-import type * as SchemaTypes from '../generated/SchemaTypes';
-import { everyNode } from '../utilities/structuredText';
+import type * as RawApiTypes from '../generated/RawApiTypes';
+import type { StructuredTextEditorConfiguration } from './appearance/structured_text';
 import {
   type BlockItemInARequest,
-  isBlockObject,
-  isBlockObjectWithId,
-  isBlockStringId,
+  isItemId,
+  isItemWithOptionalIdAndMeta,
+  isItemWithOptionalMeta,
 } from './single_block';
+import type { LengthValidator } from './validators/length';
+import type { StructuredTextBlocksValidator } from './validators/structured_text_blocks';
+import type { StructuredTextInlineBlocksValidator } from './validators/structured_text_inline_blocks';
+import type { StructuredTextLinksValidator } from './validators/structured_text_links';
 
 /**
  * STRUCTURED TEXT TYPE SYSTEM FOR DATOCMS
@@ -25,10 +30,10 @@ import {
  * The challenge we're solving:
  * - DatoCMS structured text can contain "blocks" (embedded content items) in bloth 'block'
  *   and 'inlineBlock' nodes
- * - By default, API responses contain blocks as string IDs (lightweight references)
+ * - By default, CMA responses contain blocks as string IDs (lightweight references)
  * - With ?nested=true parameter though, API responses contain blocks as full item objects
  *   (which in turn can contain other blocks)
- * - For API requests, blocks can be represented as:
+ * - For CMA requests, blocks can be represented as:
  *   1. String IDs (referencing existing items)
  *   2. Full item objects with IDs (for updates)
  *   3. Item objects without IDs (for creation)
@@ -50,80 +55,42 @@ import {
 /**
  * Variant of 'block' structured text node for API requests
  */
-export type BlockAsRequest = Omit<Block, 'item'> & {
-  item: BlockItemInARequest;
-};
+export type BlockAsRequest = Block<BlockItemInARequest>;
 
 /**
  * Variant of 'inlineBlock' structured text node for API requests
  */
-export type InlineBlockAsRequest = Omit<InlineBlock, 'item'> & {
-  item: BlockItemInARequest;
-};
-
-/**
- * Generic type to transform a node that might be containing a 'block' or 'inlineBlock' as a (deeply nested) children to its variant for API requests
- */
-export type NodeAsRequest<T> = WithMappedChildren<
-  T,
-  DeepMapVariants<
-    T extends { children: infer C } ? C : never,
-    BlockAsRequest,
-    InlineBlockAsRequest
-  >
->;
+export type InlineBlockAsRequest = InlineBlock<BlockItemInARequest>;
 
 /**
  * Variant of Structured Text document for API requests
  */
-export type DocumentAsRequest = {
-  schema: 'dast';
-  document: NodeAsRequest<Root>;
-};
+export type DocumentAsRequest = Document<BlockItemInARequest>;
 
 /**
  * =============================================================================
  * NESTED VARIANTS - Types for API responses with ?nested=true parameter
  * =============================================================================
  *
- * When using the GET /items?nested=true, the API returns Structured Text documents
- * with embedded blocks fully populated as complete SchemaTypes.Item objects instead
+ * When using the GET /items?nested=true, the CMA returns Structured Text documents
+ * with embedded blocks fully populated as complete RawApiTypes.Item objects instead
  * of just string IDs.
  */
 
 /**
  * Variant of 'block' structured text node for ?nested=true API responses
  */
-export type BlockWithResolvedBlocks = Omit<Block, 'item'> & {
-  item: SchemaTypes.Item;
-};
+export type BlockWithNestedBlocks = Block<RawApiTypes.Item>;
 
 /**
  * Variant of 'inlineBlock' structured text node for ?nested=true API responses
  */
-export type InlineBlockWithResolvedBlocks = Omit<InlineBlock, 'item'> & {
-  item: SchemaTypes.Item;
-};
-
-/**
- * Generic type to transform a node that might be containing a 'block' or 'inlineBlock' as a (deeply nested) children to it's variant for ?nested=true API responses
- */
-export type NodeWithResolvedBlocks<T> = WithMappedChildren<
-  T,
-  DeepMapVariants<
-    T extends { children: infer C } ? C : never,
-    BlockWithResolvedBlocks,
-    InlineBlockWithResolvedBlocks
-  >
->;
+export type InlineBlockWithNestedBlocks = InlineBlock<RawApiTypes.Item>;
 
 /**
  * Variant of Structured Text document for ?nested=true API responses
  */
-export type DocumentWithResolvedBlocks = {
-  schema: 'dast';
-  document: NodeWithResolvedBlocks<Root>;
-};
+export type DocumentWithNestedBlocks = Document<RawApiTypes.Item>;
 
 /**
  * =============================================================================
@@ -137,46 +104,20 @@ export type DocumentWithResolvedBlocks = {
  */
 export type StructuredTextFieldValue = Document | null;
 export type StructuredTextFieldValueAsRequest = DocumentAsRequest | null;
-export type StructuredTextFieldValueWithResolvedBlocks =
-  DocumentWithResolvedBlocks | null;
-
-/**
- * Helper function to validate if a value has the expected structured text document structure.
- * Checks for the presence of 'schema' and 'document' properties on a non-null object.
- */
-function isValidDocumentStructure(
-  value: unknown,
-): value is { schema: unknown; document: unknown } {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'schema' in value &&
-    'document' in value
-  );
-}
+export type StructuredTextFieldValueWithNestedBlocks =
+  DocumentWithNestedBlocks | null;
 
 /**
  * Utility function to validate all block/inlineBlock nodes in a structured text document tree.
  * Calls the provided callback for each block/inlineBlock node found and returns true only if all pass.
  */
-function validateAllBlockNodes(
-  node: unknown,
-  callback: (
-    node:
-      | Block
-      | BlockAsRequest
-      | BlockWithResolvedBlocks
-      | InlineBlock
-      | InlineBlockAsRequest
-      | InlineBlockWithResolvedBlocks,
-  ) => boolean,
+function validateAllBlockNodes<T>(
+  node: Node<T>,
+  callback: (node: Block<T> | InlineBlock<T>) => boolean,
 ): boolean {
   return everyNode(node, (currentNode) => {
     // If this is a block or inlineBlock node, validate it with the callback
-    if (
-      isNode(currentNode) &&
-      (isBlock(currentNode) || isInlineBlock(currentNode))
-    ) {
+    if (isBlock<T>(currentNode) || isInlineBlock<T>(currentNode)) {
       return callback(currentNode);
     }
     // For all other node types, they're valid by default
@@ -193,7 +134,7 @@ export function isStructuredTextFieldValue(
 ): value is StructuredTextFieldValue {
   if (value === null) return true;
 
-  if (!isValidDocumentStructure(value)) {
+  if (!isDocument<unknown>(value)) {
     return false;
   }
 
@@ -212,7 +153,7 @@ export function isStructuredTextFieldValueAsRequest(
 ): value is StructuredTextFieldValueAsRequest {
   if (value === null) return true;
 
-  if (!isValidDocumentStructure(value)) {
+  if (!isDocument<unknown>(value)) {
     return false;
   }
 
@@ -221,23 +162,23 @@ export function isStructuredTextFieldValueAsRequest(
     const item = node.item;
 
     // String ID
-    if (isBlockStringId(item)) return true;
+    if (isItemId(item)) return true;
 
     // Object (either with or without ID)
-    return isBlockObject(item);
+    return isItemWithOptionalIdAndMeta(item);
   });
 }
 
 /**
  * Type guard for structured text field values with nested blocks (?nested=true format).
- * Ensures all block/inlineBlock nodes have full SchemaTypes.Item objects.
+ * Ensures all block/inlineBlock nodes have full RawApiTypes.Item objects.
  */
-export function isStructuredTextFieldValueWithResolvedBlocks(
+export function isStructuredTextFieldValueWithNestedBlocks(
   value: unknown,
-): value is StructuredTextFieldValueWithResolvedBlocks {
+): value is StructuredTextFieldValueWithNestedBlocks {
   if (value === null) return true;
 
-  if (!isValidDocumentStructure(value)) {
+  if (!isDocument<unknown>(value)) {
     return false;
   }
 
@@ -246,67 +187,10 @@ export function isStructuredTextFieldValueWithResolvedBlocks(
     const item = node.item;
 
     // Must be a full object with ID (nested format always includes full items)
-    return isBlockObjectWithId(item);
+    return isItemWithOptionalMeta(item);
   });
 }
 
-/**
- * =============================================================================
- * SHARED TRANSFORMATION UTILITIES
- * =============================================================================
- *
- * These utility types provide the machinery for automatically transforming
- * structured text types between their different variants. The goal is to
- * recursively walk through complex nested structures and apply the appropriate
- * transformations to Block and InlineBlock nodes while preserving all other types.
- */
-
-/**
- * Utility type that preserves the structure of T but replaces its children with ChildrenType.
- * If T doesn't have children, it returns T unchanged.
- */
-type WithMappedChildren<T, ChildrenType> = T extends { children: any }
-  ? Omit<T, 'children'> & { children: ChildrenType }
-  : T;
-
-/**
- * Generic transformation type that replace 'block' and 'inlineBlock' node types to their variants.
- */
-type MapVariants<T, BlockVariant, InlineBlockVariant> = T extends Block
-  ? BlockVariant
-  : T extends InlineBlock
-    ? InlineBlockVariant
-    : T;
-
-/**
- * Recursively transform a Structured Text node type using the provided variants for 'block' and 'inlineBlock' nodes.
- *
- * This handles three cases:
- * _ Arrays: Transform each array element recursively
- * _ Objects with children: Transform the object itself AND recursively transform its children
- * _ Leaf nodes: Apply the variant mapping
- */
-type DeepMapVariants<T, BlockVariant, InlineBlockVariant> =
-  T extends (infer U)[]
-    ? DeepMapVariants<U, BlockVariant, InlineBlockVariant>[]
-    : T extends { children: infer Children }
-      ? T extends { children: any }
-        ? Omit<T, 'children'> & {
-            children: DeepMapVariants<
-              Children,
-              BlockVariant,
-              InlineBlockVariant
-            >;
-          }
-        : MapVariants<T, BlockVariant, InlineBlockVariant>
-      : MapVariants<T, BlockVariant, InlineBlockVariant>;
-
-import type { StructuredTextEditorConfiguration } from './appearance/structured_text';
-import type { LengthValidator } from './validators/length';
-import type { StructuredTextBlocksValidator } from './validators/structured_text_blocks';
-import type { StructuredTextInlineBlocksValidator } from './validators/structured_text_inline_blocks';
-import type { StructuredTextLinksValidator } from './validators/structured_text_links';
-
 export type StructuredTextFieldValidators = {
   /** Only accept references to block records of the specified block models */
   structured_text_blocks: StructuredTextBlocksValidator;

package/src/generated/{SimpleSchemaTypes.ts → ApiTypes.ts}

@@ -58,7 +58,7 @@ type FieldAppearanceConfig<TAppearance> = TAppearance &
   Omit<RawFieldAttributes['appearance'], keyof TAppearance>;
 
 /**
- * Base field configuration for attributes (non-localized), extending the original SchemaTypes
+ * Base field configuration for attributes (non-localized), extending the original RawApiTypes
  */
 type NonLocalizedFieldAttributesForFieldType<
   SourceType,
@@ -78,7 +78,7 @@ type NonLocalizedFieldAttributesForFieldType<
 };
 
 /**
- * Base field configuration for attributes (localized), extending the original SchemaTypes
+ * Base field configuration for attributes (localized), extending the original RawApiTypes
  */
 type LocalizedFieldAttributesForFieldType<
   SourceType,
@@ -278,12 +278,24 @@ export type FieldAttributes = GenericFieldAttributes<RawFieldAttributes>;
 
 export type Field = GenericFieldAttributes<RawField>;
 
-/**
- * Helper type to conditionally handle default values based on localization for field creation
- */
-type FieldCreateDefaultValue<T> = T | Record<string, T> | undefined;
+type LocalizedFieldCreateConfigForFieldType<
+  SourceType,
+  FieldType extends RawFieldAttributes['field_type'],
+  FieldValue,
+  FieldValidators,
+  FieldAppearance,
+> = Omit<
+  SourceType,
+  'field_type' | 'default_value' | 'validators' | 'appearance' | 'localized'
+> & {
+  field_type: FieldType;
+  localized: true;
+  default_value?: Record<string, FieldValue>;
+  validators?: FieldValidators;
+  appearance?: FieldAppearanceConfig<FieldAppearance>;
+};
 
-type FieldCreateConfigForFieldType<
+type NonLocalizedFieldCreateConfigForFieldType<
   SourceType,
   FieldType extends RawFieldAttributes['field_type'],
   FieldValue,
@@ -291,14 +303,37 @@ type FieldCreateConfigForFieldType<
   FieldAppearance,
 > = Omit<
   SourceType,
-  'field_type' | 'default_value' | 'validators' | 'appearance'
+  'field_type' | 'default_value' | 'validators' | 'appearance' | 'localized'
 > & {
   field_type: FieldType;
-  default_value?: FieldCreateDefaultValue<FieldValue>;
+  localized?: false;
+  default_value?: FieldValue;
   validators?: FieldValidators;
   appearance?: FieldAppearanceConfig<FieldAppearance>;
 };
 
+type FieldCreateConfigForFieldType<
+  SourceType,
+  FieldType extends RawFieldAttributes['field_type'],
+  FieldValue,
+  FieldValidators,
+  FieldAppearance,
+> =
+  | LocalizedFieldCreateConfigForFieldType<
+      SourceType,
+      FieldType,
+      FieldValue,
+      FieldValidators,
+      FieldAppearance
+    >
+  | NonLocalizedFieldCreateConfigForFieldType<
+      SourceType,
+      FieldType,
+      FieldValue,
+      FieldValidators,
+      FieldAppearance
+    >;
+
 type FieldCreateConfig<SourceType> =
   | FieldCreateConfigForFieldType<
       SourceType,

package/src/generated/Client.ts

@@ -3,7 +3,7 @@ import {
   pollJobResult,
   request,
 } from '@datocms/rest-client-utils';
-import type { JobResult } from './SimpleSchemaTypes';
+import type { JobResult } from './ApiTypes';
 import * as Resources from './resources';
 
 export type RequestOptions = {
@@ -147,7 +147,7 @@ export class Client {
       ...this.config,
       ...options,
       logFn: this.config.logFn || console.log,
-      userAgent: '@datocms/cma-client v5.1.0',
+      userAgent: '@datocms/cma-client v5.1.2',
       baseUrl: this.baseUrl,
       preCallStack: new Error().stack,
       extraHeaders: {