@datocms/cma-client 5.0.0 → 5.1.0

package/src/fieldTypes/single_block.ts

@@ -0,0 +1,201 @@
+import type * as SchemaTypes from '../generated/SchemaTypes';
+
+/**
+ * SINGLE BLOCK FIELD TYPE SYSTEM FOR DATOCMS
+ *
+ * This module defines a comprehensive type system for handling DatoCMS Single Block fields,
+ * which contain a single embedded content block.
+ *
+ * The challenge we're solving:
+ * - DatoCMS Single Block fields contain a single "block" (embedded content item)
+ * - By default, API responses contain blocks as string IDs (lightweight references)
+ * - With ?nested=true parameter, API responses contain blocks as full block objects
+ *   (which in turn can contain other blocks)
+ * - For API requests, blocks can be represented as:
+ *   1. String IDs (referencing existing blocks)
+ *   2. Full block objects with IDs (for updates)
+ *   3. Block objects without IDs (for creation)
+ *
+ * This creates a need for different type variants for the same conceptual data structure.
+ */
+
+/**
+ * =============================================================================
+ * BASIC SINGLE BLOCK TYPE - Default API response format
+ * =============================================================================
+ *
+ * The standard Single Block field value containing a block reference as string ID.
+ * This is what you get from regular API responses without ?nested=true.
+ */
+
+/**
+ * Basic Single Block field value - string block ID (lightweight reference)
+ */
+export type SingleBlockFieldValue = string | null;
+
+/**
+ * =============================================================================
+ * REQUEST VARIANT - Type for sending data TO the DatoCMS API
+ * =============================================================================
+ *
+ * When making API requests, we need flexibility in how we represent embedded blocks:
+ * - Use string ID to reference existing block that does not need to change
+ * - Include full block object for updates
+ * - Omit ID for new blocks being created
+ */
+
+/**
+ * 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)
+ *
+ * Also, 'meta' can always be omitted
+ */
+export type BlockItemInARequest =
+  | string
+  | OptionalFields<SchemaTypes.Item, 'id' | 'meta'>;
+
+/**
+ * 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)
+ */
+export type SingleBlockFieldValueAsRequest = BlockItemInARequest | null;
+
+/**
+ * =============================================================================
+ * NESTED VARIANT - Type for API responses with ?nested=true parameter
+ * =============================================================================
+ *
+ * When using the ?nested=true query parameter, the API returns Single Block data
+ * with embedded block fully populated as complete SchemaTypes.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;
+
+/**
+ * =============================================================================
+ * SHARED UTILITY FUNCTIONS
+ * =============================================================================
+ * These functions are used internally and can be imported by other modules
+ */
+
+/**
+ * Validates if a single block item is a string ID
+ */
+export function isBlockStringId(block: unknown): block is string {
+  return typeof block === 'string';
+}
+
+export type ItemWithOptionalIdAndMeta = OptionalFields<
+  SchemaTypes.Item,
+  'id' | 'meta'
+>;
+
+/**
+ * Validates if a single block item is a SchemaTypes.Item object (with or without ID)
+ */
+export function isBlockObject(
+  block: unknown,
+): block is ItemWithOptionalIdAndMeta {
+  return (
+    typeof block === 'object' &&
+    block !== null &&
+    'type' in block &&
+    'attributes' in block
+  );
+}
+
+export type ItemWithOptionalMeta = OptionalFields<SchemaTypes.Item, 'meta'>;
+
+/**
+ * Validates if a single block item is a complete SchemaTypes.Item object with ID
+ */
+export function isBlockObjectWithId(
+  block: unknown,
+): block is ItemWithOptionalMeta {
+  return isBlockObject(block) && 'id' in block && typeof block.id === 'string';
+}
+
+/**
+ * =============================================================================
+ * TYPE GUARDS - Runtime validation functions
+ * =============================================================================
+ */
+
+/**
+ * Type guard for basic Single Block field values (block as string ID only).
+ * Checks for string structure and ensures block is a string reference.
+ */
+export function isSingleBlockFieldValue(
+  value: unknown,
+): value is SingleBlockFieldValue {
+  return typeof value === 'string' || value === null;
+}
+
+/**
+ * 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 {
+  if (value === null) return true;
+
+  // String ID _ referencing existing block
+  if (isBlockStringId(value)) return true;
+
+  // Object (either with or without ID for updates/creation)
+  return isBlockObject(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.
+ */
+export function isSingleBlockFieldValueWithResolvedBlocks(
+  value: unknown,
+): value is SingleBlockFieldValueWithResolvedBlocks {
+  if (value === null) return true;
+
+  // Must be a full object with ID (nested format always includes complete block objects)
+  return isBlockObjectWithId(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;
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+};
+
+export type SingleBlockFieldAppearance =
+  | {
+      editor: 'framed_single_block';
+      parameters: FramedSingleBlockEditorConfiguration;
+    }
+  | {
+      editor: 'frameless_single_block';
+      parameters: FramelessSingleBlockEditorConfiguration;
+    }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };
+
+// UTILITIES
+
+type OptionalFields<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

package/src/fieldTypes/slug.ts

@@ -0,0 +1,32 @@
+import type { SlugEditorConfiguration } from './appearance/slug';
+import type { LengthValidator } from './validators/length';
+import type { RequiredValidator } from './validators/required';
+import type { SlugFormatValidator } from './validators/slug_format';
+import type { SlugTitleFieldValidator } from './validators/slug_title_field';
+
+export type SlugFieldValue = string | null;
+
+export function isSlugFieldValue(value: unknown): value is SlugFieldValue {
+  if (value === null) return true;
+  return typeof value === 'string' && /^[a-z0-9_]+(?:-[a-z0-9]+)*$/.test(value);
+}
+
+export type SlugFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept strings only with a specified number of characters */
+  length?: LengthValidator;
+  /** Only accept slugs having a specific format */
+  slug_format?: SlugFormatValidator;
+  /** Specifies the ID of the Single_line string field that will be used to generate the slug */
+  slug_title_field?: SlugTitleFieldValidator;
+};
+
+export type SlugFieldAppearance =
+  | { editor: 'slug'; parameters: SlugEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/string.ts

@@ -0,0 +1,41 @@
+import type { SingleLineEditorConfiguration } from './appearance/single_line';
+import type { StringRadioGroupEditorConfiguration } from './appearance/string_radio_group';
+import type { StringSelectEditorConfiguration } from './appearance/string_select';
+import type { EnumValidator } from './validators/enum';
+import type { FormatValidator } from './validators/format';
+import type { LengthValidator } from './validators/length';
+import type { RequiredValidator } from './validators/required';
+import type { UniqueValidator } from './validators/unique';
+
+export type StringFieldValue = string | null;
+
+export function isStringFieldValue(value: unknown): value is StringFieldValue {
+  return typeof value === 'string' || value === null;
+}
+
+export type StringFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** The value must be unique across the whole collection of records */
+  unique?: UniqueValidator;
+  /** Accept strings only with a specified number of characters */
+  length?: LengthValidator;
+  /** Accepts only strings that match a specified format */
+  format?: FormatValidator;
+  /** Only accept a specific set of values */
+  enum?: EnumValidator;
+};
+
+export type StringFieldAppearance =
+  | { editor: 'single_line'; parameters: SingleLineEditorConfiguration }
+  | {
+      editor: 'string_radio_group';
+      parameters: StringRadioGroupEditorConfiguration;
+    }
+  | { editor: 'string_select'; parameters: StringSelectEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/structured_text.ts

@@ -0,0 +1,328 @@
+import {
+  type Block,
+  type Document,
+  type InlineBlock,
+  type Root,
+  isBlock,
+  isInlineBlock,
+  isNode,
+} from 'datocms-structured-text-utils';
+import type * as SchemaTypes from '../generated/SchemaTypes';
+import { everyNode } from '../utilities/structuredText';
+import {
+  type BlockItemInARequest,
+  isBlockObject,
+  isBlockObjectWithId,
+  isBlockStringId,
+} from './single_block';
+
+/**
+ * STRUCTURED TEXT TYPE SYSTEM FOR DATOCMS
+ *
+ * This module defines a comprehensive type system for handling DatoCMS structured text fields,
+ * which are rich text documents that can contain embedded blocks and inline elements.
+ *
+ * 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)
+ * - 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:
+ *   1. String IDs (referencing existing items)
+ *   2. Full item objects with IDs (for updates)
+ *   3. Item objects without IDs (for creation)
+ *
+ * This creates a need for different type variants for the same conceptual data structure.
+ */
+
+/**
+ * =============================================================================
+ * REQUEST VARIANTS - Types for sending data TO the DatoCMS API
+ * =============================================================================
+ *
+ * When making API requests, we need flexibility in how we represent embedded blocks:
+ * - Use string IDs to reference existing blocks that do not need to change
+ * - Include full block objects for updates
+ * - Omit IDs for new blocks being created
+ */
+
+/**
+ * Variant of 'block' structured text node for API requests
+ */
+export type BlockAsRequest = Omit<Block, 'item'> & {
+  item: 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
+  >
+>;
+
+/**
+ * Variant of Structured Text document for API requests
+ */
+export type DocumentAsRequest = {
+  schema: 'dast';
+  document: NodeAsRequest<Root>;
+};
+
+/**
+ * =============================================================================
+ * 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
+ * of just string IDs.
+ */
+
+/**
+ * Variant of 'block' structured text node for ?nested=true API responses
+ */
+export type BlockWithResolvedBlocks = Omit<Block, 'item'> & {
+  item: SchemaTypes.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
+  >
+>;
+
+/**
+ * Variant of Structured Text document for ?nested=true API responses
+ */
+export type DocumentWithResolvedBlocks = {
+  schema: 'dast';
+  document: NodeWithResolvedBlocks<Root>;
+};
+
+/**
+ * =============================================================================
+ * MAIN APPLICATION TYPES
+ * =============================================================================
+ */
+
+/**
+ * The main type for structured text field values in our application.
+ * 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 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
+  );
+}
+
+/**
+ * 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,
+): 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))
+    ) {
+      return callback(currentNode);
+    }
+    // For all other node types, they're valid by default
+    return true;
+  });
+}
+
+/**
+ * Type guard for basic structured text field values (blocks as string IDs only).
+ * Checks for the expected structure and ensures all block/inlineBlock nodes have string IDs.
+ */
+export function isStructuredTextFieldValue(
+  value: unknown,
+): value is StructuredTextFieldValue {
+  if (value === null) return true;
+
+  if (!isValidDocumentStructure(value)) {
+    return false;
+  }
+
+  // Check that all block/inlineBlock nodes have string item IDs
+  return validateAllBlockNodes(value.document, (node) => {
+    return typeof node.item === 'string';
+  });
+}
+
+/**
+ * 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(
+  value: unknown,
+): value is StructuredTextFieldValueAsRequest {
+  if (value === null) return true;
+
+  if (!isValidDocumentStructure(value)) {
+    return false;
+  }
+
+  // Check that all block/inlineBlock nodes have valid request format items
+  return validateAllBlockNodes(value.document, (node) => {
+    const item = node.item;
+
+    // String ID
+    if (isBlockStringId(item)) return true;
+
+    // Object (either with or without ID)
+    return isBlockObject(item);
+  });
+}
+
+/**
+ * Type guard for structured text field values with nested blocks (?nested=true format).
+ * Ensures all block/inlineBlock nodes have full SchemaTypes.Item objects.
+ */
+export function isStructuredTextFieldValueWithResolvedBlocks(
+  value: unknown,
+): value is StructuredTextFieldValueWithResolvedBlocks {
+  if (value === null) return true;
+
+  if (!isValidDocumentStructure(value)) {
+    return false;
+  }
+
+  // Check that all block/inlineBlock nodes have full item objects
+  return validateAllBlockNodes(value.document, (node) => {
+    const item = node.item;
+
+    // Must be a full object with ID (nested format always includes full items)
+    return isBlockObjectWithId(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;
+  /** Only accept itemLink to inlineItem nodes for records of the specified models */
+  structured_text_links: StructuredTextLinksValidator;
+  /** Accept strings only with a specified number of characters */
+  length?: LengthValidator;
+  /** Only accept references to block records of the specified block models for inline blocks */
+  structured_text_inline_blocks?: StructuredTextInlineBlocksValidator;
+};
+
+export type StructuredTextFieldAppearance =
+  | { editor: 'structured_text'; parameters: StructuredTextEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/text.ts

@@ -0,0 +1,35 @@
+import type { MarkdownEditorConfiguration } from './appearance/markdown';
+import type { TextareaEditorConfiguration } from './appearance/textarea';
+import type { WysiwygEditorConfiguration } from './appearance/wysiwyg';
+import type { FormatValidator } from './validators/format';
+import type { LengthValidator } from './validators/length';
+import type { RequiredValidator } from './validators/required';
+import type { SanitizationValidator } from './validators/sanitization';
+
+export type TextFieldValue = string | null;
+
+export function isTextFieldValue(value: unknown): value is TextFieldValue {
+  return typeof value === 'string' || value === null;
+}
+
+export type TextFieldValidators = {
+  /** Value must be specified or it won't be valid */
+  required?: RequiredValidator;
+  /** Accept strings only with a specified number of characters */
+  length?: LengthValidator;
+  /** Accepts only strings that match a specified format */
+  format?: FormatValidator;
+  /** Checks for the presence of malicious code in HTML fields */
+  sanitization?: SanitizationValidator;
+};
+
+export type TextFieldAppearance =
+  | { editor: 'markdown'; parameters: MarkdownEditorConfiguration }
+  | { editor: 'wysiwyg'; parameters: WysiwygEditorConfiguration }
+  | { editor: 'textarea'; parameters: TextareaEditorConfiguration }
+  | {
+      /** Plugin ID */
+      editor: string;
+      /** Plugin configuration */
+      parameters: Record<string, unknown>;
+    };

package/src/fieldTypes/validators/date_range.ts

@@ -0,0 +1,16 @@
+/**
+ * Accept dates only inside a specified date range.
+ */
+export type DateRangeValidator =
+  | {
+      /** Minimum date (ISO 8601 date format) */
+      min: string;
+      /** Maximum date (ISO 8601 date format) */
+      max?: string;
+    }
+  | {
+      /** Minimum date (ISO 8601 date format) */
+      min?: string;
+      /** Maximum date (ISO 8601 date format) */
+      max: string;
+    };

package/src/fieldTypes/validators/date_time_range.ts

@@ -0,0 +1,14 @@
+/**
+ * Accept date times only inside a specified date range.
+ */
+export type DateTimeRangeValidator =
+  | {
+      /** Minimum datetime (ISO 8601 datetime format) */
+      min: string /** Maximum datetime (ISO 8601 datetime format) */;
+      max?: string;
+    }
+  | {
+      /** Minimum datetime (ISO 8601 datetime format) */
+      min?: string /** Maximum datetime (ISO 8601 datetime format) */;
+      max: string;
+    };

package/src/fieldTypes/validators/description_length.ts

@@ -0,0 +1,13 @@
+/**
+ * Limits the length of the description for a SEO field.
+ * Search engines usually truncate description tags to 160 characters so it is a good practice to keep the description around this length.
+ */
+export type DescriptionLengthValidator =
+  | {
+      /** Minimum value */ min: number /** Maximum value */;
+      max?: number;
+    }
+  | {
+      /** Minimum value */ min?: number /** Maximum value */;
+      max: number;
+    };

package/src/fieldTypes/validators/enum.ts

@@ -0,0 +1,7 @@
+/**
+ * Only accept a specific set of values.
+ */
+export type EnumValidator = {
+  /** Set of allowed values */
+  values: string[];
+};