Request for more documentation around Block type usage

[williamlmao]

Hey there! This might be a product of me being somewhat of a typescript/notion api noob, so please excuse me if that's the case.

I'm trying to define a function that allows me to append a paragraph to a page. I'd like to use typescript to ensure that the paragraph parameter is correctly typed. I'm able to import the Block<"paragraph"> type from this library, but the issue is that the type definition contains all of the parameters of the paragraph type, some of which are generated after creation. For example, it'd be impossible for me to create a paragraph object that contains created_time.

async function appendParagraphToPage(paragraph: Block<"paragraph">) {
  const blockId = await getEntryPageIdFromDate();
  console.log("block id", blockId);
  const response = await notion.blocks.children.append({
    block_id: blockId,
    children: [paragraph],
  });
  console.log(response);
}

const paragraph = {
  paragraph: {
    rich_text: [
      {
        type: "text",
        text: {
          content:
            "Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
        },
      },
    ],
  },
};

appendParagraphToPage(paragraph);

Is there a type that can be used to check that only required parameters are present?

Additionally, I'm finding it somewhat difficult to understand how to use the Block types. Some examples included in the documentation would be really helpful for noobs like me. Thank you so much!

[justjake]

All the types and functions in the library are focused on reading data, so they don’t work well for your writing data use-case. We’ll need a new set of types maybe called CreateBlock<T> that work in a similar way for the write-side types.

[williamlmao]

Ah got it. Thanks for the response! I decided to continue building in vanilla JS for speed but if I switch back to TS I'll send over any write-side types I write out.