Notion usability improvements

components/notion/actions/append-block/append-block.mjs

@@ -5,8 +5,9 @@ export default {
   ...base,
   key: "notion-append-block",
   name: "Append Block to Parent",
-  description: "Creates and appends blocks to the specified parent. [See the documentation](https://developers.notion.com/reference/patch-block-children)",
-  version: "0.2.17",
+  description:
+    "Append new and/or existing blocks to the specified parent. [See the documentation](https://developers.notion.com/reference/patch-block-children)",
+  version: "0.3.0",
   type: "action",
   props: {
     notion,
@@ -16,13 +17,39 @@ export default {
         "pageId",
       ],
       label: "Parent Block ID",
-      description: "The identifier for the parent block",
+      description: "Select a parent block/page or provide its ID",
+    },
+    blockTypes: {
+      type: "string[]",
+      label: "Block Type(s)",
+      description: "Select which type(s) of block you'd like to append",
+      reloadProps: true,
+      options: [
+        {
+          label:
+            "Use objects of existing blocks (e.g. objects returned from previous steps)",
+          value: "blockObjects",
+        },
+        {
+          label: "Select existing blocks or provide their IDs",
+          value: "blockIds",
+        },
+        {
+          label: "Provide Markdown content to create new blocks with",
+          value: "markupContents",
+        },
+        {
+          label: "Provide Image URLs to create new image blocks",
+          value: "imageUrls",
+        },
+      ],
     },
     blockObjects: {
       type: "string[]",
       label: "Block Objects",
-      description: "This prop accepts an array of block objects to be appended. Using a custom expression in this prop is recommended.",
-      optional: true,
+      description:
+        "An array of block objects to be appended. You can use a custom expression to reference block objects from previous steps. [See the documentation](https://developers.notion.com/reference/block) for more information",
+      hidden: true,
     },
     blockIds: {
       propDefinition: [
@@ -31,22 +58,37 @@ export default {
       ],
       type: "string[]",
       label: "Block IDs",
-      description: "Contents of selected blocks will be appended",
-      optional: true,
+      description: "Select one or more block(s) or page(s) to append (selecting a page appends its children). You can also provide block or page IDs.",
+      hidden: true,
     },
     markupContents: {
       type: "string[]",
       label: "Markup Contents",
-      description: "Content of new blocks to append. You must use Markdown syntax [See docs](https://www.notion.so/help/writing-and-editing-basics#markdown-&-shortcuts)",
-      optional: true,
+      description:
+        "Each entry is the content of a new block to append, using Markdown syntax. [See the documentation](https://www.notion.com/help/writing-and-editing-basics#markdown-and-shortcuts) for more information",
+      hidden: true,
     },
     imageUrls: {
       type: "string[]",
       label: "Image URLs",
-      description: "List of URLs to append as image blocks",
-      optional: true,
+      description: "One or more Image URLs to append new image blocks with. [See the documentation](https://www.notion.com/help/images-files-and-media#media-block-types) for more information",
+      hidden: true,
     },
   },
+  additionalProps(currentProps) {
+    const { blockTypes } = this;
+
+    for (let prop of [
+      "blockObjects",
+      "blockIds",
+      "markupContents",
+      "imageUrls",
+    ]) {
+      currentProps[prop].hidden = !blockTypes.includes(prop);
+    }
+
+    return {};
+  },
   methods: {
     ...base.methods,
     chunkArray(array, chunkSize = 100) {
@@ -58,19 +100,20 @@ export default {
     },
   },
   async run({ $ }) {
+    const { blockTypes } = this;
     const children = [];
     // add blocks from blockObjects
-    if (this.blockObjects?.length > 0) {
+    if (blockTypes.includes("blockObjects") && this.blockObjects?.length > 0) {
       for (const obj of this.blockObjects) {
-        const child = (typeof obj === "string")
+        const child = typeof obj === "string"
           ? JSON.parse(obj)
           : obj;
         children.push(child);
       }
     }
 
     // add blocks from blockIds
-    if (this.blockIds?.length > 0) {
+    if (blockTypes.includes("blockIds") && this.blockIds?.length > 0) {
       for (const id of this.blockIds) {
         const block = await this.notion.retrieveBlock(id);
         block.children = await this.notion.retrieveBlockChildren(block);
@@ -80,15 +123,15 @@ export default {
     }
 
     // add blocks from markup
-    if (this.markupContents?.length > 0) {
+    if (blockTypes.includes("markupContents") && this.markupContents?.length > 0) {
       for (const content of this.markupContents) {
         const block = this.createBlocks(content);
         children.push(...block);
       }
     }
 
     // add image blocks
-    if (this.imageUrls?.length) {
+    if (blockTypes.includes("imageUrls") && this.imageUrls?.length) {
       for (const url of this.imageUrls) {
         children.push({
           type: "image",
@@ -111,7 +154,10 @@ export default {
     const chunks = this.chunkArray(children);
 
     for (const chunk of chunks) {
-      const { results: payload } = await this.notion.appendBlock(this.pageId, chunk);
+      const { results: payload } = await this.notion.appendBlock(
+        this.pageId,
+        chunk,
+      );
       results.push(payload);
     }
 

components/notion/actions/common/base-page-builder.mjs

@@ -39,7 +39,7 @@ export default {
      */
     _buildPropDescription(type, example) {
       const typeName = type.replace(/_/g, "-");
-      const description = `The type of this property is \`${type}\`. [See ${type} type docs here](https://developers.notion.com/reference/property-object#${typeName}).`;
+      const description = `The type of this property is \`${type}\`. [See ${type} type documentation here](https://developers.notion.com/reference/property-object#${typeName}).`;
       const descriptionExample = example
         ? `e.g. ${example}.`
         : "";

components/notion/actions/create-comment/create-comment.mjs

@@ -4,23 +4,27 @@
 export default {
   key: "notion-create-comment",
   name: "Create Comment",
-  description: "Creates a comment in a page or existing discussion thread. [See the documentation](https://developers.notion.com/reference/create-a-comment)",
-  version: "0.0.1",
+  description: "Create a comment in a page or existing discussion thread. [See the documentation](https://developers.notion.com/reference/create-a-comment)",
+  version: "0.0.2",
   type: "action",
   props: {
     notion,
+    infoLabel: {
+      type: "alert",
+      alertType: "info",
+      content: "Provide either a page ID or a discussion thread ID to create the comment under.",
+    },
     pageId: {
       propDefinition: [
         notion,
         "pageId",
       ],
-      description: "Unique identifier of a page. Either this or a Discussion ID is required (not both)",
       optional: true,
     },
     discussionId: {
       type: "string",
       label: "Discussion ID",
-      description: "A UUID identifier for a discussion thread. Either this or a Page ID is required (not both)",
+      description: "The ID of a discussion thread. [See the documentation](https://developers.notion.com/docs/working-with-comments#retrieving-a-discussion-id) for more information",
       optional: true,
     },
     comment: {
@@ -31,7 +35,7 @@
   },
   async run({ $ }) {
     if ((this.pageId && this.discussionId) || (!this.pageId && !this.discussionId)) {
-      throw new ConfigurationError("Either a Page ID or a Discussion ID is required (not both)");
+      throw new ConfigurationError("Provide either a page ID or a discussion thread ID to create the comment under");
     }
 
     const response = await this.notion._getNotionClient().comments.create({
@@ -47,7 +51,7 @@
         },
       ],
     });
-    $.export("$summary", `Successfully added comment with ID: ${response.id}`);
+    $.export("$summary", `Successfully created comment (ID: ${response.id})`);
     return response;
   },
 };

components/notion/actions/create-page-from-database/create-page-from-database.mjs

@@ -6,8 +6,8 @@
   ...base,
   key: "notion-create-page-from-database",
   name: "Create Page from Database",
-  description: "Creates a page from a database. [See the documentation](https://developers.notion.com/reference/post-page)",
-  version: "0.1.15",
+  description: "Create a page from a database. [See the documentation](https://developers.notion.com/reference/post-page)",
+  version: "0.1.16",
   type: "action",
   props: {
     notion,
@@ -17,7 +17,7 @@
         "databaseId",
       ],
       label: "Parent Database ID",
-      description: "The identifier for a Notion parent page",
+      description: "Select a parent database or provide a database ID",
       reloadProps: true,
     },
     metaTypes: {
@@ -37,16 +37,16 @@
       ],
       reloadProps: true,
     },
     alert: {
       type: "alert",
       alertType: "info",
-      content: "This action will create an empty page by default. To add content, use the `pageContent` prop below.",
+      content: "This action will create an empty page by default. To add content, use the `Page Content` prop below.",
     },
     pageContent: {
-      type: "string",
-      label: "Page Content",
-      description: "Content of the page. You can use Markdown syntax [See docs](https://www.notion.so/help/writing-and-editing-basics#markdown-&-shortcuts)",
-      optional: true,
+      propDefinition: [
+        notion,
+        "pageContent",
+      ],
     },
   },
   async additionalProps() {

components/notion/actions/create-page/create-page.mjs

@@ -6,8 +6,8 @@ export default {
   ...base,
   key: "notion-create-page",
   name: "Create Page",
-  description: "Creates a page from a parent page. The only valid property is *title*. [See the documentation](https://developers.notion.com/reference/post-page)",
-  version: "0.2.13",
+  description: "Create a page from a parent page. [See the documentation](https://developers.notion.com/reference/post-page)",
+  version: "0.2.14",
   type: "action",
   props: {
     notion,
@@ -17,7 +17,7 @@ export default {
         "pageId",
       ],
       label: "Parent Page ID",
-      description: "The identifier for a Notion parent page",
+      description: "Select a parent page or provide a page ID",
       reloadProps: true,
     },
     title: {
@@ -33,10 +33,10 @@ export default {
       ],
     },
     pageContent: {
-      type: "string",
-      label: "Page Content",
-      description: "Content of the page. You can use Markdown syntax [See docs](https://www.notion.so/help/writing-and-editing-basics#markdown-&-shortcuts)",
-      optional: true,
+      propDefinition: [
+        notion,
+        "pageContent",
+      ],
     },
   },
   async additionalProps() {

components/notion/actions/duplicate-page/duplicate-page.mjs

@@ -6,8 +6,8 @@ export default {
   ...base,
   key: "notion-duplicate-page",
   name: "Duplicate Page",
-  description: "Creates a new page copied from an existing page block. [See the documentation](https://developers.notion.com/reference/post-page)",
-  version: "0.0.9",
+  description: "Create a new page copied from an existing page block. [See the documentation](https://developers.notion.com/reference/post-page)",
+  version: "0.0.10",
   type: "action",
   props: {
     notion,
@@ -16,7 +16,7 @@ export default {
         notion,
         "pageId",
       ],
-      description: "The page to copy",
+      description: "Select a page to copy or provide a page ID",
     },
     title: {
       propDefinition: [
@@ -31,7 +31,7 @@ export default {
         "pageId",
       ],
       label: "Parent Page ID",
-      description: "The parent page of the new page being created",
+      description: "Select a parent page for the new page being created, or provide the ID of a parent page",
     },
   },
   async run({ $ }) {
@@ -65,7 +65,7 @@ export default {
 
     const results = await this.notion.createPage(page);
     const pageName = this.notion.extractPageTitle(results);
-    $.export("$summary", `Successfully created the new page, "[${pageName}](${results.url})"`);
+    $.export("$summary", `Successfully created page "[${pageName}](${results.url})"`);
     return results;
   },
 };

components/notion/actions/query-database/query-database.mjs

@@ -4,8 +4,8 @@ import utils from "../../common/utils.mjs";
 export default {
   key: "notion-query-database",
   name: "Query Database",
-  description: "Query a database. [See the docs](https://developers.notion.com/reference/post-database-query)",
-  version: "0.0.8",
+  description: "Query a database with a specified filter. [See the documentation](https://developers.notion.com/reference/post-database-query)",
+  version: "0.0.9",
   type: "action",
   props: {
     notion,
@@ -16,8 +16,8 @@ export default {
       ],
     },
     filter: {
-      label: "Filter",
-      description: "The filter to query. [See how filters work here](https://developers.notion.com/reference/post-database-query-filter). E.g. { \"property\": \"Email\", \"rich_text\": { \"contains\": \"gmail.com\" } }",
+      label: "Filter (query)",
+      description: "The filter to apply, as a JSON-stringified object. [See the documentation for available filters](https://developers.notion.com/reference/post-database-query-filter). Example: `{ \"property\": \"Name\", \"title\": { \"contains\": \"title to search for\" } }`",
       type: "string",
     },
   },
@@ -28,7 +28,11 @@ export default {
       filter: utils.parseStringToJSON(filter),
     });
 
-    $.export("$summary", "Retrieved database query result");
+    const length = response?.results?.length;
+
+    $.export("$summary", `Retrieved ${length} result${length === 1
+      ? ""
+      : "s"}`);
 
     return response;
   },