This /tasks directory holds endpoints that get data from Notion, refactor it, and then save it back to Notion.

tasks.ts handles routing in this directory.

In order to keep the API easy to look and work with, the routes in /tasks handle routing but do not get data from or save data to Notion. The functions that connect to Notion live in the /controllers directory, and are called from the endpoints in /tasks.

By convention, /controllers have the same file names as the /tasks routes that call them.

For example, the endpoint at the route in /tasks/setDemoURL.ts calls the controller in /controllers/setDemoURL.ts. (Both have setDemoURL.ts as their filename.)

To use the controller in the route:

1. import the controller at the top of the /tasks/setDemoURL.ts route:

   import { setDemoURL } from "../../controllers/setDemoURL.ts";
   

   Note that the export in the controller follows the same convention; it's also called setDemoURL.

2. Once the controller is imported, pass data to the exported function so that it can do its thing:

   const page = await setDemoURL(data);
   

   Note the function call is the exported function in the import object at the top of the route; i.e., { setDemoURL }. The setDemoURL.ts controller exports it like this:

   // /controllers/setDemoURL.ts
   export async function setDemoURL(data: any) {
     try {
       ...
     }
   };
   

Note: with this separation of routes from controllers, we also keep Notion out of the routes. This means that we don't need to initialize the Notion client in the routes in this directory. All of that happens in the /controllers. If you see the Notion client in the routes in this directory, it's probably a mistake.

All webhooks from Notion are POSTs. Notion will tell you when a webhook fails, but only if you're looking at Notion, and only with a generic and terse message. Also, Notion doesn't log errors.

Each POST in this /tasks directory logs and returns errors. Val.town logging is great and easy to access—view logs right here in the val.town UI.

Error handling and logging is a key benefit of integrating val.town into Notion. Wherever possible and reasonable, we should do the bulk of our automation work in val.town and leave the simpler and smaller automation bits to Notion.