Add typing hints for page update (WIP)

examples/typed-page-update/README.md

@@ -0,0 +1,34 @@
+# Sample Integration: Types Page Update
+
+## About the Integration
+
+This Notion integration simply updates a page, but the request body is validated by a given page type.
+
+## Running Locally
+
+### 1. Setup your local project
+
+```zsh
+# Clone this repository locally
+git clone https://github.com/makenotion/notion-sdk-js.git
+
+# Switch into this project
+cd notion-sdk-js/examples/typed-page-update
+# Install the dependencies
+npm install
+```
+
+### 2. Set your environment variables in a `.env` file
+
+```zsh
+NOTION_KEY=<your-notion-api-key>
+PAGE_ID=<page-id>
+```
+
+You can create your Notion API key [here](https://www.notion.com/my-integrations).
+
+### 3. Run code
+
+```zsh
+npx node-ts index.ts
+```

examples/typed-page-update/index.ts

@@ -0,0 +1,68 @@
+// Find the official Notion API client @ https://  github.com/makenotion/notion-sdk-js/
+// npm install @notionhq/client
+import { Client, LogLevel } from "@notionhq/client"
+
+import { config } from "dotenv"
+import { Page, TitlePropertyValue } from "../../build/src/api-types"
+
+config()
+
+const notion = new Client({
+  auth: process.env["NOTION_KEY"],
+  logLevel: LogLevel.DEBUG,
+})
+
+type PrecisePage = Page & {
+  properties: {
+    Title: TitlePropertyValue
+  }
+}
+
+export async function updatePage(pageId: string): Promise<void> {
+  await notion.pages.update<PrecisePage>({
+    page_id: pageId,
+    properties: {
+      Title: {
+        type: "title",
+        id: "azer",
+        title: [
+          {
+            type: "text",
+            text: {
+              content: "azer",
+            },
+          },
+        ],
+      },
+      // Won't be validated by Typescript because Title is a Title type property
+      // Title: {
+      //   type: "title",
+      //   id: "azer",
+      //   select: [
+      //     {
+      //       type: "text",
+      //       text: {
+      //         content: "azer",
+      //       },
+      //     },
+      //   ],
+      // },
+
+      // Won't be validated by Typescript because OtherProperty hasn't been defined in PrecisePage
+      // OtherProperty: {
+      //   type: "title",
+      //   id: "azer",
+      //   text: [
+      //     {
+      //       type: "text",
+      //       text: {
+      //         content: "azer",
+      //       },
+      //     },
+      //   ],
+      // },
+    },
+  })
+}
+
+updatePage(process.env["PAGE_ID"] ?? "")

examples/typed-page-update/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "get-typed-page",
+  "version": "1.0.0",
+  "description": "**TODO**",
+  "main": "index.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Sc0ra",
+  "license": "MIT",
+  "dependencies": {
+    "dotenv": "^8.2.0",
+    "@notionhq/client": "file:../.."
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^4.22.0",
+    "@typescript-eslint/parser": "^4.22.0",
+    "eslint": "^7.24.0",
+    "markdown-link-check": "^3.8.7",
+    "prettier": "^2.3.0",
+    "typescript": "^4.2.4",
+    "ts-node": "^9.1.1"
+  }
+}

examples/typed-page-update/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+    // Recommended Node options have been incorporated from https://github.com/tsconfig/bases/blob/master/bases/node14.json
+
+    // Node LTS Fermium (14.x) has mostly complete support for ES2019 (as reported by https://node.green/)
+    "target": "ES2019",
+    "module": "commonjs",
+    // "esModuleInterop": true,
+
+    // Overrides default in order to remove "dom" because this package shouldn't assume the presence of browser APIs
+    "lib": ["ES2019"],
+
+    // Emit location
+    "outDir": "build",
+
+    // Emit sourcemaps
+    "declarationMap": true,
+    "sourceMap": true,
+    "inlineSources": true,
+
+    // Emit type definitions
+    "declaration": true,
+
+    // Strict mode
+    "strict": true,
+
+    // Linter style rules
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "forceConsistentCasingInFileNames": true
+  },
+
+  "include": ["./index.ts"]
+}

src/Client.ts

@@ -50,6 +50,7 @@ import got, {
   Headers as GotHeaders,
   Agents as GotAgents,
 } from "got"
+import { Page } from "./api-types"
 
 export interface ClientOptions {
   auth?: string
@@ -275,8 +276,8 @@ export default class Client {
     /**
      * Update page properties
      */
-    update: (
-      args: WithAuth<PagesUpdateParameters>
+    update: <PageType extends Page | void = void>(
+      args: WithAuth<PagesUpdateParameters<PageType>>
     ): Promise<PagesUpdateResponse> => {
       return this.request<PagesUpdateResponse>({
         path: pagesUpdate.path(args),

src/api-endpoints.ts

@@ -23,6 +23,7 @@ import {
   SearchFilter,
   InputPropertyValue,
   Property,
+  InputValueMapFromPage,
 } from "./api-types"
 
 // TODO: type assertions to verify that each interface is synchronized to the list of keys in the runtime value below.
@@ -220,14 +221,16 @@ interface PagesUpdatePathParameters {
 }
 interface PagesUpdateQueryParameters {}
 
-interface PagesUpdateBodyParameters {
-  properties: InputPropertyValueMap
+interface PagesUpdateBodyParameters<PageType extends Page | void = void> {
+  properties: PageType extends Page
+    ? InputValueMapFromPage<PageType>
+    : InputPropertyValueMap
 }
 
-export interface PagesUpdateParameters
+export interface PagesUpdateParameters<PageType extends Page | void = void>
   extends PagesUpdatePathParameters,
     PagesUpdateQueryParameters,
-    PagesUpdateBodyParameters {}
+    PagesUpdateBodyParameters<PageType> {}
 export interface PagesUpdateResponse extends Page {}
 
 export const pagesUpdate = {

src/api-types.ts

@@ -614,6 +614,19 @@ export type InputPropertyValueWithRequiredId =
   | LastEditedTimePropertyValue
   | LastEditedByPropertyValue
 
+type InputPropertyValueFromPropertyValue<T extends PropertyValue> =
+  T extends TitlePropertyValue
+    ? TitleInputPropertyValue
+    : T extends RichTextPropertyValue
+    ? RichTextInputPropertyValue
+    : T
+
+export type InputValueMapFromPage<PageType extends Page> = {
+  [property in keyof PageType["properties"]]: InputPropertyValueFromPropertyValue<
+    PageType["properties"][property]
+  >
+}
+
 export interface PropertyValueBase {
   id: string
   type: string