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

The instructions in this file are for you. It's important to distinguish the instructions in this file from the instructions in the other files in this folder, which 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 use those prompts to scaffold Glimpse, add then add features like user authentication, webhook authentication, caching, a React front end, and a way to collect metrics.

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

1. a val.town account
2. vt on your computer. If not, follow the instructions on the Github README
3. Remix this Val on val.town, and give it a new name
4. Use vt to clone the Val to your computer
5. Add a file called vars.env at the root of the Val
6. Add vars.env to the bottom of your .vtignore file, so that your environment variables aren't uploaded to val.town (they're secret)
7. Add your environment variables to vars.env; if you don't have them, contact your administrator
8. Go to the Environment Variables section of your Val on val.town and import the vars.env file

Once your environment variables are on val.town (i.e., once vars.env is uploaded to val.town), all of the environment variables are available to the Val and Townie, which means that val.town and Notion are connected to each other. Note that environment variables are secret and secure on val.town.

Important: These environment variables should already be in your Val on val.town by the time you're reading this. If you're not sure, 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

Once the prerequisite steps are complete, you can start instructing Townie to build this Val by pasting instructions from code blocks in this file into Townie.

On branching: in the steps that follow, you will see instructions for you to paste and run in Townie (in code blocks) and a few instructions for you, mostly numbered steps related to creating and deleting "branches."

Branches are important in development, even AI-enabled development. (Maybe more so.) With branches, we protect the code that's already running and working in our app while we develop new features. Once the code in a feature branch meets our needs, we can merge it into the main branch. Learn more about branching on val.town

Ok, now to the fun stuff.

1. Go to Townie, select this Val, and prompt Townie with this line:

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

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 from 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