TODO:

1. have success messages at the bottom of each step to direct the user; they may be redundant to what we see in this file but they will be in the context of Townie on val.town and that may be easier than going back and forth between Townie and this file

Use this file to guide you through the Glimpse setup process.

The instructions in this file are for you. I say that because it's important to distinguish them from the other files in this folder; those files are for Townie.

The prompts for you to enter into Townie are in code blocks, like this:

I'm a prompt for Townie

Townie will handle those prompts to write code on val.town, which—because it's on val.town—will be live. Townie will handle scaffolding the Val, user authentication, webhook authentication, caching, the front end, and metrics.

Once those bits are complete, you can add features til your heart's content.

1. a val.town account
2. vt is on your computer. If not, follow the instructions on the Github README

1. Remix this Val on val.town, and give it a new name
2. Use vt to clone the Val to your computer
3. Add a file called vars.env at the root of the Val
4. Add vars.env to the bottom of your .vtignore file, so that your environment variables aren't uploaded to val.town
5. Add all of the environment variables that this Val will use to vars.env; see "Environment variables required", below
6. Go to the Environment Variables section of your Val on val.town and import the vars.env file; once vars.env is uploaded, all of the environment variables are available to the Val and Townie, which means that val.town and Notion can connect to each other
7. Go to Townie, select this Val, and prompt Townie with this line:

Scaffold this Val with what you see in `/_townie/01-scaffold.md`

Important: These should already be in your vars.env by the time you're reading this, and vars.env should be in your vt.ignore file. If you don't have a vars.env file, or you don't have values for these variables, contact your administrator.

• NOTION_API_KEY - Your Notion integration API key
• NOTION_WEBHOOK_SECRET - Matches the X-API-KEY custom header coming from Notion webhooks to /tasks/* endpoint(s)
• GLANCE_DEMOS_DB_ID - Your Notion database ID for demos, which are personalized to prospects and have unique URLs
• GLANCE_CONTENT_DB_ID - Your Notion database ID for demo page content, which are compiled into demos
• GLANCE_INTERACTIONS_DB_ID - Your Notion database ID for pageview metrics and the like

1. In val.town, create a branch in your Val called auth
2. Go to Townie, select this Val, and then select the auth branch
3. Prompt Townie with this line:

Add auth to this Val with what you see in `/_townie/02-auth.md`

Work with Townie to make sure what appears at / is correct. Once it's correct, move on to the next step.

1. In val.town, merge auth into main
2. Delete the auth branch
3. Create a branch in your Val called webhooks
4. Go to Townie, select this Val, and then select the webhooks branch
5. Prompt Townie with this line:

Add webhook auth to this Val with what you see in `/_townie/03-webhooks.md`

1. Go to main.tsx, click the green HTTP button, and copy the URL of this Val.
2. In Notion, add a button to the Glimpse Demos database
3. Edit the automation on that button: add the URL fromj step 1 and then append /tasks/notion-webhook to it
4. Click the 'custom header' link under the webhook URL field and add this key and value: Key: X-API-KEY, Value: <x-api-key value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
5. Click the save button
6. Click the automation button in the Notion database row
7. Go to the Logs in your Val and see the latest log statement, which should outline success or failure of your webhook and webhook auth

1. Merge the webhooks branch into main
2. Delete the webhooks branch
3. Create a branch called view
4. Go to Townie, select this Val, and then select the view branch
5. Prompt Townie with this line:

Add an endpoint at `/views/glimpse/:id` by following the instructions in `/_townie/04-view.md`

For now we will just have to trust that this new endpoint works. We will verify that's true in the next few steps.

1. Prompt Townie with this line:

Add a route for `/glimpse/:id` by following the instructions in `/_townie/05-glimpse.md`.

TODO: enter directions

1. Merge the view branch into main
2. Delete the view branch
3. Create a new branch called save

Follow the instructions in `/_townie/07-save.md` to add an endpoint at `/tasks/url`.

1. In Notion, add a button to a database row in the Glimpse Demos database called "Staging: set URL"
2. Edit the automation on that button to be a webhook that hits https://<branch subdomain url>/tasks/url
3. Add the custom header for webhook auth: Key: X-API-KEY and Value: <custom header value>. (Find the value in the NOTION_WEBHOOK_SECRET key in vars.env)
4. Save the button automation
5. Click the button in Notion
6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
7. If it fails, clues as to why are in the logs
8. Go to the Logs in your Val and see the latest log statement
9. If there's an error captured there, explain that to Townie

1. Merge save into main
2. Delete the save branch
3. Create a new branch called related

Add related pages to the /glimpse/:id endpoint by following the instructions in `/_townie/08-related.md`

TODO: have Townie's success message at the end tell the user to update Notion automation with the URL on the main branch

1. In Notion, click the URL in the URL property; it should not work. That URL is from a previous branch that we deleted.
2. Go to main.tsx and get the URL for this branch
3. Edit the automation on the "Set URL" button with that URL; make sure it incudes the /tasks/url endpoint
4. Save the button automation
5. Click the button in Notion
6. You should see the URL property update with a URL to a Glimpse endpoint on val.town
7. Click the new URL
8. Authenticate
9. CTRL+F glimpseContent -- that's the object that holds the related content you see in Notion

1. Merge related into main
2. Delete the related branch
3. Create a new branch called cache

Use the instructions in /_townie/09-cache.md to implement a cache for Glimpse demos at the `/glimpse/:id` endpoint

1. merge cache into main
2. set cron interval to 1 minute

After merging into main:

CRITICAL: Go to the Val Town web UI and set the cron schedule for /backend/crons/cache_glimpse_data.ts to run every minute

Now that we have a responsive endpoint, we can iterate quickly on the front end without waiting for notion to respond and the JSON to render.

1. Delete the cache branch
2. Create a new branch called react

Use the instructions in `/_townie/10-react.md` to implement a React bootstrap for the `/glimpse/:id` endpoint

1. test /glimpse/:id endpoint in the react branch
2. if it looks good, merge react into main
3. delete react branch

1. Create a new branch called html
2. Go to townie and select the html branch
3. Enter this into townie:

TODO: make sure that the html instructions are clear about persisting the page layout with header including auth, sidenav, main content and footer.

TODO: UPDATE THE ENDPOINT BIT BELOW WITH A REAL URL BUILT BY TOWNIE LIKE IN THE LINK STEP ABOVE

use the instructions in `/_townie/11-html.md` to format the Notion data as HTML. Use this endpoint for testing: `/glimpse/20089f51-c349-803b-a940-edd14b011876

1. test /glimpse/:id endpoint in the html branch
2. if it looks good, merge html into main
3. delete html branch

1. Create a new branch called pdf-embeds
2. Go to Townie and select the pdf-embeds branch
3. Enter this into Townie:

follow the instructions in `/_townie/12-embed.md` to implement rendering for certain embed blocks

The link is rendered as a button but it 404s. We need to implement the /glimpse/:id/pdf route.

1. Create a new branch called pdf-route
2. Go to Townie and select the pdf-route branch
3. Enter this into Townie:

follow the instructions in /_townie/PDF-ROUTE.md to implement rendering for certain embed blocks