Content Management API > Record

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6

7
type EnvironmentSettings = { locales: "en" };
8

9
/*
10
 * BlogPost
11
 * ├─ title: string
12
 * ├─ description: string
13
 * ├─ featured_image: file
14
 * └─ content_blocks: modular_content
15
 *    └─ HeroBlock: headline
16
 */
17

18
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
19

20
type BlogPost = ItemTypeDefinition<
21
  EnvironmentSettings,
22
  "UZyfjdBES8y2W2ruMEHSoA",
23
  {
24
    title: { type: "string" };
25
    description: { type: "string" };
26
    featured_image: { type: "file" };
27
    content_blocks: { type: "rich_text"; blocks: Block };
28
  }
29
>;
30

31
type Block = ItemTypeDefinition<
32
  EnvironmentSettings,
33
  "DB5xsyzCQ3iHTx0dZPb3sw",
34
  {
35
    headline: { type: "string" };
36
  }
37
>;
38

39
async function run() {
40
  // Make sure the API token has access to the CMA, and is stored securely
41
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
42

43
  const record = await client.items.find<BlogPost>("T4m4tPymSACFzsqbZS65WA", {
44
    nested: true,
45
  });
46

47
  console.log("-- BEFORE UPDATE --");
48
  console.log(inspectItem(record));
49

50
  const item = await client.items.update<BlogPost>("T4m4tPymSACFzsqbZS65WA", {
51
    // Field we want to update with a new value
52
    title: "[EDIT] My first blog post!",
53

54
    // Fields we omit are left UNTOUCHED - their existing values remain unchanged
55
    // description: (omitted - keeps existing value)
56

57
    // Fields we explicitly set to null/empty are DELETED/CLEARED
58
    featured_image: null, // This removes the featured image
59
    content_blocks: [], // This clears all content blocks!
60
  });
61

62
  console.log("-- AFTER UPDATE --");
63
  console.log(inspectItem(item));
64
}
65

66
run();

1
-- BEFORE UPDATE --
2
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "My first blog post!"
4
  ├ description: "An introduction to our new blog platform"
5
  ├ featured_image: null
6
  └ content_blocks
7
    └ [0] Item "WtzyjA4sTLiLiOQ9TBNgtQ" (item_type: "DB5xsyzCQ3iHTx0dZPb3sw")
8
      └ headline: "Hello!"
9

10
-- AFTER UPDATE --
11
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
12
  ├ title: "[EDIT] My first blog post!"
13
  ├ description: "An introduction to our new blog platform"
14
  ├ featured_image: null
15
  └ content_blocks: []

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  duplicateBlockRecord,
5
  inspectItem,
6
  SchemaRepository,
7
  type ApiTypes,
8
  type ItemTypeDefinition,
9
} from "@datocms/cma-client-node";
10

11
type EnvironmentSettings = { locales: "en" };
12

13
/*
14
 * LandingPage
15
 * ├─ title: string
16
 * └─ sections: modular_content
17
 *    ├─ HeroBlock: headline, subtitle
18
 *    ├─ CallToActionBlock: button_text, button_url
19
 *    └─ TestimonialBlock: quote, author
20
 */
21

22
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
23

24
type LandingPage = ItemTypeDefinition<
25
  EnvironmentSettings,
26
  "ZV0o9497SsqWxQR8HEQddw",
27
  {
28
    title: { type: "string" };
29
    sections: {
30
      type: "rich_text";
31
      blocks: HeroBlock | CallToActionBlock | TestimonialBlock;
32
    };
33
  }
34
>;
35

36
type HeroBlock = ItemTypeDefinition<
37
  EnvironmentSettings,
38
  "d-CHYg-rShOt3kiL6ZN1yA",
39
  {
40
    headline: { type: "string" };
41
    subtitle: { type: "text" };
42
  }
43
>;
44

45
type CallToActionBlock = ItemTypeDefinition<
46
  EnvironmentSettings,
47
  "I8Q6k-HqQmaZ498WKtvFbg",
48
  {
49
    button_text: { type: "string" };
50
    button_url: { type: "string" };
51
  }
52
>;
53

54
type TestimonialBlock = ItemTypeDefinition<
55
  EnvironmentSettings,
56
  "Dy9C52o4S6eF3mqSOmeUtg",
57
  {
58
    quote: { type: "text" };
59
    author: { type: "string" };
60
  }
61
>;
62

63
async function run() {
64
  // Make sure the API token has access to the CMA, and is stored securely
65
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
66

67
  // Schema repository (used for block duplication below)
68
  const schemaRepository = new SchemaRepository(client);
69

70
  // Get the current record with nested blocks to see existing content
71
  const currentPage = await client.items.find<LandingPage>(
72
    "W4wcrs_2REiM4fc6dlDZCQ",
73
    {
74
      nested: true,
75
    },
76
  );
77

78
  console.log("-- BEFORE UPDATE --");
79
  console.log(inspectItem(currentPage));
80

81
  // 1. DUPLICATE EXISTING BLOCKS: All testimonial blocks
82
  const duplicatedTestimonialBlocksOrNull = await Promise.all(
83
    currentPage.sections.map((block) =>
84
      block.__itemTypeId === "Dy9C52o4S6eF3mqSOmeUtg"
85
        ? // duplicateBlockRecord() clones the block object and removes block IDs (this applies to nested blocks too)
86
          // This creates a new block template that can be used elsewhere or modified
87
          duplicateBlockRecord<TestimonialBlock>(block, schemaRepository)
88
        : null,
89
    ),
90
  );
91

92
  const updateOperation: ApiTypes.ItemUpdateSchema<LandingPage> = {
93
    sections: [
94
      // 2. ADD NEW BLOCK: New hero at top for better first impression
95
      buildBlockRecord<HeroBlock>({
96
        item_type: { type: "item_type", id: "d-CHYg-rShOt3kiL6ZN1yA" },
97
        headline: "Transform Your Business Today",
98
        subtitle:
99
          "Join thousands of companies already using our platform to streamline their operations and boost productivity.",
100
      }),
101

102
      // Put the first duplicate testimonial as second block
103
      ...duplicatedTestimonialBlocksOrNull.filter(isNonNullable).slice(0, 1),
104

105
      ...currentPage.sections
106
        // 3. REMOVE EXISTING BLOCKS: Old hero blocks
107
        .filter((block) => block.__itemTypeId !== "d-CHYg-rShOt3kiL6ZN1yA")
108
        .map((block) => {
109
          // 4. UPDATE EXISTING BLOCKS: Add UTM parameters to all CTA URLs
110
          if (block.__itemTypeId === "I8Q6k-HqQmaZ498WKtvFbg") {
111
            const url = new URL(
112
              block.attributes.button_url || "https://www.datocms.com",
113
            );
114
            url.searchParams.set("utm_source", "landing_page");
115
            url.searchParams.set("utm_medium", "cta");
116
            url.searchParams.set("utm_campaign", "q1_2024");
117

118
            return buildBlockRecord<CallToActionBlock>({
119
              item_type: { id: "I8Q6k-HqQmaZ498WKtvFbg", type: "item_type" },
120
              id: block.id,
121
              button_url: url.toString(),
122
              // We don't need to pass button_text, as we're not changing it
123
            });
124
          }
125

126
          // 5. KEEP OTHER BLOCKS UNCHANGED (ie. existing testimonials)
127
          return block.id;
128
        }),
129
    ],
130
  };
131

132
  console.log("-- UPDATE OPERATION --");
133
  console.log(inspectItem(updateOperation));
134

135
  await client.items.update<LandingPage>(currentPage, updateOperation);
136

137
  const updatedPage = await client.items.find(currentPage, { nested: true });
138

139
  console.log("-- AFTER UPDATE --");
140
  console.log(inspectItem(updatedPage));
141
}
142

143
run();
144

145
function isNonNullable<T>(
146
  value: T | null | undefined,
147
): value is NonNullable<T> {
148
  return value !== null && value !== undefined && value !== false;
149
}

1
-- BEFORE UPDATE --
2
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
3
  ├ title: "Product Launch Landing Page"
4
  └ sections
5
    ├ [0] Item "BxsiUvpRQV20x8iJYXSr-w" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
6
    │ ├ headline: "Revolutionary New Solution"
7
    │ └ subtitle: "Discover the future of productivity with our cutting-edge platform designed f..."
8
    ├ [1] Item "WjyqFR6xQqmxDoQNodlx8g" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
9
    │ ├ button_text: "Get Started Free"
10
    │ └ button_url: "https://www.datocms.com/signup"
11
    ├ [2] Item "M4O1B4uwTzW0Chv41suTFA" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
12
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
13
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
14
    ├ [3] Item "Tlzw3TmDR6eRPOS2B3JS2A" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
15
    │ ├ quote: "The best investment we've made this year. The ROI was evident within the firs..."
16
    │ └ author: "Michael Rodriguez, CTO at InnovateLabs"
17
    └ [4] Item "MNksTfS8R2O_BYL1iCQAaw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
18
      ├ button_text: "Start Your Free Trial"
19
      └ button_url: "https://www.datocms.com/trial"
20

21
-- UPDATE OPERATION --
22
└ Item
23
  └ sections
24
    ├ [0] Item (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
25
    │ ├ headline: "Transform Your Business Today"
26
    │ └ subtitle: "Join thousands of companies already using our platform to streamline their op..."
27
    ├ [1] Item (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
28
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
29
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
30
    ├ [2] Item "WjyqFR6xQqmxDoQNodlx8g" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
31
    │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..."
32
    ├ [3] "M4O1B4uwTzW0Chv41suTFA"
33
    ├ [4] "Tlzw3TmDR6eRPOS2B3JS2A"
34
    └ [5] Item "MNksTfS8R2O_BYL1iCQAaw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
35
      └ button_url: "https://www.datocms.com/trial?utm_source=landing_page&utm_medium=cta&utm_camp..."
36

37
-- AFTER UPDATE --
38
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
39
  ├ title: "Product Launch Landing Page"
40
  └ sections
41
    ├ [0] Item "V5VQsv0wTeGpDjx4gM2bDw" (item_type: "d-CHYg-rShOt3kiL6ZN1yA")
42
    │ ├ headline: "Transform Your Business Today"
43
    │ └ subtitle: "Join thousands of companies already using our platform to streamline their op..."
44
    ├ [1] Item "BAHvU2p5T6W8GGg4lF0ZpA" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
45
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
46
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
47
    ├ [2] Item "WjyqFR6xQqmxDoQNodlx8g" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
48
    │ ├ button_text: "Get Started Free"
49
    │ └ button_url: "https://www.datocms.com/signup?utm_source=landing_page&utm_medium=cta&utm_cam..."
50
    ├ [3] Item "M4O1B4uwTzW0Chv41suTFA" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
51
    │ ├ quote: "This platform completely transformed how our team collaborates. We've seen a ..."
52
    │ └ author: "Sarah Chen, Product Manager at TechCorp"
53
    ├ [4] Item "Tlzw3TmDR6eRPOS2B3JS2A" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
54
    │ ├ quote: "The best investment we've made this year. The ROI was evident within the firs..."
55
    │ └ author: "Michael Rodriguez, CTO at InnovateLabs"
56
    └ [5] Item "MNksTfS8R2O_BYL1iCQAaw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
57
      ├ button_text: "Start Your Free Trial"
58
      └ button_url: "https://www.datocms.com/trial?utm_source=landing_page&utm_medium=cta&utm_camp..."

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  duplicateBlockRecord,
5
  inspectItem,
6
  SchemaRepository,
7
  type ApiTypes,
8
  type ItemTypeDefinition,
9
} from "@datocms/cma-client-node";
10

11
type EnvironmentSettings = { locales: "en" };
12

13
/*
14
 * ProductPage
15
 * ├─ title: string
16
 * ├─ price: float
17
 * └─ hero_section: single_block
18
 *    ├─ HeroBlock: headline, description, background_image
19
 *    ├─ CallToActionBlock: button_text, button_url, style
20
 *    └─ VideoBlock: video_url, thumbnail_image, autoplay
21
 */
22

23
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
24

25
type ProductPage = ItemTypeDefinition<
26
  EnvironmentSettings,
27
  "ZV0o9497SsqWxQR8HEQddw",
28
  {
29
    title: { type: "string" };
30
    price: { type: "float" };
31
    hero_section: {
32
      type: "single_block";
33
      blocks: HeroBlock | CallToActionBlock | VideoBlock;
34
    };
35
  }
36
>;
37

38
type HeroBlock = ItemTypeDefinition<
39
  EnvironmentSettings,
40
  "d-CHYg-rShOt3kiL6ZN1yA",
41
  {
42
    headline: { type: "string" };
43
    description: { type: "text" };
44
    background_image: { type: "file" };
45
  }
46
>;
47

48
type CallToActionBlock = ItemTypeDefinition<
49
  EnvironmentSettings,
50
  "I8Q6k-HqQmaZ498WKtvFbg",
51
  {
52
    button_text: { type: "string" };
53
    button_url: { type: "string" };
54
    style: { type: "string" };
55
  }
56
>;
57

58
type VideoBlock = ItemTypeDefinition<
59
  EnvironmentSettings,
60
  "Dy9C52o4S6eF3mqSOmeUtg",
61
  {
62
    video_url: { type: "string" };
63
    thumbnail_image: { type: "file" };
64
    autoplay: { type: "boolean" };
65
  }
66
>;
67

68
// Make sure the API token has access to the CMA, and is stored securely
69
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
70

71
async function run() {
72
  // Schema repository for block duplication
73
  const schemaRepository = new SchemaRepository(client);
74

75
  // Get the current record with nested blocks to see existing content
76
  const currentProduct = await client.items.find<ProductPage>(
77
    "W4wcrs_2REiM4fc6dlDZCQ",
78
    {
79
      nested: true,
80
    },
81
  );
82

83
  console.log("-- BEFORE UPDATE --");
84
  console.log(inspectItem(currentProduct));
85

86
  // 1. UPDATE EXISTING BLOCKS: Update CTAs for A/B testing
87
  if (
88
    currentProduct.hero_section &&
89
    currentProduct.hero_section.__itemTypeId === "I8Q6k-HqQmaZ498WKtvFbg"
90
  ) {
91
    await client.items.update<ProductPage>(currentProduct, {
92
      hero_section: buildBlockRecord<CallToActionBlock>({
93
        item_type: { type: "item_type", id: "I8Q6k-HqQmaZ498WKtvFbg" },
94
        id: currentProduct.hero_section.id,
95
        button_text:
96
          currentProduct.hero_section.attributes.button_text?.toUpperCase() ||
97
          "SHOP NOW",
98
        style: "primary-large",
99
        // button_url unchanged, so we don't need to include it
100
      }),
101
    });
102
    console.log("-- EXISTING BLOCK UPDATED --");
103
    await inspectItemWithNestedBlocks(currentProduct);
104
  }
105

106
  // 2. DUPLICATE EXISTING BLOCK
107
  await client.items.update<ProductPage>(currentProduct, {
108
    // duplicateBlockRecord() clones the block object and removes block IDs (this applies to nested blocks too)
109
    // This creates a new block template that can be used elsewhere or modified
110
    hero_section: await duplicateBlockRecord<
111
      HeroBlock | CallToActionBlock | VideoBlock
112
    >(currentProduct.hero_section!, schemaRepository),
113
  });
114
  console.log("-- BLOCK DUPLICATE --");
115
  await inspectItemWithNestedBlocks(currentProduct);
116

117
  // 3. REPLACE WITH DIFFERENT BLOCK TYPE
118
  const upload = await client.uploads.createFromUrl({
119
    url: "https://picsum.photos/800/600?random=1",
120
  });
121
  const productWithVideo = await client.items.update<ProductPage>(
122
    currentProduct,
123
    {
124
      hero_section: buildBlockRecord<VideoBlock>({
125
        item_type: { type: "item_type", id: "Dy9C52o4S6eF3mqSOmeUtg" },
126
        video_url: "https://videos.datocms.com/product-demo.mp4",
127
        thumbnail_image: {
128
          upload_id: upload.id,
129
        },
130
        autoplay: false,
131
      }),
132
    },
133
  );
134
  console.log("-- BLOCK REPLACED --");
135
  await inspectItemWithNestedBlocks(currentProduct);
136

137
  // 4. REMOVE BLOCK
138
  await client.items.update<ProductPage>(productWithVideo, {
139
    hero_section: null,
140
  });
141

142
  console.log("-- BLOCK REMOVED --");
143
  await inspectItemWithNestedBlocks(currentProduct);
144
}
145

146
run();
147

148
async function inspectItemWithNestedBlocks(item: ApiTypes.Item) {
149
  const itemWithNestedBlocks = await client.items.find(item, { nested: true });
150
  console.log(inspectItem(itemWithNestedBlocks));
151
}

1
-- BEFORE UPDATE --
2
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
3
  ├ title: "Premium Wireless Headphones"
4
  ├ price: 299.99
5
  └ hero_section
6
    └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
7
      ├ button_text: "Buy Now"
8
      ├ button_url: "https://example.com/buy"
9
      └ style: "primary"
10

11
-- EXISTING BLOCK UPDATED --
12
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
13
  ├ title: "Premium Wireless Headphones"
14
  ├ price: 299.99
15
  └ hero_section
16
    └ Item "MolF0AwpSLeXrdE5kdcEtw" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
17
      ├ button_text: "BUY NOW"
18
      ├ button_url: "https://example.com/buy"
19
      └ style: "primary-large"
20

21
-- BLOCK DUPLICATE --
22
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
23
  ├ title: "Premium Wireless Headphones"
24
  ├ price: 299.99
25
  └ hero_section
26
    └ Item "QXqFgPHVTfq8F1tOmQEwEg" (item_type: "I8Q6k-HqQmaZ498WKtvFbg")
27
      ├ button_text: "Buy Now"
28
      ├ button_url: "https://example.com/buy"
29
      └ style: "primary"
30

31
-- BLOCK REPLACED --
32
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
33
  ├ title: "Premium Wireless Headphones"
34
  ├ price: 299.99
35
  └ hero_section
36
    └ Item "JIHRl3kyQiGXAJHcP-7v7Q" (item_type: "Dy9C52o4S6eF3mqSOmeUtg")
37
      ├ video_url: "https://videos.datocms.com/product-demo.mp4"
38
      ├ thumbnail_image
39
      │ └ upload_id: "WwqHexgISQqQdMKJSYE8VA"
40
      └ autoplay: false
41

42
-- BLOCK REMOVED --
43
└ Item "W4wcrs_2REiM4fc6dlDZCQ" (item_type: "ZV0o9497SsqWxQR8HEQddw")
44
  ├ title: "Premium Wireless Headphones"
45
  ├ price: 299.99
46
  └ hero_section: null

1
import {
2
  buildClient,
3
  inspectItem,
4
  type ItemTypeDefinition,
5
} from "@datocms/cma-client-node";
6
import {
7
  filterNodes,
8
  isHeading,
9
  isItemLink,
10
  isLink,
11
  isParagraph,
12
  isSpan,
13
  mapNodes,
14
} from "datocms-structured-text-utils";
15

16
type EnvironmentSettings = { locales: "en" };
17

18
/*
19
 * BlogPost
20
 * ├─ title: string
21
 * ├─ slug: string
22
 * └─ content: structured_text (no blocks for this example)
23
 */
24

25
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
26

27
type BlogPost = ItemTypeDefinition<
28
  EnvironmentSettings,
29
  "UZyfjdBES8y2W2ruMEHSoA",
30
  {
31
    title: { type: "string" };
32
    slug: { type: "string" };
33
    content: { type: "structured_text" };
34
  }
35
>;
36

37
async function run() {
38
  // Make sure the API token has access to the CMA, and is stored securely
39
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
40

41
  // Get the current blog post with its structured text content
42
  const currentPost = await client.items.find<BlogPost>(
43
    "T4m4tPymSACFzsqbZS65WA",
44
  );
45

46
  if (!currentPost.content) {
47
    return;
48
  }
49

50
  console.log("-- BEFORE UPDATE --");
51
  console.log(inspectItem(currentPost));
52

53
  // Transform the structured text document with three key operations
54
  let updatedContent = mapNodes(currentPost.content, (node) => {
55
    // 1. TRANSFORM HEADING LEVELS: Convert all h1 to h2 for better hierarchy
56
    if (isHeading(node)) {
57
      if (node.level === 1) {
58
        return {
59
          ...node,
60
          level: 2, // Demote h1 to h2
61
        };
62
      }
63
    }
64

65
    // 2. UPDATE LINK ATTRIBUTES: Add target="_blank" to all links
66
    if (isLink(node)) {
67
      return {
68
        ...node,
69
        meta: [
70
          ...(node.meta || []),
71
          {
72
            id: "target",
73
            value: "_blank",
74
          },
75
        ],
76
      };
77
    }
78

79
    // 3. UPDATE ITEM LINK ATTRIBUTES: Add target="_blank" to item links too
80
    if (isItemLink(node)) {
81
      return {
82
        ...node,
83
        meta: [
84
          ...(node.meta || []),
85
          {
86
            id: "target",
87
            value: "_blank",
88
          },
89
        ],
90
      };
91
    }
92

93
    // 4. REPLACE TEXT CONTENT: Update brand name from "ZEIT" to "Vercel"
94
    if (isSpan(node) && node.value.includes("ZEIT")) {
95
      return {
96
        ...node,
97
        value: node.value.replace(/ZEIT/g, "Vercel"),
98
      };
99
    }
100

101
    // Keep all other nodes unchanged
102
    return node;
103
  });
104

105
  // 5. REMOVING NODES: Remove empty paragraphs
106
  updatedContent = filterNodes(updatedContent, (node) => {
107
    if (isParagraph(node)) {
108
      return node.children.some(
109
        (child) => !isSpan(child) || child.value.trim().length > 0,
110
      );
111
    }
112
    return true;
113
  })!;
114

115
  // Update the blog post with the transformed content
116
  const updatedPost = await client.items.update<BlogPost>(currentPost.id, {
117
    content: updatedContent,
118
    // Keep title and slug unchanged
119
  });
120

121
  console.log("-- AFTER UPDATE --");
122
  console.log(inspectItem(updatedPost));
123
}
124

125
run();

1
-- BEFORE UPDATE --
2
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title: "What is ZEIT?"
4
  ├ slug: "what-is-zeit"
5
  └ content
6
    ├ heading (level: 1)
7
    │ └ span "Understanding ZEIT"
8
    ├ paragraph
9
    │ └ span "ZEIT is a cloud platform for static sites and serverless functions. I..."
10
    ├ paragraph
11
    │ └ span ""
12
    ├ paragraph
13
    │ └ span ""
14
    ├ heading (level: 1)
15
    │ └ span "Key Features"
16
    ├ paragraph
17
    │ ├ span "ZEIT offers automatic HTTPS, global CDN distribution, and instant dep..."
18
    │ ├ link (url: "https://example.com/blog")
19
    │ │ └ span "detailed comparison"
20
    │ └ span " for more insights."
21
    └ paragraph
22
      ├ span "Visit our "
23
      ├ itemLink (item: "DvYpzVRHT2mdarqJ3ct4ow")
24
      │ └ span "migration guide"
25
      └ span " for step-by-step instructions."
26

27
-- AFTER UPDATE --
28
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
29
  ├ title: "What is ZEIT?"
30
  ├ slug: "what-is-zeit"
31
  └ content
32
    ├ heading (level: 2)
33
    │ └ span "Understanding Vercel"
34
    ├ paragraph
35
    │ └ span "Vercel is a cloud platform for static sites and serverless functions...."
36
    ├ heading (level: 2)
37
    │ └ span "Key Features"
38
    ├ paragraph
39
    │ ├ span "Vercel offers automatic HTTPS, global CDN distribution, and instant d..."
40
    │ ├ link (url: "https://example.com/blog", meta: {target="_blank"})
41
    │ │ └ span "detailed comparison"
42
    │ └ span " for more insights."
43
    └ paragraph
44
      ├ span "Visit our "
45
      ├ itemLink (item: "DvYpzVRHT2mdarqJ3ct4ow", meta: {target="_blank"})
46
      │ └ span "migration guide"
47
      └ span " for step-by-step instructions."

1
import {
2
  buildBlockRecord,
3
  buildClient,
4
  duplicateBlockRecord,
5
  inspectItem,
6
  SchemaRepository,
7
  type ApiTypes,
8
  type BlockNodeInNestedResponse,
9
  type ItemTypeDefinition,
10
} from "@datocms/cma-client-node";
11
import {
12
  findFirstNode,
13
  isBlock,
14
  isInlineBlock,
15
  mapNodes,
16
} from "datocms-structured-text-utils";
17

18
type EnvironmentSettings = { locales: "en" };
19

20
/*
21
 * Article
22
 * ├─ title: string
23
 * ├─ author: string
24
 * └─ content: structured_text
25
 *    ├─ CtaBlock: title, description, button_text, button_url
26
 *    ├─ ProductMentionInline: product_name, price, affiliate_url
27
 *    └─ ImageGalleryBlock: title, images
28
 */
29

30
// 👇 Definitions can be generated automatically using CLI: https://www.datocms.com/cma-ts-schema
31

32
type Article = ItemTypeDefinition<
33
  EnvironmentSettings,
34
  "ZV0o9497SsqWxQR8HEQddw",
35
  {
36
    title: { type: "string" };
37
    author: { type: "string" };
38
    content: {
39
      type: "structured_text";
40
      blocks: CtaBlock | ImageGalleryBlock;
41
      inline_blocks: ProductMentionInline;
42
    };
43
  }
44
>;
45

46
type CtaBlock = ItemTypeDefinition<
47
  EnvironmentSettings,
48
  "d-CHYg-rShOt3kiL6ZN1yA",
49
  {
50
    title: { type: "string" };
51
    description: { type: "text" };
52
    button_text: { type: "string" };
53
    button_url: { type: "string" };
54
  }
55
>;
56

57
type ProductMentionInline = ItemTypeDefinition<
58
  EnvironmentSettings,
59
  "VGXgXav9SwG5P48frGrFxA",
60
  {
61
    product_name: { type: "string" };
62
    price: { type: "float" };
63
    affiliate_url: { type: "string" };
64
  }
65
>;
66

67
type ImageGalleryBlock = ItemTypeDefinition<
68
  EnvironmentSettings,
69
  "I8Q6k-HqQmaZ498WKtvFbg",
70
  {
71
    title: { type: "string" };
72
    images: { type: "gallery" };
73
  }
74
>;
75

76
// Make sure the API token has access to the CMA, and is stored securely
77
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
78

79
async function run() {
80
  // Schema repository for block duplication
81
  const schemaRepository = new SchemaRepository(client);
82

83
  // Get the current article with nested blocks to analyze existing content
84
  const currentArticle = await client.items.find<Article>(
85
    "RSfdsZbbR7ixGgMBSmcaVA",
86
    {
87
      nested: true,
88
    },
89
  );
90

91
  if (!currentArticle.content) {
92
    return;
93
  }
94

95
  console.log("-- BEFORE UPDATE --");
96
  console.log(inspectItem(currentArticle));
97

98
  let newContent = currentArticle.content as NonNullable<
99
    ApiTypes.ItemUpdateSchema<Article>["content"]
100
  >;
101

102
  // 1. DUPLICATING BLOCKS: Find first block node containing a CTA block, and
103
  //    repeat it at the end of the document
104
  const firstNodeContainingCtaBlock = findFirstNode(
105
    newContent,
106
    (node): node is BlockNodeInNestedResponse<CtaBlock> => {
107
      return (
108
        isBlock(node) &&
109
        typeof node.item !== "string" &&
110
        node.item.__itemTypeId === "d-CHYg-rShOt3kiL6ZN1yA"
111
      );
112
    },
113
  );
114

115
  if (firstNodeContainingCtaBlock) {
116
    // duplicateBlockRecord() clones the block object and removes block IDs (this applies to nested blocks too)
117
    // This creates a new block template that can be used elsewhere or modified
118
    const duplicateCtaBlock = await duplicateBlockRecord<CtaBlock>(
119
      firstNodeContainingCtaBlock.node.item,
120
      schemaRepository,
121
    );
122
    newContent.document.children.push({
123
      type: "block",
124
      item: duplicateCtaBlock,
125
    });
126
  }
127

128
  // 2. UPDATING EXISTING BLOCKS: Either inside 'block' or 'inlineBlock' nodes
129
  newContent = mapNodes(currentArticle.content, (node) => {
130
    if (isBlock(node)) {
131
      // Normalize existing CTA blocks URLs
132
      if (
133
        node.item.__itemTypeId === "d-CHYg-rShOt3kiL6ZN1yA" &&
134
        node.item.attributes.button_url?.includes("old-domain.com")
135
      ) {
136
        return {
137
          ...node,
138
          item: buildBlockRecord<CtaBlock>({
139
            item_type: { type: "item_type", id: "d-CHYg-rShOt3kiL6ZN1yA" },
140
            id: node.item.id,
141
            button_url: node.item.attributes.button_url.replace(
142
              "old-domain.com",
143
              "new-domain.com",
144
            ),
145
            // Skip other attributes to keep them unchanged
146
          }),
147
        };
148
      }
149

150
      // If we don't need to make a change to the block (ie. Image Galleries),
151
      // just pass the block ID
152
      return { ...node, item: node.item.id };
153
    }
154

155
    // Normalize update referrals in Product Mention blocks
156
    if (isInlineBlock(node)) {
157
      if (
158
        node.item.__itemTypeId === "VGXgXav9SwG5P48frGrFxA" &&
159
        node.item.attributes.affiliate_url?.includes("ref=blog")
160
      ) {
161
        const updatedUrl = new URL(node.item.attributes.affiliate_url);
162
        updatedUrl.searchParams.set("ref", "blog");
163
        updatedUrl.searchParams.set("source", "article_mention");
164

165
        return {
166
          ...node,
167
          item: buildBlockRecord<ProductMentionInline>({
168
            item_type: { type: "item_type", id: "VGXgXav9SwG5P48frGrFxA" },
169
            id: node.item.id,
170
            affiliate_url: updatedUrl.toString(),
171
            // Keep product_name and price unchanged
172
          }),
173
        };
174
      }
175

176
      // If we don't need to make a change to the node, just pass the block ID
177
      return { ...node, item: node.item.id };
178
    }
179

180
    // Keep any other dast node unchanged
181
    return node;
182
  });
183

184
  await client.items.update<Article>(currentArticle.id, {
185
    content: newContent,
186
    // Keep title and author unchanged
187
  });
188

189
  const updatedArticleWithNestedBlocks = await client.items.find(
190
    currentArticle,
191
    { nested: true },
192
  );
193
  console.log(inspectItem(updatedArticleWithNestedBlocks));
194
}
195

196
run();