@datocms/cma-client 5.1.3 → 5.1.4

package/src/fieldTypes/lat_lon.ts

@@ -2,14 +2,12 @@ import type { LocalizedFieldValue } from '../utilities/fieldValue';
 import type { MapEditorConfiguration } from './appearance/map';
 import type { RequiredValidator } from './validators/required';
 
-export type LocationFieldValue = {
+export type LatLonFieldValue = {
   latitude: number;
   longitude: number;
 } | null;
 
-export function isLocationFieldValue(
-  value: unknown,
-): value is LocationFieldValue {
+export function isLatLonFieldValue(value: unknown): value is LatLonFieldValue {
   if (value === null) return true;
   return (
     typeof value === 'object' &&
@@ -19,22 +17,22 @@ export function isLocationFieldValue(
   );
 }
 
-export function isLocalizedLocationFieldValue(
+export function isLocalizedLatLonFieldValue(
   value: unknown,
-): value is LocalizedFieldValue<LocationFieldValue> {
+): value is LocalizedFieldValue<LatLonFieldValue> {
   return (
     typeof value === 'object' &&
     value !== null &&
-    Object.values(value).every(isLocationFieldValue)
+    Object.values(value).every(isLatLonFieldValue)
   );
 }
 
-export type LocationFieldValidators = {
+export type LatLonFieldValidators = {
   /** Value must be specified or it won't be valid */
   required?: RequiredValidator;
 };
 
-export type LocationFieldAppearance =
+export type LatLonFieldAppearance =
   | { editor: 'map'; parameters: MapEditorConfiguration }
   | {
       /** Plugin ID */

package/src/fieldTypes/rich_text.ts

@@ -1,5 +1,6 @@
 import type * as RawApiTypes from '../generated/RawApiTypes';
 import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import type { ItemDefinition } from '../utilities/itemDefinition';
 import type { RichTextEditorConfiguration } from './appearance/rich_text';
 import {
   type BlockItemInARequest,
@@ -41,7 +42,7 @@ import type { SizeValidator } from './validators/size';
 /**
  * Basic Modular Content field value - array of string block IDs (lightweight references)
  */
-export type RichTextFieldValue = string[] | null;
+export type RichTextFieldValue = string[];
 
 /**
  * =============================================================================
@@ -60,7 +61,9 @@ export type RichTextFieldValue = string[] | null;
  * - RawApiTypes.Item: Full block object with ID (for updates)
  * - Omit<RawApiTypes.Item, 'id'>: Block object without ID (for creation)
  */
-export type RichTextFieldValueAsRequest = BlockItemInARequest[] | null;
+export type RichTextFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+> = BlockItemInARequest<D>[] | null;
 
 /**
  * =============================================================================
@@ -75,7 +78,9 @@ export type RichTextFieldValueAsRequest = BlockItemInARequest[] | null;
 /**
  * Modular Content field value with nested blocks - array of fully populated block objects
  */
-export type RichTextFieldValueWithNestedBlocks = RawApiTypes.Item[] | null;
+export type RichTextFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+> = RawApiTypes.Item<D>[];
 
 /**
  * =============================================================================
@@ -111,9 +116,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(
-  value: unknown,
-): value is RichTextFieldValueAsRequest {
+export function isRichTextFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+>(value: unknown): value is RichTextFieldValueAsRequest<D> {
   if (value === null) return true;
 
   if (!Array.isArray(value)) return false;
@@ -127,9 +132,11 @@ export function isRichTextFieldValueAsRequest(
   });
 }
 
-export function isLocalizedRichTextFieldValueAsRequest(
+export function isLocalizedRichTextFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueAsRequest> {
+): value is LocalizedFieldValue<RichTextFieldValueAsRequest<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&
@@ -141,9 +148,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(
-  value: unknown,
-): value is RichTextFieldValueWithNestedBlocks {
+export function isRichTextFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(value: unknown): value is RichTextFieldValueWithNestedBlocks<D> {
   if (value === null) return true;
 
   if (!Array.isArray(value)) return false;
@@ -154,9 +161,11 @@ export function isRichTextFieldValueWithNestedBlocks(
   });
 }
 
-export function isLocalizedRichTextFieldValueWithNestedBlocks(
+export function isLocalizedRichTextFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks> {
+): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&

package/src/fieldTypes/single_block.ts

@@ -1,5 +1,6 @@
 import type * as RawApiTypes from '../generated/RawApiTypes';
 import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import type { ItemDefinition } from '../utilities/itemDefinition';
 
 import type { FramedSingleBlockEditorConfiguration } from './appearance/framed_single_block';
 import type { FramelessSingleBlockEditorConfiguration } from './appearance/frameless_single_block';
@@ -51,14 +52,15 @@ export type SingleBlockFieldValue = string | null;
  */
 
 /** Represents an existing block in a CMA request */
-export type UnchangedBlockInARequest = string;
+export type UnchangedBlockInARequest<
+  D extends ItemDefinition = ItemDefinition,
+> = RawApiTypes.Item<D>['id'];
 /** Represents a block we want to update in a CMA request */
-export type UpdatedBlockInARequest = OptionalFields<RawApiTypes.Item, 'meta'>;
+export type UpdatedBlockInARequest<D extends ItemDefinition = ItemDefinition> =
+  OptionalFields<RawApiTypes.Item<D>, 'meta'>;
 /** Represents a new block to create in a CMA request */
-export type NewBlockInARequest = OptionalFields<
-  RawApiTypes.Item,
-  'id' | 'meta'
->;
+export type NewBlockInARequest<D extends ItemDefinition = ItemDefinition> =
+  OptionalFields<RawApiTypes.Item<D>, 'id' | 'meta'>;
 
 /**
  * Union type representing the different ways a block can be specified in API requests:
@@ -68,10 +70,10 @@ export type NewBlockInARequest = OptionalFields<
  *
  * Also, 'meta' can always be omitted
  */
-export type BlockItemInARequest =
+export type BlockItemInARequest<D extends ItemDefinition = ItemDefinition> =
   | UnchangedBlockInARequest
-  | UpdatedBlockInARequest
-  | NewBlockInARequest;
+  | UpdatedBlockInARequest<D>
+  | NewBlockInARequest<D>;
 
 /**
  * Single Block field value for API requests - allows flexible block representations:
@@ -79,7 +81,9 @@ export type BlockItemInARequest =
  * - Full block object with ID (to update an existing block)
  * - Block object without ID (to create a new block)
  */
-export type SingleBlockFieldValueAsRequest = BlockItemInARequest | null;
+export type SingleBlockFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+> = BlockItemInARequest<D> | null;
 
 /**
  * =============================================================================
@@ -94,7 +98,9 @@ export type SingleBlockFieldValueAsRequest = BlockItemInARequest | null;
 /**
  * Single Block field value with nested block - fully populated block object
  */
-export type SingleBlockFieldValueWithNestedBlocks = RawApiTypes.Item | null;
+export type SingleBlockFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+> = RawApiTypes.Item<D> | null;
 
 /**
  * =============================================================================
@@ -110,17 +116,16 @@ export function isItemId(input: unknown): input is string {
   return typeof input === 'string';
 }
 
-export type ItemWithOptionalIdAndMeta = OptionalFields<
-  RawApiTypes.Item,
-  'id' | 'meta'
->;
+export type ItemWithOptionalIdAndMeta<
+  D extends ItemDefinition = ItemDefinition,
+> = OptionalFields<RawApiTypes.Item<D>, 'id' | 'meta'>;
 
 /**
  * Validates if the input is a RawApiTypes.Item object (with optional `id` and `meta`)
  */
-export function isItemWithOptionalIdAndMeta(
-  block: unknown,
-): block is ItemWithOptionalIdAndMeta {
+export function isItemWithOptionalIdAndMeta<
+  D extends ItemDefinition = ItemDefinition,
+>(block: unknown): block is ItemWithOptionalIdAndMeta<D> {
   return (
     typeof block === 'object' &&
     block !== null &&
@@ -129,14 +134,15 @@ export function isItemWithOptionalIdAndMeta(
   );
 }
 
-export type ItemWithOptionalMeta = OptionalFields<RawApiTypes.Item, 'meta'>;
+export type ItemWithOptionalMeta<D extends ItemDefinition = ItemDefinition> =
+  OptionalFields<RawApiTypes.Item<D>, 'meta'>;
 
 /**
  * Validates if the input is a a complete RawApiTypes.Item object with optional `meta`
  */
-export function isItemWithOptionalMeta(
-  block: unknown,
-): block is ItemWithOptionalMeta {
+export function isItemWithOptionalMeta<
+  D extends ItemDefinition = ItemDefinition,
+>(block: unknown): block is ItemWithOptionalMeta<D> {
   return (
     isItemWithOptionalIdAndMeta(block) &&
     'id' in block &&
@@ -174,9 +180,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(
-  value: unknown,
-): value is SingleBlockFieldValueAsRequest {
+export function isSingleBlockFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+>(value: unknown): value is SingleBlockFieldValueAsRequest<D> {
   if (value === null) return true;
 
   // String ID - referencing existing block
@@ -186,9 +192,11 @@ export function isSingleBlockFieldValueAsRequest(
   return isItemWithOptionalIdAndMeta(value);
 }
 
-export function isLocalizedSingleBlockFieldValueAsRequest(
+export function isLocalizedSingleBlockFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<SingleBlockFieldValueAsRequest> {
+): value is LocalizedFieldValue<SingleBlockFieldValueAsRequest<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&
@@ -200,18 +208,20 @@ 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(
-  value: unknown,
-): value is SingleBlockFieldValueWithNestedBlocks {
+export function isSingleBlockFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(value: unknown): value is SingleBlockFieldValueWithNestedBlocks<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(
+export function isLocalizedSingleBlockFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<SingleBlockFieldValueWithNestedBlocks> {
+): value is LocalizedFieldValue<SingleBlockFieldValueWithNestedBlocks<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&

package/src/fieldTypes/structured_text.ts

@@ -10,6 +10,7 @@ import {
 } 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 { StructuredTextEditorConfiguration } from './appearance/structured_text';
 import {
   type BlockItemInARequest,
@@ -56,17 +57,26 @@ import type { StructuredTextLinksValidator } from './validators/structured_text_
 /**
  * Variant of 'block' structured text node for API requests
  */
-export type BlockAsRequest = Block<BlockItemInARequest>;
+export type BlockAsRequest<D extends ItemDefinition = ItemDefinition> = Block<
+  BlockItemInARequest<D>
+>;
 
 /**
  * Variant of 'inlineBlock' structured text node for API requests
  */
-export type InlineBlockAsRequest = InlineBlock<BlockItemInARequest>;
+export type InlineBlockAsRequest<D extends ItemDefinition = ItemDefinition> =
+  InlineBlock<BlockItemInARequest<D>>;
 
 /**
  * Variant of Structured Text document for API requests
  */
-export type DocumentAsRequest = Document<BlockItemInARequest>;
+export type DocumentAsRequest<
+  BlockItemDefinition extends ItemDefinition = ItemDefinition,
+  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+> = Document<
+  BlockItemInARequest<BlockItemDefinition>,
+  BlockItemInARequest<InlineBlockItemDefinition>
+>;
 
 /**
  * =============================================================================
@@ -81,17 +91,26 @@ export type DocumentAsRequest = Document<BlockItemInARequest>;
 /**
  * Variant of 'block' structured text node for ?nested=true API responses
  */
-export type BlockWithNestedBlocks = Block<RawApiTypes.Item>;
+export type BlockWithNestedBlocks<D extends ItemDefinition = ItemDefinition> =
+  Block<RawApiTypes.Item<D>>;
 
 /**
  * Variant of 'inlineBlock' structured text node for ?nested=true API responses
  */
-export type InlineBlockWithNestedBlocks = InlineBlock<RawApiTypes.Item>;
+export type InlineBlockWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+> = InlineBlock<RawApiTypes.Item<D>>;
 
 /**
  * Variant of Structured Text document for ?nested=true API responses
  */
-export type DocumentWithNestedBlocks = Document<RawApiTypes.Item>;
+export type DocumentWithNestedBlocks<
+  BlockItemDefinition extends ItemDefinition = ItemDefinition,
+  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+> = Document<
+  RawApiTypes.Item<BlockItemDefinition>,
+  RawApiTypes.Item<InlineBlockItemDefinition>
+>;
 
 /**
  * =============================================================================
@@ -104,21 +123,29 @@ export type DocumentWithNestedBlocks = Document<RawApiTypes.Item>;
  * Can be null (empty field) or a document with blocks as string IDs
  */
 export type StructuredTextFieldValue = Document | null;
-export type StructuredTextFieldValueAsRequest = DocumentAsRequest | null;
-export type StructuredTextFieldValueWithNestedBlocks =
-  DocumentWithNestedBlocks | 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
+> | 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<T>(
-  node: Node<T>,
-  callback: (node: Block<T> | InlineBlock<T>) => boolean,
+function validateAllBlockNodes<B, I>(
+  node: Node<B, I>,
+  callback: (node: Block<B> | InlineBlock<I>) => boolean,
 ): boolean {
   return everyNode(node, (currentNode) => {
     // If this is a block or inlineBlock node, validate it with the callback
-    if (isBlock<T>(currentNode) || isInlineBlock<T>(currentNode)) {
+    if (isBlock(currentNode) || isInlineBlock(currentNode)) {
       return callback(currentNode);
     }
     // For all other node types, they're valid by default
@@ -135,7 +162,7 @@ export function isStructuredTextFieldValue(
 ): value is StructuredTextFieldValue {
   if (value === null) return true;
 
-  if (!isDocument<unknown>(value)) {
+  if (!isDocument<unknown, unknown>(value)) {
     return false;
   }
 
@@ -159,9 +186,15 @@ 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(
+export function isStructuredTextFieldValueAsRequest<
+  BlockItemDefinition extends ItemDefinition = ItemDefinition,
+  InlineBlockItemDefinition extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is StructuredTextFieldValueAsRequest {
+): value is StructuredTextFieldValueAsRequest<
+  BlockItemDefinition,
+  InlineBlockItemDefinition
+> {
   if (value === null) return true;
 
   if (!isDocument<unknown>(value)) {
@@ -180,9 +213,11 @@ export function isStructuredTextFieldValueAsRequest(
   });
 }
 
-export function isLocalizedStructuredTextFieldValueAsRequest(
+export function isLocalizedStructuredTextFieldValueAsRequest<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<StructuredTextFieldValueAsRequest> {
+): value is LocalizedFieldValue<StructuredTextFieldValueAsRequest<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&
@@ -194,9 +229,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(
-  value: unknown,
-): value is StructuredTextFieldValueWithNestedBlocks {
+export function isStructuredTextFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(value: unknown): value is StructuredTextFieldValueWithNestedBlocks<D> {
   if (value === null) return true;
 
   if (!isDocument<unknown>(value)) {
@@ -212,9 +247,11 @@ export function isStructuredTextFieldValueWithNestedBlocks(
   });
 }
 
-export function isLocalizedStructuredTextFieldValueWithNestedBlocks(
+export function isLocalizedStructuredTextFieldValueWithNestedBlocks<
+  D extends ItemDefinition = ItemDefinition,
+>(
   value: unknown,
-): value is LocalizedFieldValue<StructuredTextFieldValueWithNestedBlocks> {
+): value is LocalizedFieldValue<StructuredTextFieldValueWithNestedBlocks<D>> {
   return (
     typeof value === 'object' &&
     value !== null &&