Glimpse

` tag. The goal is to render this data as properly formatted HTML while maintaining the existing architecture and caching system.\n\n## Current Architecture Understanding\n\n- Backend fetches Notion data via `getGlimpseData()` in `/backend/controllers/glimpse.controller.ts`\n- Data structure includes main page + `glimpseContent` array of related pages\n- Each glimpse content item has: `{id, properties, blocks}` where `blocks` is the direct array (not `blocks.results`)\n- Frontend uses React with server-side data injection via `window.__INITIAL_DATA__`\n- Current display: `GlimpseView.tsx` renders JSON in `
` tag\n\n## Implementation Steps\n\n### 1\\. Create NotionRenderer Component\n\nCreate `/frontend/components/NotionRenderer.tsx`:\n\n    /** @jsxImportSource https://esm.sh/react@18.2.0 */\n    import React from \"https://esm.sh/react@18.2.0?deps=react@18.2.0\";\n    import { BlockRenderer } from \"./BlockRenderer.tsx\";\n\n    interface NotionRendererProps {\n      data: any;\n    }\n\n    export function NotionRenderer({ data }: NotionRendererProps) {\n      if (!data) {\n        return No data available
;\n      }\n\n      // Handle both direct data and wrapped service response\n      const mainPage = data.data || data;\n      const glimpseContent = mainPage.glimpseContent || [];\n\n      return (\n        \n          {/* Main Page Header */}\n          \n            \n              {getPageTitle(mainPage)}\n            
\n            {/* Only show Name property if it exists and is not already shown as title */}\n            {mainPage.properties && (\n              \n                {Object.entries(mainPage.properties)\n                  .filter(([key, value]) => key === 'Name' && (value as any)?.type !== 'title')\n                  .map(([key, value]) => (\n                    \n                  ))}\n              
\n            )}\n          
\n\n          {/* Glimpse Content */}\n          {glimpseContent.length > 0 ? (\n            \n              \n                Content ({glimpseContent.length} pages)\n              
\n              {glimpseContent.map((contentPage: any, index: number) => (\n                \n              ))}\n            
\n          ) : (\n            \n              No glimpse content available for this page.\n            
\n          )}\n        
\n      );\n    }\n\n    function getPageTitle(page: any): string {\n      // Try to extract title from properties\n      if (page.properties) {\n        const titleProp = Object.values(page.properties).find((prop: any) => prop.type === 'title');\n        if (titleProp && (titleProp as any).title?.[0]?.plain_text) {\n          return (titleProp as any).title[0].plain_text;\n        }\n      }\n\n      // Fallback to page object title if available\n      if (page.object === 'page' && page.properties?.title?.title?.[0]?.plain_text) {\n        return page.properties.title.title[0].plain_text;\n      }\n\n      return 'Untitled';\n    }\n\n    function PropertyRenderer({ name, property }: { name: string; property: any }) {\n      if (!property || property.type === 'title') return null;\n\n      const renderPropertyValue = () => {\n        switch (property.type) {\n          case 'rich_text':\n            return property.rich_text?.map((text: any, i: number) => (\n              {text.plain_text}\n            )).join('') || '';\n          case 'number':\n            return property.number?.toString() || '';\n          case 'select':\n            return property.select?.name || '';\n          case 'multi_select':\n            return property.multi_select?.map((item: any) => item.name).join(', ') || '';\n          case 'date':\n            return property.date?.start || '';\n          case 'checkbox':\n            return property.checkbox ? '✓' : '✗';\n          case 'url':\n            return property.url ? (\n              \n                {property.url}\n              \n            ) : '';\n          case 'email':\n            return property.email ? (\n              \n                {property.email}\n              \n            ) : '';\n          case 'phone_number':\n            return property.phone_number || '';\n          case 'relation':\n            return `${property.relation?.length || 0} related items`;\n          default:\n            return JSON.stringify(property);\n        }\n      };\n\n      const value = renderPropertyValue();\n      if (!value) return null;\n\n      return (\n        \n          {name}
\n          {value}
\n        
\n      );\n    }\n\n    function ContentPageRenderer({ page }: { page: any }) {\n      const title = getPageTitle(page);\n      // CRITICAL: blocks are directly on page object, not page.blocks.results\n      const blocks = page.blocks || [];\n\n      return (\n        \n          {title !== 'Untitled' && (\n            {title}
\n          )}\n\n          {/* Render blocks - NO page properties for content pages */}\n          {blocks.length > 0 ? (\n            \n              \n            
\n          ) : (\n            \n              No content blocks found for this page.\n            
\n          )}\n        
\n      );\n    }\n\n    function BlockGroupRenderer({ blocks }: { blocks: any[] }) {\n      const groupedBlocks: any[] = [];\n      let currentGroup: any = null;\n\n      for (let i = 0; i < blocks.length; i++) {\n        const block = blocks[i];\n\n        if (block.type === 'numbered_list_item') {\n          if (!currentGroup || currentGroup.type !== 'numbered_list') {\n            // Start a new numbered list group\n            currentGroup = {\n              type: 'numbered_list',\n              items: [block]\n            };\n            groupedBlocks.push(currentGroup);\n          } else {\n            // Add to existing numbered list group\n            currentGroup.items.push(block);\n          }\n        } else if (block.type === 'bulleted_list_item') {\n          if (!currentGroup || currentGroup.type !== 'bulleted_list') {\n            // Start a new bulleted list group\n            currentGroup = {\n              type: 'bulleted_list',\n              items: [block]\n            };\n            groupedBlocks.push(currentGroup);\n          } else {\n            // Add to existing bulleted list group\n            currentGroup.items.push(block);\n          }\n        } else {\n          // Non-list item, reset current group\n          currentGroup = null;\n          groupedBlocks.push(block);\n        }\n      }\n\n      return (\n        <>\n          {groupedBlocks.map((item, index) => {\n            if (item.type === 'numbered_list') {\n              return (\n                \n                  {item.items.map((block: any, itemIndex: number) => (\n                    \n                      \n                    
\n                  ))}\n                
\n              );\n            } else if (item.type === 'bulleted_list') {\n              return (\n                \n                  {item.items.map((block: any, itemIndex: number) => (\n                    \n                      \n                    
\n                  ))}\n                
\n              );\n            } else {\n              return ;\n            }\n          })}\n        \n      );\n    }\n\n### 2\\. Create BlockRenderer Component\n\nCreate `/frontend/components/BlockRenderer.tsx`:\n\n    /** @jsxImportSource https://esm.sh/react@18.2.0 */\n    import React from \"https://esm.sh/react@18.2.0?deps=react@18.2.0\";\n\n    interface BlockRendererProps {\n      block: any;\n      listContext?: {\n        type: 'numbered' | 'bulleted';\n        index: number;\n      };\n    }\n\n    // Helper function to group blocks for nested lists\n    function groupBlocks(blocks: any[]): any[] {\n      const groupedBlocks: any[] = [];\n      let currentGroup: any = null;\n\n      for (let i = 0; i < blocks.length; i++) {\n        const block = blocks[i];\n\n        if (block.type === 'numbered_list_item') {\n          if (!currentGroup || currentGroup.type !== 'numbered_list') {\n            currentGroup = {\n              type: 'numbered_list',\n              items: [block]\n            };\n            groupedBlocks.push(currentGroup);\n          } else {\n            currentGroup.items.push(block);\n          }\n        } else if (block.type === 'bulleted_list_item') {\n          if (!currentGroup || currentGroup.type !== 'bulleted_list') {\n            currentGroup = {\n              type: 'bulleted_list',\n              items: [block]\n            };\n            groupedBlocks.push(currentGroup);\n          } else {\n            currentGroup.items.push(block);\n          }\n        } else {\n          currentGroup = null;\n          groupedBlocks.push(block);\n        }\n      }\n\n      return groupedBlocks;\n    }\n\n    // Helper component to render grouped blocks\n    function NestedBlockRenderer({ blocks }: { blocks: any[] }) {\n      const groupedBlocks = groupBlocks(blocks);\n\n      return (\n        <>\n          {groupedBlocks.map((item, index) => {\n            if (item.type === 'numbered_list') {\n              return (\n                \n                  {item.items.map((block: any, itemIndex: number) => (\n                    \n                      \n                    
\n                  ))}\n                
\n              );\n            } else if (item.type === 'bulleted_list') {\n              return (\n                \n                  {item.items.map((block: any, itemIndex: number) => (\n                    \n                      \n                    
\n                  ))}\n                
\n              );\n            } else {\n              return ;\n            }\n          })}\n        \n      );\n    }\n\n    export function BlockRenderer({ block, listContext }: BlockRendererProps) {\n      if (!block || !block.type) {\n        return null;\n      }\n\n      const blockData = block[block.type] || {};\n      const children = block.children || [];\n\n      const renderChildren = () => {\n        if (children.length === 0) return null;\n        return (\n          \n            {children.map((child: any, index: number) => (\n              \n            ))}\n          
\n        );\n      };\n\n      switch (block.type) {\n        case 'paragraph':\n          return (\n            \n              \n              {renderChildren()}\n            
\n          );\n\n        case 'heading_1':\n          return (\n            \n              \n                \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'heading_2':\n          return (\n            \n              \n                \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'heading_3':\n          return (\n            \n              \n                \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'bulleted_list_item':\n          if (listContext?.type === 'bulleted') {\n            // When rendered inside , render content inline to avoid line breaks after bullets\n            return (\n              <>\n                \n                {children.length > 0 && (\n                  \n                )}\n              \n            );\n          }\n          // Fallback for standalone bulleted list items\n          return (\n            \n              \n                \n                \n                  \n                  {renderChildren()}\n                
\n              
\n            
\n          );\n\n        case 'numbered_list_item':\n          if (listContext?.type === 'numbered') {\n            // When rendered inside , render content inline to avoid line breaks after numbers\n            return (\n              <>\n                \n                {children.length > 0 && (\n                  \n                )}\n              \n            );\n          }\n          // Fallback for standalone numbered list items\n          return (\n            \n              \n                1.\n                \n                  \n                  {renderChildren()}\n                
\n              
\n            
\n          );\n\n        case 'to_do':\n          return (\n            \n              \n                \n                \n                  \n                  {renderChildren()}\n                
\n              
\n            
\n          );\n\n        case 'quote':\n          return (\n            \n              \n                \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'code':\n          return (\n            \n              \n                \n                  \n                \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'callout':\n          const renderCalloutIcon = () => {\n            if (!blockData?.icon) return '💡';\n\n            if (blockData.icon.type === 'emoji') {\n              return blockData.icon.emoji;\n            } else if (blockData.icon.type === 'external' && blockData.icon.external?.url) {\n              return (\n                \n              );\n            } else if (blockData.icon.type === 'file' && blockData.icon.file?.url) {\n              return (\n                \n              );\n            }\n\n            return '💡';\n          };\n\n          return (\n            \n              \n                \n                  \n                    {renderCalloutIcon()}\n                  \n                  \n                    \n                    {/* CRITICAL: Render children INSIDE callout container */}\n                    {children.length > 0 && (\n                      \n                        {children.map((child: any, index: number) => (\n                          \n                        ))}\n                      
\n                    )}\n                  
\n                
\n              
\n            
\n          );\n\n        case 'divider':\n          return (\n            \n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'image':\n          const imageUrl = blockData?.file?.url || blockData?.external?.url;\n          const caption = blockData?.caption || [];\n          return (\n            \n              {imageUrl && (\n                 0 ? caption[0].plain_text : 'Image'}\n                  className=\"max-w-full h-auto rounded\"\n                />\n              )}\n              {caption.length > 0 && (\n                \n                  \n                
\n              )}\n              {renderChildren()}\n            
\n          );\n\n        case 'video':\n          const videoUrl = blockData?.file?.url || blockData?.external?.url;\n          return (\n            \n              {videoUrl && (\n                \n              )}\n              {renderChildren()}\n            
\n          );\n\n        case 'embed':\n          return (\n            \n              \n                \n                  Embedded content: {blockData?.url}\n                
\n              
\n              {renderChildren()}\n            
\n          );\n\n        case 'bookmark':\n          return (\n            \n              \n                \n                  {blockData?.caption?.[0]?.plain_text || blockData?.url}\n                
\n                {blockData?.url}
\n              \n              {renderChildren()}\n            
\n          );\n\n        case 'table':\n          return (\n            \n              \n                \n                  {children.map((row: any, rowIndex: number) => (\n                    \n                      {row.table_row?.cells?.map((cell: any, cellIndex: number) => (\n                        \n                      ))}\n                    \n                  ))}\n                \n              \n                          \n                        
\n            
\n          );\n\n        case 'table_row':\n          return null;\n\n        default:\n          return (\n            \n              \n                Unsupported block type: {block.type}\n              
\n              {blockData?.rich_text && (\n                \n                  \n                
\n              )}\n              {renderChildren()}\n            
\n          );\n      }\n    }\n\n    function RichTextRenderer({ richText }: { richText: any[] }) {\n      if (!richText || richText.length === 0) {\n        return null;\n      }\n\n      return (\n        <>\n          {richText.map((text, index) => {\n            let element = {text.plain_text};\n\n            if (text.annotations) {\n              if (text.annotations.bold) {\n                element = {element};\n              }\n              if (text.annotations.italic) {\n                element = {element};\n              }\n              if (text.annotations.strikethrough) {\n                element = {element};\n              }\n              if (text.annotations.underline) {\n                element = {element};\n              }\n              if (text.annotations.code) {\n                element = {text.plain_text};\n              }\n              if (text.annotations.color && text.annotations.color !== 'default') {\n                const colorClass = getColorClass(text.annotations.color);\n                element = {element};\n              }\n            }\n\n            if (text.href) {\n              element = (\n                \n                  {element}\n                \n              );\n            }\n\n            return element;\n          })}\n        \n      );\n    }\n\n    function getColorClass(color: string): string {\n      const colorMap: { [key: string]: string } = {\n        'gray': 'text-gray-600',\n        'brown': 'text-amber-700',\n        'orange': 'text-orange-600',\n        'yellow': 'text-yellow-600',\n        'green': 'text-green-600',\n        'blue': 'text-blue-600',\n        'purple': 'text-purple-600',\n        'pink': 'text-pink-600',\n        'red': 'text-red-600',\n        'gray_background': 'bg-gray-100',\n        'brown_background': 'bg-amber-100',\n        'orange_background': 'bg-orange-100',\n        'yellow_background': 'bg-yellow-100',\n        'green_background': 'bg-green-100',\n        'blue_background': 'bg-blue-100',\n        'purple_background': 'bg-purple-100',\n        'pink_background': 'bg-pink-100',\n        'red_background': 'bg-red-100',\n      };\n\n      return colorMap[color] || '';\n    }\n\n### 3\\. Update GlimpseView Component\n\nModify `/frontend/components/GlimpseView.tsx`:\n\n    // Add import\n    import React, { useState } from \"https://esm.sh/react@18.2.0?deps=react@18.2.0\";\n    import { NotionRenderer } from \"./NotionRenderer.tsx\";\n\n    // Add state to component\n    export function GlimpseView({ data, userEmail }: GlimpseViewProps) {\n      const [showDebug, setShowDebug] = useState(false);\n\n    // Replace main content section\n            \n              \n                {/* Debug toggle */}\n                \n                   setShowDebug(!showDebug)}\n                    className=\"px-3 py-1 text-sm bg-gray-100 hover:bg-gray-200 rounded border\"\n                  >\n                    {showDebug ? 'Hide' : 'Show'} Raw JSON\n                  \n                
\n\n                {showDebug ? (\n                  \n                    Raw Glimpse Data
\n                    \n                      {JSON.stringify(data, null, 2)}\n                    
\n                  
\n                ) : (\n                  \n                )}\n              
\n            
\n\n### 4\\. Update Documentation\n\nUpdate `/frontend/README.md` to document the new HTML rendering functionality and supported block types.\n\n## Critical Implementation Notes\n\n1.  **Data Structure**: The service returns item.blocks.results which the controller assigns to blocks property, so the frontend receives glimpseContent[].blocks as a direct array (not nested under a results property)\"\n2.  **Callout Children**: Must render children INSIDE the callout container, not after it\n3.  **Icon Handling**: Support emoji, external, and file icon types for callouts\n4.  **Property Filtering**: Only show \"Name\" property for main page, no properties for content pages\n5.  **Rich Text**: Handle all formatting (bold, italic, colors, links) and nested structures\n6.  **Error Handling**: Provide fallbacks for missing data and unsupported block types\n7.  **List Context**: Pass `listContext` parameter to BlockRenderer for proper list item rendering\n8.  **List Formatting**: Use `listStylePosition: 'outside'` to prevent line breaks after numbers/bullets\n9.  **Nested List Rendering**: List item content must render as React Fragments (`<>`) when inside grouped lists to avoid block-level line breaks\n10. **List Grouping**: Consecutive list items must be grouped into proper `` and `` elements for correct browser numbering\n11. **Nested List Helpers**: Use `NestedBlockRenderer` component for handling nested lists within list items\n12. **Browser-Native Numbering**: Leverage browser's automatic list numbering with semantic HTML elements\n\n## Expected Result\n\n- `/glimpse/:id` renders formatted HTML instead of JSON\n- Debug toggle allows switching between HTML and JSON views\n- All major Notion block types render correctly with proper styling\n- Nested content (especially in callouts) is properly contained\n- Custom icons display correctly in callouts\n- Clean layout with minimal metadata display\n- Proper list numbering with browser-native `` and `` elements\n- No line breaks after list numbers or bullets\n- Correct nested list numbering (nested lists start from 1)\n- Proper indentation for nested lists\n",[],[181,385],"f1c348a6-7387-11f0-8a1d-0224a6c84d84","10-react.md","01988473-765e-7709-bfba-ad6528f459e1",["D",1754568816144],"# Complete Implementation Instructions: React Bootstrap for Glimpse Endpoint (REVISED)\n\n\\=================================================================================\n\n## Objective\n\n---\n\nTransform an existing JSON-only `/glimpse/:id` endpoint to serve a professional HTML page with React, while maintaining JSON API compatibility.\n\n## Prerequisites\n\n---\n\n- Existing `/glimpse/:id` endpoint that returns JSON data\n- Hono-based backend with authentication middleware\n- User email available via `c.get(\"userEmail\")` from auth context\n- LastLogin authentication system with `/auth/logout` endpoint\n\n## Implementation Steps\n\n---\n\n### 1\\. Create Frontend Directory Structure\n\n    /frontend/\n    ├── glimpse.html\n    ├── glimpse.tsx\n    ├── components/\n    │   └── GlimpseView.tsx\n    └── README.md (update existing)\n\n### 2\\. Create `/frontend/glimpse.html`\n\nClean HTML shell that loads the React entry point:\n\n    \n    \n    \n        \n        \n        Glimpse\n        \n        \n    \n    \n        
\n        \n    \n    \n\n### 3\\. Create `/frontend/glimpse.tsx`\n\nReact entry point that bootstraps the application:\n\n    /** @jsxImportSource https://esm.sh/react@18.2.0 */\n    import React from \"https://esm.sh/react@18.2.0?deps=react@18.2.0\";\n    import { createRoot } from \"https://esm.sh/react-dom@18.2.0/client?deps=react@18.2.0,react-dom@18.2.0\";\n    import { GlimpseView } from \"./components/GlimpseView.tsx\";\n\n    // Get data injected by the server\n    const data = (window as any).__INITIAL_DATA__;\n    const userEmail = (window as any).__USER_EMAIL__;\n\n    // Render the application\n    const root = createRoot(document.getElementById('root')!);\n    root.render();\n\n### 4\\. Create `/frontend/components/GlimpseView.tsx`\n\nPure React component for displaying glimpse data:\n\n    /** @jsxImportSource https://esm.sh/react@18.2.0 */\n    import React from \"https://esm.sh/react@18.2.0?deps=react@18.2.0\";\n\n    interface GlimpseViewProps {\n      data: any;\n      userEmail?: string;\n    }\n\n    export function GlimpseView({ data, userEmail }: GlimpseViewProps) {\n      return (\n        \n          {/* Header */}\n          \n            Glimpse
\n            \n              {userEmail || 'user@example.com'}\n              \n                Logout\n              \n            
\n          
\n\n          {/* Main layout with sidenav and content */}\n          \n            {/* Sidenav */}\n            \n              Navigation
\n              \n                \n                  \n                    Dashboard\n                  \n                
\n                \n                  \n                    Current Glimpse\n                  \n                
\n              
\n            
\n\n            {/* Main content */}\n            \n              \n                Glimpse Data
\n                \n                  {JSON.stringify(data, null, 2)}\n                
\n              
\n            
\n          
\n\n          {/* Footer */}\n          \n            © 2024 Glimpse Platform
\n          
\n        
\n      );\n    }\n\n### 5\\. Update `/frontend/README.md`\n\nReplace existing content with:\n\n    # Frontend\n\n    Client-side files that render in the browser.\n\n    ## Structure\n\n    - `glimpse.html` - Clean HTML shell that loads React entry point\n    - `glimpse.tsx` - React bootstrap/entry point that gathers data and initializes the app\n    - `components/` - React components\n      - `GlimpseView.tsx` - Component for displaying JSON data in glimpse pages\n\n    ## Glimpse Pages\n\n    The glimpse functionality uses a 3-layer architecture:\n\n    1. **HTML Shell** (`glimpse.html`) - Minimal HTML that loads the React entry point\n    2. **React Bootstrap** (`glimpse.tsx`) - Gathers server-injected data and renders the main component\n    3. **UI Component** (`GlimpseView.tsx`) - Pure React component that receives data as props\n\n    ### Data Flow\n\n    1. Backend fetches cached or live Notion data\n    2. Data is injected into HTML template as `window.__INITIAL_DATA__`\n    3. React entry point reads the data and passes it to the component\n    4. Component renders the data in a `` tag for JSON display\n\n    ## API Compatibility\n\n    The glimpse endpoint maintains backward compatibility:\n    - Default: Serves HTML page with React\n    - `?format=json` or `Accept: application/json` header: Returns JSON data\n\n    ## Future Enhancements\n\n    When ready to format Notion data as HTML instead of JSON:\n    1. Modify the `GlimpseView` component in `components/GlimpseView.tsx`\n    2. Add proper Notion block rendering logic\n    3. The entry point (`glimpse.tsx`) handles data gathering, so UI changes only affect the component\n\n### 6\\. Modify Glimpse Controller\n\nIn `/backend/controllers/glimpse.controller.ts`:\n\n**Add imports:**\n\n    import { readFile, serveFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\n\n**Replace the entire `glimpseHandler` function:**\n\n    export async function glimpseHandler(c: Context) {\n      const id = c.req.param(\"id\");\n\n      if (!id) {\n        return c.json({ error: \"Demo ID is required\" }, 400);\n      }\n\n      // Get the data (cached or live)\n      let notionData;\n\n      // First try to get cached data\n      try {\n        const cachedData = await blob.getJSON(blobKeyForDemos(id));\n        if (cachedData) {\n          console.log(`Serving cached data for glimpse ID: ${id}`);\n          notionData = cachedData;\n        }\n      } catch (error) {\n        console.log(`No cached data found for glimpse ID: ${id}, falling back to live data`);\n      }\n\n      // Cache miss - fall back to live Notion data\n      if (!notionData) {\n        const result = await getGlimpseData(id);\n\n        if (!result.success) {\n          return c.json({ error: result.error, details: result.details }, result.status);\n        }\n\n        notionData = result.data;\n      }\n\n      // Check if they want JSON (for API compatibility)\n      if (c.req.header(\"accept\")?.includes(\"application/json\") || c.req.query(\"format\") === \"json\") {\n        return c.json(notionData);\n      }\n\n      // Otherwise serve the React page\n      let html = await readFile(\"/frontend/glimpse.html\", import.meta.url);\n\n      // Get user email from auth context\n      const userEmail = c.get(\"userEmail\");\n\n      const dataScript = ``;\n\n      html = html.replace(\"\", `${dataScript}`);\n      return c.html(html);\n    }\n\n### 7\\. Add Frontend File Serving\n\nIn your main Hono app (likely `/main.tsx` or similar), add frontend file serving:\n\n**Add after existing route mounts:**\n\n    // Serve frontend files\n    app.get(\"/frontend/*\", c => serveFile(c.req.path, import.meta.url));\n\n## Key Features Delivered\n\n---\n\n✅ **Clean Architecture** \\- Proper separation between HTML shell, React bootstrap, and UI components  \n✅ **Professional Tailwind Layout** \\- Header, sidenav, main content, footer  \n✅ **Server-side Data Injection** \\- No extra API calls needed  \n✅ **User Context** \\- Shows authenticated user's email in header  \n✅ **Backward Compatibility** \\- JSON API still works with `?format=json`  \n✅ **Proper Authentication Integration** \\- Uses `/auth/logout` endpoint  \n✅ **Clean JSON Display** \\- Formatted in scrollable `` tag  \n✅ **Minimal Tailwind Classes** \\- Only essential styling  \n✅ **React 18.2.0** \\- Properly configured with pinned versions  \n✅ **Error Handling** \\- Includes Val Town's error capture script  \n✅ **Maintainable Code** \\- Single source of truth for UI logic\n\n## Testing\n\n---\n\n- Visit `/glimpse/:id` → Should show HTML page with layout\n- Visit `/glimpse/:id?format=json` → Should return JSON data\n- Verify user email appears in header\n- Verify logout link works\n- Verify React entry point loads correctly\n\nThis implementation provides a clean, maintainable React architecture while maintaining all existing functionality and adding a professional UI layer.\n",[],[181,392],"f1c33d52-7387-11f0-8a1d-0224a6c84d84","09-cache.md","01988473-765e-7709-bfba-a9447ab09b74",["D",1754568816144],"# Complete Instructions for Implementing Glimpse Endpoint Caching\n\n## Overview\n\nImplement a comprehensive caching system for `/glimpse/:id` endpoints to reduce Notion API response times from 1-6 seconds to milliseconds by using blob storage with automated cache population.\n\n## Prerequisites Understanding\n\n- The `/glimpse/:id` endpoint fetches data from Notion API including nested blocks via `getAllBlocksRecursively`\n- Response times are slow (1-6 seconds) due to Notion API calls and recursive block fetching\n- The system uses Hono for routing and has existing authentication middleware\n- Database queries use `GLANCE_DEMOS_DB_ID` environment variable to identify demo pages\n- Existing architecture has controllers in `/backend/controllers/`, services in `/backend/services/`, routes in `/backend/routes/`\n\n## Implementation Steps\n\n### 1\\. Create Blob Key Utilities (`/backend/utils/blob-keys.ts`)\n\n    function getValAndFileNameFromURL(url: string): string | null {\n      try {\n        const { pathname } = new URL(url);\n        const [preAt] = pathname.split(\"@\");\n        if (!preAt) return null;\n        const valName = preAt.split(\"/\").filter(Boolean).pop();\n        return valName ?? null;\n      } catch (e) {\n        console.error(\"Invalid URL passed to getValAndFileNameFromURL:\", url, e);\n        return null;\n      }\n    }\n\n    export function blobKey(type: string, id: string, url: string = import.meta.url): string {\n      if (!id || typeof id !== \"string\") {\n        throw new Error(\"Invalid ID passed to blobKey\");\n      }\n\n      const valName = getValAndFileNameFromURL(url);\n      if (!valName) {\n        throw new Error(\"Could not extract val name from URL\");\n      }\n\n      return [valName, type, id].join(\"--\");\n    }\n\n    export const blobKeyForDemos = (id: string) => blobKey(\"demo\", id);\n\n### 2\\. Add Database Query Function to Notion Service\n\nAdd to `/backend/services/notion.service.ts`:\n\n    export async function getDemoPages() {\n      try {\n        const databaseId = Deno.env.get(\"GLANCE_DEMOS_DB_ID\");\n        if (!databaseId) {\n          throw new Error(\"GLANCE_DEMOS_DB_ID environment variable is not set\");\n        }\n\n        const response = await notion.databases.query({\n          database_id: databaseId,\n        });\n\n        return {\n          success: true,\n          data: response.results,\n          timestamp: new Date().toISOString(),\n        };\n      } catch (error) {\n        return {\n          success: false,\n          error: error.message,\n          timestamp: new Date().toISOString(),\n        };\n      }\n    }\n\n### 3\\. Refactor Glimpse Controller\n\nReplace `/backend/controllers/glimpse.controller.ts` entirely:\n\n    import { Context } from \"npm:hono@3.12.12\";\n    import { getPageById, getMultiplePages } from \"../services/notion.service.ts\";\n    import { blob } from \"https://esm.town/v/std/blob\";\n    import { blobKeyForDemos } from \"../utils/blob-keys.ts\";\n\n    export async function getGlimpseData(id: string) {\n      if (!id) {\n        return { success: false, error: \"Demo ID is required\", status: 400 };\n      }\n\n      // Fetch the main page\n      const result = await getPageById(id);\n\n      if (!result.success) {\n        return { success: false, error: \"Failed to fetch demo data\", details: result.error, status: 500 };\n      }\n\n      // Filter out button properties from the main page\n      if (result.data?.properties) {\n        const filteredProperties = Object.fromEntries(\n          Object.entries(result.data.properties).filter(([key, value]) => value?.type !== \"button\")\n        );\n\n        result.data.properties = filteredProperties;\n      }\n\n      // Extract related page IDs from \"Glimpse content\" relation property\n      const glimpseContentProperty = result.data?.properties?.[\"Glimpse content\"];\n      let glimpseContent = [];\n\n      if (glimpseContentProperty?.type === \"relation\" && glimpseContentProperty.relation?.length > 0) {\n        const relatedPageIds = glimpseContentProperty.relation.map((rel: any) => rel.id);\n\n        // Fetch all related pages with their content\n        const relatedPagesResult = await getMultiplePages(relatedPageIds);\n\n        if (!relatedPagesResult.success) {\n          return {\n            success: false,\n            error: \"Failed to fetch related pages\",\n            details: relatedPagesResult.error,\n            status: 500\n          };\n        }\n\n        // Process and sort the related pages\n        glimpseContent = relatedPagesResult.data\n          .map((item: any) => {\n            // Filter out button properties from related pages too\n            const filteredProperties = item.page.properties ?\n              Object.fromEntries(\n                Object.entries(item.page.properties).filter(([key, value]) => (value as any)?.type !== \"button\")\n              ) : {};\n\n            return {\n              id: item.id,\n              properties: filteredProperties,\n              blocks: item.blocks.results\n            };\n          })\n          // Sort by Order property\n          .sort((a: any, b: any) => {\n            const orderA = a.properties?.Order?.number || 0;\n            const orderB = b.properties?.Order?.number || 0;\n            return orderA - orderB;\n          });\n      }\n\n      // Add the glimpse content to the response\n      result.data.glimpseContent = glimpseContent;\n\n      return { success: true, data: result };\n    }\n\n    export async function glimpseHandler(c: Context) {\n      const id = c.req.param(\"id\");\n\n      if (!id) {\n        return c.json({ error: \"Demo ID is required\" }, 400);\n      }\n\n      // First try to get cached data\n      try {\n        const cachedData = await blob.getJSON(blobKeyForDemos(id));\n        if (cachedData) {\n          console.log(`Serving cached data for glimpse ID: ${id}`);\n          return c.json(cachedData);\n        }\n      } catch (error) {\n        console.log(`No cached data found for glimpse ID: ${id}, falling back to live data`);\n      }\n\n      // Cache miss - fall back to live Notion data\n      const result = await getGlimpseData(id);\n\n      if (!result.success) {\n        return c.json({ error: result.error, details: result.details }, result.status);\n      }\n\n      return c.json(result.data);\n    }\n\n### 4\\. Create Caching Cron Job\n\nCreate `/backend/crons/cache_glimpse_data.ts`:\n\n    import { blob } from \"https://esm.town/v/std/blob\";\n    import { getDemoPages } from \"../services/notion.service.ts\";\n    import { getGlimpseData } from \"../controllers/glimpse.controller.ts\";\n    import { blobKeyForDemos } from \"../utils/blob-keys.ts\";\n\n    export default async function cacheGlimpseData() {\n      console.log(\"Starting glimpse data caching process...\");\n\n      try {\n        // Get all demo pages from the database\n        const demosResult = await getDemoPages();\n\n        if (!demosResult.success) {\n          console.error(\"Failed to fetch demo pages:\", demosResult.error);\n          return;\n        }\n\n        const demoPages = demosResult.data;\n        console.log(`Found ${demoPages.length} demo pages to cache`);\n\n        let successCount = 0;\n        let errorCount = 0;\n\n        // Process each demo page\n        for (const page of demoPages) {\n          const pageId = page.id;\n\n          try {\n            console.log(`Caching glimpse data for page ID: ${pageId}`);\n\n            // Get the glimpse data using the same logic as the endpoint\n            const glimpseResult = await getGlimpseData(pageId);\n\n            if (glimpseResult.success) {\n              // Store in blob storage\n              await blob.setJSON(blobKeyForDemos(pageId), glimpseResult.data);\n              console.log(`Successfully cached data for page ID: ${pageId}`);\n              successCount++;\n            } else {\n              console.error(`Failed to get glimpse data for page ID ${pageId}:`, glimpseResult.error);\n              errorCount++;\n            }\n          } catch (error) {\n            console.error(`Error processing page ID ${pageId}:`, error.message);\n            errorCount++;\n          }\n        }\n\n        console.log(`Caching process completed. Success: ${successCount}, Errors: ${errorCount}`);\n      } catch (error) {\n        console.error(\"Fatal error in caching process:\", error.message);\n      }\n    }\n\n### 5\\. Set Cron Trigger\n\nUse the `change_val_type` tool:\n\n    change_val_type(\"/backend/crons/cache_glimpse_data.ts\", \"cron\")\n\n### 6\\. Configure Cron Schedule\n\n**CRITICAL**: After implementation, go to Val Town web UI and set the cron schedule to run every minute (`* * * * *`).\n\n## Validation Steps\n\n### Test 1: Verify Database Query\n\nCreate temporary test file:\n\n    import { getDemoPages } from \"./backend/services/notion.service.ts\";\n\n    export default async function testDatabaseQuery(req: Request) {\n      const result = await getDemoPages();\n      return new Response(JSON.stringify({\n        success: result.success,\n        count: result.success ? result.data.length : 0,\n        sampleIds: result.success ? result.data.slice(0, 3).map(p => p.id) : [],\n        error: result.success ? null : result.error\n      }), {\n        headers: { \"Content-Type\": \"application/json\" }\n      });\n    }\n\nExpected: `success: true`, `count: > 0`, array of page IDs\n\n### Test 2: Verify Caching Logic\n\nCreate temporary test file:\n\n    import { getGlimpseData } from \"./backend/controllers/glimpse.controller.ts\";\n    import { blob } from \"https://esm.town/v/std/blob\";\n    import { blobKeyForDemos } from \"./backend/utils/blob-keys.ts\";\n\n    export default async function testCaching(req: Request) {\n      const testPageId = \"FIRST_PAGE_ID_FROM_TEST_1\"; // Replace with actual ID\n\n      const glimpseResult = await getGlimpseData(testPageId);\n      if (!glimpseResult.success) {\n        return new Response(JSON.stringify({ error: glimpseResult.error }), { status: 500 });\n      }\n\n      const blobKey = blobKeyForDemos(testPageId);\n      await blob.setJSON(blobKey, glimpseResult.data);\n\n      const retrieved = await blob.getJSON(blobKey);\n\n      return new Response(JSON.stringify({\n        success: true,\n        blobKey,\n        dataStored: !!retrieved,\n        hasNestedBlocks: !!retrieved?.data?.glimpseContent?.some(item =>\n          item.blocks?.some(block => block.children && block.children.length > 0)\n        )\n      }));\n    }\n\nExpected: `success: true`, `dataStored: true`, nested blocks preserved\n\n### Test 3: Verify Cache-First Endpoint\n\nCreate temporary test file:\n\n    import { glimpseHandler } from \"./backend/controllers/glimpse.controller.ts\";\n\n    export default async function testCachedEndpoint(req: Request) {\n      const testPageId = \"CACHED_PAGE_ID_FROM_TEST_2\";\n\n      const mockContext = {\n        req: { param: (name: string) => name === \"id\" ? testPageId : undefined },\n        json: (data: any, status?: number) => new Response(JSON.stringify(data), {\n          status: status || 200,\n          headers: { \"Content-Type\": \"application/json\" }\n        })\n      };\n\n      const response = await glimpseHandler(mockContext as any);\n      const responseData = JSON.parse(await response.text());\n\n      return new Response(JSON.stringify({\n        success: true,\n        status: response.status,\n        servedFromCache: true, // Check logs for \"Serving cached data\" message\n        hasData: !!responseData?.data\n      }));\n    }\n\nExpected: `success: true`, `status: 200`, logs show \"Serving cached data\"\n\n## Performance Expectations\n\n### Before Implementation:\n\n- Response times: 1-6 seconds\n- Every request hits Notion API\n- Recursive block fetching on every request\n\n### After Implementation:\n\n- **Cache Hit**: 50-200ms response time\n- **Cache Miss**: 1-6 seconds (fallback to live data)\n- **Cache Population**: Automatic every minute via cron\n\n## Troubleshooting Guide\n\n### Issue: Cron not running\n\n- **Check**: Val Town web UI cron schedule is set to `* * * * *`\n- **Verify**: Check cron execution logs with `requests` tool\n\n### Issue: Cache not being used\n\n- **Check**: Look for \"Serving cached data\" or \"No cached data found\" in endpoint logs\n- **Verify**: Manually test blob key exists: `blob.getJSON(blobKeyForDemos(pageId))`\n\n### Issue: Nested blocks missing\n\n- **Check**: Compare live vs cached data structure\n- **Verify**: `getAllBlocksRecursively` function is working correctly\n- **Expected**: Blocks with `children` property containing nested arrays\n\n### Issue: Slow response times persist\n\n- **Check**: Cron has run at least once (check cron logs)\n- **Verify**: Cache keys exist in blob storage\n- **Debug**: Look for cache miss logs in endpoint requests\n\n## Architecture Principles Maintained\n\n1.  **Controllers**: Business logic stays in `/backend/controllers/`\n2.  **Services**: External API calls in `/backend/services/`\n3.  **Utilities**: Backend-only helpers in `/backend/utils/`\n4.  **Crons**: Scheduled tasks in `/backend/crons/`\n5.  **No Code Duplication**: Both endpoint and cron use same `getGlimpseData()` function\n6.  **Error Resilience**: Cron continues on individual failures, endpoint falls back to live data\n7.  **Data Integrity**: Complete preservation of nested block structure and all metadata\n\n## Success Criteria\n\n- ✅ All demo pages automatically cached every minute\n- ✅ Cache-first endpoint with live data fallback\n- ✅ Response times under 200ms for cached data\n- ✅ Complete preservation of nested block structure\n- ✅ Error logging and graceful degradation\n- ✅ No breaking changes to existing API contract\n",[],[181,399],"f1c330b4-7387-11f0-8a1d-0224a6c84d84","08-related.md","01988473-765e-7709-bfba-a5f329002663",["D",1754568816144],"# Complete Implementation Instructions: Enhanced /glimpse/:id Endpoint with Related Content and Nested Blocks\n\n## Overview\n\nEnhance the existing `/glimpse/:id` endpoint to fetch and attach related pages from the \"Glimpse content\" relation property, sorted by \"Order\" property, including full page blocks/content with all nested blocks recursively fetched to support callouts, code blocks, lists, tables, columns, and other rich content structures.\n\n## Understanding the Existing Patterns\n\n### Service Response Pattern\n\nServices return consistent structure:\n\n    // Success: {success: true, data: response, timestamp: string}\n    // Failure: {success: false, error: string, timestamp: string}\n\n### Controller Pattern\n\nControllers check `result.success` and handle accordingly:\n\n- If `!result.success`: Return 500 error with details\n- If `result.success`: Return full service response (includes success/data/timestamp)\n\n### Error Handling Philosophy\n\n\"All or nothing\" - operations either succeed completely or fail completely. No partial success states.\n\n## Implementation Steps\n\n### Step 1: Add Required Service Functions\n\nAdd to `/backend/services/notion.service.ts` before the `updatePageUrl` function:\n\n    async function getAllBlocksRecursively(blockId: string): Promise {\n      const response = await notion.blocks.children.list({\n        block_id: blockId,\n        page_size: 100 // Get more blocks per request\n      });\n\n      const blocks = response.results;\n\n      // For each block, check if it has children and fetch them recursively\n      for (const block of blocks) {\n        if (block.has_children) {\n          try {\n            block.children = await getAllBlocksRecursively(block.id);\n          } catch (error) {\n            // If fetching children fails, log but don't fail the entire operation\n            console.warn(`Failed to fetch children for block ${block.id}:`, error.message);\n            block.children = [];\n          }\n        }\n      }\n\n      return blocks;\n    }\n\n    export async function getPageBlocks(pageId: string) {\n      try {\n        const blocks = await getAllBlocksRecursively(pageId);\n        return {\n          success: true,\n          data: { results: blocks },\n          timestamp: new Date().toISOString(),\n        };\n      } catch (error) {\n        return {\n          success: false,\n          error: error.message,\n          timestamp: new Date().toISOString(),\n        };\n      }\n    }\n\n    export async function getMultiplePages(pageIds: string[]) {\n      try {\n        // Fetch all pages concurrently\n        const pagePromises = pageIds.map(async (pageId) => {\n          const [pageResult, blocksResult] = await Promise.all([\n            notion.pages.retrieve({ page_id: pageId }),\n            getAllBlocksRecursively(pageId)\n          ]);\n\n          return {\n            id: pageId,\n            page: pageResult,\n            blocks: { results: blocksResult } // Maintain same structure as before\n          };\n        });\n\n        const results = await Promise.all(pagePromises);\n\n        return {\n          success: true,\n          data: results,\n          timestamp: new Date().toISOString(),\n        };\n      } catch (error) {\n        return {\n          success: false,\n          error: error.message,\n          timestamp: new Date().toISOString(),\n        };\n      }\n    }\n\n### Step 2: Update Controller Import\n\nIn `/backend/controllers/glimpse.controller.ts`, update the import:\n\n    import { getPageById, getMultiplePages } from \"../services/notion.service.ts\";\n\n### Step 3: Replace Controller Function\n\nReplace the entire `glimpseHandler` function in `/backend/controllers/glimpse.controller.ts`:\n\n    export async function glimpseHandler(c: Context) {\n      const id = c.req.param(\"id\");\n\n      if (!id) {\n        return c.json({ error: \"Demo ID is required\" }, 400);\n      }\n\n      // Fetch the main page\n      const result = await getPageById(id);\n\n      if (!result.success) {\n        return c.json({ error: \"Failed to fetch demo data\", details: result.error }, 500);\n      }\n\n      // Filter out button properties from the main page\n      if (result.data?.properties) {\n        const filteredProperties = Object.fromEntries(\n          Object.entries(result.data.properties).filter(([key, value]) => value?.type !== \"button\")\n        );\n\n        result.data.properties = filteredProperties;\n      }\n\n      // Extract related page IDs from \"Glimpse content\" relation property\n      const glimpseContentProperty = result.data?.properties?.[\"Glimpse content\"];\n      let glimpseContent = [];\n\n      if (glimpseContentProperty?.type === \"relation\" && glimpseContentProperty.relation?.length > 0) {\n        const relatedPageIds = glimpseContentProperty.relation.map((rel: any) => rel.id);\n\n        // Fetch all related pages with their content\n        const relatedPagesResult = await getMultiplePages(relatedPageIds);\n\n        if (!relatedPagesResult.success) {\n          return c.json({\n            error: \"Failed to fetch related pages\",\n            details: relatedPagesResult.error\n          }, 500);\n        }\n\n        // Process and sort the related pages\n        glimpseContent = relatedPagesResult.data\n          .map((item: any) => {\n            // Filter out button properties from related pages too\n            const filteredProperties = item.page.properties ?\n              Object.fromEntries(\n                Object.entries(item.page.properties).filter(([key, value]) => (value as any)?.type !== \"button\")\n              ) : {};\n\n            return {\n              id: item.id,\n              properties: filteredProperties,\n              blocks: item.blocks.results\n            };\n          })\n          // Sort by Order property\n          .sort((a: any, b: any) => {\n            const orderA = a.properties?.Order?.number || 0;\n            const orderB = b.properties?.Order?.number || 0;\n            return orderA - orderB;\n          });\n      }\n\n      // Add the glimpse content to the response\n      result.data.glimpseContent = glimpseContent;\n\n      return c.json(result);\n    }\n\n### Step 4: Update Documentation\n\n#### Update `/backend/routes/glimpse/README.md`:\n\n    # Glimpse Routes\n\n    This directory contains routes for the glimpse functionality.\n\n    ## Routes\n\n    ### GET /:id\n\n    - **Purpose**: Returns Notion page data as JSON with related content (filtered for data consumption)\n    - **Authentication**: Required (Google OAuth)\n    - **Parameters**: `id` - Notion page ID\n    - **Response**: Service response object with Notion page data and related content\n    - **Filtering**: Removes UI-specific properties (type: \"button\") for cleaner data consumption\n\n    #### Enhanced Functionality\n\n    The endpoint now fetches and includes related pages from the \"Glimpse content\" relation property:\n\n    1. **Main Page**: Returns the requested page with filtered properties\n    2. **Related Content**: Fetches all pages referenced in the \"Glimpse content\" relation\n    3. **Content Blocks**: Includes full page blocks/content for each related page with nested blocks recursively fetched\n    4. **Nested Content**: Supports callouts, code blocks, lists, tables, columns, and other nested block structures\n    5. **Sorting**: Related pages are sorted by their \"Order\" property (ascending)\n    6. **Error Handling**: Returns failure if main page OR any related page fails to fetch\n\n    #### Response Structure\n\n    ```json\n    {\n      \"success\": true,\n      \"data\": {\n        \"id\": \"main-page-id\",\n        \"properties\": { ... }, // Main page properties (buttons filtered out)\n        \"glimpseContent\": [\n          {\n            \"id\": \"related-page-1\",\n            \"properties\": { \"Order\": { \"number\": 1 }, ... }, // Related page properties (buttons filtered out)\n            \"blocks\": [ ... ] // Full page content blocks with nested structures (callouts, lists, tables, etc.)\n          },\n          {\n            \"id\": \"related-page-2\",\n            \"properties\": { \"Order\": { \"number\": 2 }, ... },\n            \"blocks\": [ ... ] // Full page content blocks with nested structures\n          }\n        ]\n      },\n      \"timestamp\": \"2025-07-27T12:00:00.000Z\"\n    }\n\n#### Nested Block Structure\n\nBlocks with children will have a `children` property containing their nested blocks:\n\n    {\n      \"type\": \"bulleted_list_item\",\n      \"bulleted_list_item\": { ... },\n      \"has_children\": true,\n      \"children\": [\n        {\n          \"type\": \"bulleted_list_item\",\n          \"bulleted_list_item\": { ... },\n          \"has_children\": false\n        }\n      ]\n    }\n\n#### Error Cases\n\n- **Main page not found**: Returns `{success: false, error: \"...\", timestamp: \"...\"}`\n- **Related page fetch fails**: Returns `{success: false, error: \"Failed to fetch related pages\", timestamp: \"...\"}`\n- **Individual block children fail**: Logs warning, continues with empty children array\n- **No related content**: Returns successful response with empty `glimpseContent` array\n\nThis is the same functionality as `/views/glimpse/:id` but mounted at `/glimpse/:id` for convenience.\n\n    #### Update main `/README.md` Views section:\n\n    Replace:\n    ```markdown\n    ### Views\n    - `GET /views/glimpse/:id` - Get Notion page data as JSON (filtered for data consumption)\n\nWith:\n\n    ### Views\n    - `GET /views/glimpse/:id` - Get Notion page data with related content as JSON (filtered for data consumption)\n    - `GET /glimpse/:id` - Same as above, alternative endpoint\n\n#### Update `/backend/services/README.md` Examples section:\n\nReplace:\n\n    ## Examples\n\n    - `getDatabaseById(id)` - retrieve specific database from Notion\n    - `searchNotionDatabases()` - search for all databases\n    - `updatePageUrl(pageId, url)` - update a Notion page's URL property\n\nWith:\n\n    ## Examples\n\n    - `getDatabaseById(id)` - retrieve specific database from Notion\n    - `getPageById(id)` - retrieve specific page from Notion\n    - `getPageBlocks(id)` - retrieve page content blocks from Notion (with nested blocks recursively)\n    - `getMultiplePages(ids)` - batch retrieve multiple pages with their blocks from Notion (with nested blocks recursively)\n    - `searchNotionDatabases()` - search for all databases\n    - `updatePageUrl(pageId, url)` - update a Notion page's URL property\n\n## Key Implementation Details\n\n### Property Names\n\n- **Relation property**: \"Glimpse content\" (exact match required)\n- **Sort property**: \"Order\" (exact match required)\n\n### Nested Block Handling\n\n- **Recursive fetching**: Uses `getAllBlocksRecursively()` to fetch all nested blocks\n- **Error resilience**: Individual block failures don't break the entire operation\n- **Performance optimization**: Uses `page_size: 100` for fewer API calls\n- **Complete structure**: Supports all Notion block types with children (callouts, lists, tables, columns, toggles, etc.)\n\n### Error Handling Strategy\n\n- **All or nothing**: If any related page fails, entire request fails\n- **Individual block resilience**: If fetching children of a specific block fails, logs warning but continues\n- **Consistent responses**: Always use service response pattern\n- **Detailed errors**: Include specific error details in failure responses\n\n### Performance Considerations\n\n- **Concurrent fetching**: Use `Promise.all()` for parallel page fetching\n- **Recursive API calls**: More requests due to nested block fetching\n- **Batch operations**: Single service call handles multiple pages\n- **Reasonable limits**: Designed for up to 10 related pages\n- **Graceful degradation**: Individual block failures don't break entire response\n\n### Data Processing\n\n- **Button filtering**: Remove `type: \"button\"` properties from all pages\n- **Sorting**: Sort by `Order.number` property (ascending, default 0 for missing)\n- **Block extraction**: Use `blocks.results` from recursive fetch\n- **Nested structure**: Blocks with children have `children` array property\n\n### Response Structure\n\n- **Backward compatible**: Existing clients continue to work\n- **Additive**: New `glimpseContent` array added to existing response\n- **Consistent**: Maintains service response pattern with success/data/timestamp\n- **Rich content**: Full nested block structures for complete content representation\n\n### Supported Nested Block Types\n\n- **Lists**: Bulleted, numbered, to-do items with nested items\n- **Callouts**: With nested content blocks\n- **Code blocks**: With syntax highlighting\n- **Tables**: With cell content\n- **Columns**: With nested blocks in each column\n- **Toggles**: With hidden/expandable content\n- **Quotes**: With nested formatting\n- **Synced blocks**: With synchronized content\n- **Any other block type**: That supports children\n\n## Testing Strategy\n\n1.  **Test with no related content**: Should return empty `glimpseContent` array\n2.  **Test with related content**: Should return sorted pages with complete nested blocks\n3.  **Test nested structures**: Verify callouts, lists, tables render with full hierarchy\n4.  **Test error cases**: Invalid page IDs should return failure responses\n5.  **Test individual block failures**: Should continue with warnings, not fail entirely\n6.  **Test authentication**: Unauthenticated requests should show login page\n7.  **Test performance**: Monitor response times with deeply nested content\n\n## Block Structure Examples\n\n### Nested List Example\n\n    {\n      \"type\": \"bulleted_list_item\",\n      \"bulleted_list_item\": {\n        \"rich_text\": [{\"plain_text\": \"Parent item\"}]\n      },\n      \"has_children\": true,\n      \"children\": [\n        {\n          \"type\": \"bulleted_list_item\",\n          \"bulleted_list_item\": {\n            \"rich_text\": [{\"plain_text\": \"Child item\"}]\n          },\n          \"has_children\": false\n        }\n      ]\n    }\n\n### Callout with Nested Content Example\n\n    {\n      \"type\": \"callout\",\n      \"callout\": {\n        \"rich_text\": [{\"plain_text\": \"Important note\"}],\n        \"icon\": {\"emoji\": \"💡\"}\n      },\n      \"has_children\": true,\n      \"children\": [\n        {\n          \"type\": \"paragraph\",\n          \"paragraph\": {\n            \"rich_text\": [{\"plain_text\": \"Additional details inside callout\"}]\n          }\n        }\n      ]\n    }\n\nThis implementation provides complete nested block structures that will properly represent all rich content types including callouts, code blocks, lists, tables, columns, and any other nested Notion block structures.\n",[],[181,406],"f1c32984-7387-11f0-8a1d-0224a6c84d84","07-save.md","01988473-765e-7709-bfba-a179c7d14619",["D",1754568816144],"# Instructions for Implementing a New /tasks/url Webhook Endpoint\n\n## Context\n\nThis guide is for implementing webhook endpoints in the Glance Demo Platform Val that follow the established architectural patterns.\n\n## Pre-Implementation Analysis\n\n1. ### Understand the Architecture Patterns\n   Before implementing, identify which pattern to use:\n\n- Data API Pattern (/api/_, /views/_): Controllers return data objects, routes handle HTTP\n- Webhook Handler Pattern (/tasks/\\*): Controllers handle HTTP requests/responses directly\n\nFor /tasks/\\* routes, use the Webhook Handler Pattern.\n\n2. ### Examine Existing Patterns\n   Study these files to understand the established patterns:\n\n- `/backend/controllers/glimpse.controller.ts` - Example of webhook handler pattern\n- `/backend/routes/tasks/_tasks.routes.ts` - Existing webhook route structure\n- `/backend/services/notion.service.ts` - Service layer patterns\n- `/backend/routes/webhookAuthCheck.ts` - Authentication middleware\n\n3. ### Identify Required Components\n   For a new /tasks/url endpoint, you'll need:\n\n- Controller function (handles HTTP directly)\n- Service function (if new Notion API calls needed)\n- Route definition\n- Documentation updates\n\n## Implementation Steps\n\n### Step 1: Extend the Service Layer (if needed)\n\nIf new external API calls are required:\n\n1. **Location:** /backend/services/notion.service.ts\n1. **Pattern:** Add pure API functions that return {success, data/error, timestamp} format\n1. **Example:** updatePageUrl(pageId, url) function\n1. **Responsibilities:** Only handle external API calls, no business logic\n\n### Step 2: Create the Controller\n\n1. **Location:** `/backend/controllers/tasks.controller.ts`\n1. **Pattern:** Webhook Handler Pattern - function takes Context, returns HTTP responses\n1. **Function signature:** export async function handleNotionWebhook(c: Context)\n1. **Responsibilities:**\n\n- Parse HTTP request (c.req.json(), c.req.header())\n- Extract and validate data from webhook payload\n- Implement business logic\n- Call service functions\n- Log success/failure with detailed context\n- Return HTTP responses with appropriate status codes (c.json(data, statusCode))\n\n### Step 3: Add the Route\n\n- **Location:** `/backend/routes/tasks/_tasks.routes.ts`\n- **Pattern:** Direct controller call\n- **Implementation:** `app.post(\"/url\", handleNotionWebhook)`\n- **Update catch-all handler:** Add new endpoint to `availableEndpoints` array\n\n### Step 4: Update Documentation\n\n**Main README** `(/README.md)`:\n\n- Add endpoint to \"Webhooks (Notion Integration)\" section\n- Follow format: `POST /tasks/url` - Description (requires `X-API-KEY` header)\n\n**Route README** `(/backend/routes/tasks/README.md)`:\n\n- Add comprehensive endpoint documentation\n- Include request/response examples\n- Document error cases\n- Add testing instructions\n\n**Controller README** `(/backend/controllers/README.md)`:\n\n- Add controller function to examples\n- Note that it follows webhook handler pattern\n\n**Service README** `(/backend/services/README.md)`:\n\n- Add any new service functions to examples\n\n## Key Implementation Details\n\n### Authentication\n\n- All `/tasks/*` routes automatically use webhook authentication\n- Requires X-API-KEY header with NOTION_WEBHOOK_SECRET value\n- No additional auth setup needed in route\n\n### Webhook Payload Handling\n\nSupport multiple payload structures:\n\n```\n// Try multiple common webhook payload structures\nif (body.data?.id) {\n  pageId = body.data.id;\n} else if (body.id) {\n  pageId = body.id;\n} else if (body.page_id) {\n  pageId = body.page_id;\n}\n```\n\n### URL Construction Pattern\n\nUse this pattern for glimpse URLs:\n\n```\nconst host = c.req.header(\"host\");\nconst glimpseUrl = `https://${host}/glimpse/${pageId}`;\n```\n\n### Error Handling\n\nReturn structured errors with appropriate HTTP status codes:\n\n```\n// 400 for client errors\nreturn c.json({ success: false, error: \"Description\" }, 400);\n\n// 500 for server errors\nreturn c.json({ success: false, error: \"Description\", details: result.error }, 500);\n```\n\n### Logging Pattern\n\nInclude comprehensive logging:\n\n```\nconsole.log(\"Processing URL update webhook request\");\nconsole.log(\"Notion webhook received:\", body);\nconsole.log(`Constructed glimpse URL: ${glimpseUrl} for page ID: ${pageId}`);\nconsole.log(\"Successfully updated Notion page with glimpse URL:\", { pageId, url });\nconsole.error(\"Failed to update Notion page:\", result.error);\n```\n\n### Success Response Format\n\nReturn detailed success responses:\n\n```\nreturn c.json({\n  success: true,\n  message: \"Page URL updated successfully\",\n  pageId: pageId,\n  url: glimpseUrl,\n  timestamp: new Date().toISOString()\n});\n```\n\n## Testing Strategy\n\n### Authentication Testing\n\n1. Test without header (expect 401)\n1. Test with wrong key (expect 403)\n1. Test with correct key (expect 200 or business logic response)\n\n### Business Logic Testing\n\n1. Test with valid payload structure\n1. Test with missing page ID (expect 400)\n1. Test with missing host header (expect 400)\n1. Test with Notion API failures (expect 500)\n\n### Add Test Endpoint (optional)\n\nCreate a test endpoint that simulates the logic without calling external APIs:\n\n```\napp.post(\"/test-url\", async (c) => {\n  // Same logic but return test response instead of calling Notion API\n});\n```\n\n## Common Pitfalls to Avoid\n\n1. Don't mix patterns: /tasks/\\_ routes should use webhook handler pattern, not data API pattern\n1. Don't forget authentication: All /tasks/\\_ routes are automatically protected\n1. Don't skip logging: Webhook endpoints need comprehensive logging for debugging\n1. Don't forget documentation: Update all relevant README files\n1. Don't hardcode hosts: Always extract host from request headers\n1. Don't forget error cases: Handle missing data, API failures, etc.\n1. Don't skip the catch-all update: Add new endpoints to available endpoints list\n\n## Validation Checklist\n\nBefore considering implementation complete:\n\n- Controller follows webhook handler pattern (takes Context, returns HTTP responses)\n- Route uses direct controller call pattern\n- Service functions return consistent {success, data/error, timestamp} format\n- Comprehensive logging for success and failure cases\n- Proper HTTP status codes (400 for client errors, 500 for server errors)\n- Support for multiple webhook payload structures\n- Host extraction from request headers\n- Updated all relevant documentation\n- Added endpoint to catch-all handler's available endpoints list\n- Tested authentication (should fail with test keys)\n- Error handling for all edge cases\n\n## Final Notes\n\n- The webhook authentication middleware handles all security automatically\n- Focus on business logic and proper HTTP handling in the controller\n- Keep service functions pure (no business logic, just API calls)\n- Document the architectural decision when mixing patterns\n- Test thoroughly but remember authentication will block test requests without proper keys\n\nThis pattern ensures consistency with the established architecture while providing clear separation of concerns and comprehensive error handling.\n",[],[181,413],"f1c324fc-7387-11f0-8a1d-0224a6c84d84","06-link.md","01988473-765e-7709-bfba-9f07380a111a",["D",1754568816144],"# Instructions for Getting Sample URLs with Real Notion Page IDs\n\n## Goal\n\nProvide working sample URLs for glimpse routes using actual page IDs from the GLANCE_DEMOS_DB_ID database without trial and error.\n\n## Step-by-Step Process\n\n### 1\\. Create Temporary Unauthenticated Endpoint\n\n    // In /backend/routes/api/_api.routes.ts, add:\n    app.get(\"/demo-pages\", async (c) => {\n      const databaseId = Deno.env.get(\"GLANCE_DEMOS_DB_ID\");\n      if (!databaseId) {\n        return c.json({ error: \"GLANCE_DEMOS_DB_ID not configured\" }, 500);\n      }\n\n      const result = await getDatabasePages(databaseId);\n      return c.json(result);\n    });\n\n### 2\\. Add Database Query Function\n\n    // In /backend/services/notion.service.ts, add:\n    export async function getDatabasePages(databaseId: string) {\n      try {\n        const response = await notion.databases.query({\n          database_id: databaseId,\n          page_size: 10, // Limit to first 10 pages\n        });\n        return {\n          success: true,\n          data: response,\n          timestamp: new Date().toISOString(),\n        };\n      } catch (error) {\n        return {\n          success: false,\n          error: error.message,\n          timestamp: new Date().toISOString(),\n        };\n      }\n    }\n\n### 3\\. Temporarily Bypass Authentication for Demo Endpoint\n\n    // In main.tsx, change:\n    // FROM: app.use(\"/api/*\", authCheck);\n    // TO:\n    app.use(\"/api/health\", authCheck);\n    // This allows /api/demo-pages to be accessed without auth\n\n### 4\\. Fetch Real Page IDs\n\n    # Make request to get actual page IDs\n    fetch(\"/api/demo-pages\")\n\n### 5\\. Extract Page ID from Response\n\n    // From the JSON response, extract the first page ID:\n    const pageId = response.data.results[0].id;\n    // Example: \"20789f51-c349-81e0-8b17-d2d89039c636\"\n\n### 6\\. Restore Authentication\n\n    // In main.tsx, restore:\n    app.use(\"/api/*\", authCheck);\n\n### 7\\. Provide Working URLs\n\n    Original route: /views/glimpse/{pageId}\n    New route: /glimpse/{pageId}\n\n## Complete Implementation Script\n\n    // 1. Add to notion.service.ts\n    export async function getDatabasePages(databaseId: string) {\n      try {\n        const response = await notion.databases.query({\n          database_id: databaseId,\n          page_size: 10,\n        });\n        return { success: true, data: response, timestamp: new Date().toISOString() };\n      } catch (error) {\n        return { success: false, error: error.message, timestamp: new Date().toISOString() };\n      }\n    }\n\n    // 2. Add to _api.routes.ts\n    app.get(\"/demo-pages\", async (c) => {\n      const databaseId = Deno.env.get(\"GLANCE_DEMOS_DB_ID\");\n      if (!databaseId) return c.json({ error: \"GLANCE_DEMOS_DB_ID not configured\" }, 500);\n      const result = await getDatabasePages(databaseId);\n      return c.json(result);\n    });\n\n    // 3. Temporarily modify main.tsx\n    app.use(\"/api/health\", authCheck); // Instead of \"/api/*\"\n\n    // 4. Fetch data\n    const response = await fetch(\"/api/demo-pages\");\n    const data = await response.json();\n    const pageId = data.data.results[0].id;\n\n    // 5. Restore main.tsx\n    app.use(\"/api/*\", authCheck);\n\n    // 6. Provide URLs\n    const originalUrl = `/views/glimpse/${pageId}`;\n    const newUrl = `/glimpse/${pageId}`;\n\n## Key Points\n\n- Always use GLANCE_DEMOS_DB_ID environment variable for database ID\n- Temporarily bypass auth only for the demo endpoint\n- Extract the first available page ID from results array\n- Restore full authentication after getting the ID\n- Both routes should work identically with the real page ID\n\nThis process eliminates guesswork and provides actual working URLs with real Notion page IDs from the configured database.\n",[],[181,420],"f1c31f70-7387-11f0-8a1d-0224a6c84d84","05-glimpse.md","01988473-765e-7709-bfba-9ab2b43c4ed4",["D",1754568816144],"# Instructions for Adding Duplicate Routes (Multiple Paths to Same Handler)\n\nThis guide covers how to properly create multiple URL paths that serve the same functionality while maintaining clean architecture.\n\n## Use Case\n\nWhen you need both `/views/feature/:id` and `/feature/:id` to work identically, serving the same handler with the same authentication and behavior.\n\n## ❌ Common Mistakes to Avoid\n\n### 1. Direct Controller Import in Main Router\n\n```ts\n// DON'T DO THIS - violates architectural separation\nimport { featureHandler } from \"./backend/controllers/feature.controller.ts\";\napp.get(\"/feature/:id\", featureHandler);\n```\n\n### 2. Mounting Routes at Wrong Path\n\n```ts\n// DON'T DO THIS - creates /feature/feature/:id instead of /feature/:id\napp.route(\"/feature\", viewRoutes); // where viewRoutes has app.get(\"/feature/:id\", ...)\n```\n\n### 3. Forgetting Authentication Middleware\n\n```ts\n// DON'T DO THIS - inconsistent auth between routes\napp.use(\"/views/*\", authCheck);\n// Missing: app.use(\"/feature/*\", authCheck);\napp.route(\"/feature\", featureRoutes);\n```\n\n## ✅ Correct Implementation Steps\n\n### Step 1: Analyze Existing Route Structure\n\nFirst, understand the current route setup:\n\n```bash\n# Check existing routes file\ncat /backend/routes/views/_views.routes.ts\n\n# Check main router setup\ncat /main.tsx\n```\n\nLook for:\n\n- How the route is currently defined (e.g., `app.get(\"/feature/:id\", handler)`)\n- What authentication middleware is applied\n- How routes are mounted in main.tsx\n\n### Step 2: Create Dedicated Route Module\n\nCreate a new route module that mirrors the existing functionality:\n\n```ts\n// Create /backend/routes/feature/_feature.routes.ts\nimport { Hono } from \"npm:hono@3.12.12\";\nimport { featureHandler } from \"../../controllers/feature.controller.ts\";\n\nconst app = new Hono();\n\n// Use /:id (not /feature/:id) since it will be mounted at /feature\napp.get(\"/:id\", featureHandler);\n\nexport default app;\n```\n\n**Key Points:**\n\n- Route path is `/:id` not `/feature/:id` (mounting handles the prefix)\n- Import the same controller used by the original route\n- Follow the same naming convention (`_feature.routes.ts`)\n\n### Step 3: Add Route Documentation\n\n```ts\n// Create /backend/routes/feature/README.md\n# Feature Routes\n\nThis directory contains routes for the feature functionality.\n\n## Routes\n\n### GET /:id\n\n- **Purpose**: [Copy purpose from original route docs]\n- **Authentication**: Required (Google OAuth)\n- **Parameters**: `id` - [Parameter description]\n- **Response**: [Response description]\n\nThis is the same functionality as `/views/feature/:id` but mounted at `/feature/:id` for convenience.\n```\n\n### Step 4: Update Main Router\n\nAdd the new route module to main.tsx:\n\n```ts\n// Add import\nimport featureRoutes from \"./backend/routes/feature/_feature.routes.ts\";\n\n// Add authentication middleware (same as original)\napp.use(\"/feature/*\", authCheck);\n\n// Mount routes\napp.route(\"/feature\", featureRoutes);\n```\n\n**Critical Order:**\n\n1. Import route modules (not controllers)\n2. Apply authentication middleware\n3. Mount routes after middleware\n\n### Step 5: Verify Route Mounting Logic\n\nEnsure you understand the path composition:\n\n```\nMain router mount: app.route(\"/feature\", featureRoutes)\nRoute definition: app.get(\"/:id\", handler)\nFinal URL: /feature/:id ✅\n\nNOT:\nRoute definition: app.get(\"/feature/:id\", handler)\nFinal URL: /feature/feature/:id ❌\n```\n\n### Step 6: Test Both Routes\n\nTest that both routes work identically:\n\n```bash\n# Test original route\ncurl /views/feature/test-id\n\n# Test new route\ncurl /feature/test-id\n\n# Both should return identical responses (login page if not authenticated)\n```\n\n## Complete Example Implementation\n\n### File Structure\n\n```\nbackend/routes/\n├── views/_views.routes.ts          # Original route\n├── feature/\n│   ├── _feature.routes.ts          # New duplicate route\n│   └── README.md                   # Documentation\n```\n\n### main.tsx\n\n```ts\nimport { Hono } from \"npm:hono@3.12.12\";\nimport { lastlogin } from \"https://esm.town/v/stevekrouse/lastlogin_safe\";\n\n// Import route modules (NOT controllers)\nimport viewRoutes from \"./backend/routes/views/_views.routes.ts\";\nimport featureRoutes from \"./backend/routes/feature/_feature.routes.ts\";\nimport authCheck from \"./backend/routes/authCheck.ts\";\n\nconst app = new Hono();\n\n// Apply authentication to both routes\napp.use(\"/views/*\", authCheck);\napp.use(\"/feature/*\", authCheck);\n\n// Mount routes\napp.route(\"/views\", viewRoutes);\napp.route(\"/feature\", featureRoutes);\n\nexport default lastlogin(app.fetch);\n```\n\n### \\_feature.routes.ts\n\n```ts\nimport { Hono } from \"npm:hono@3.12.12\";\nimport { featureHandler } from \"../../controllers/feature.controller.ts\";\n\nconst app = new Hono();\n\napp.get(\"/:id\", featureHandler);\n\nexport default app;\n```\n\n## Architecture Principles\n\n### ✅ Maintain Clean Separation\n\n- Main router → Route modules → Controllers → Services\n- Never import controllers directly in main router\n- Each route module handles one logical grouping\n\n### ✅ Consistent Authentication\n\n- Apply same middleware to both route paths\n- Ensure identical security behavior\n- Document authentication requirements\n\n### ✅ DRY Principle\n\n- Reuse existing controllers and services\n- Don't duplicate business logic\n- Share the same handler implementation\n\n## Testing Checklist\n\n- [ ] Both routes return identical responses\n- [ ] Authentication works the same on both routes\n- [ ] No 404 errors on either route\n- [ ] Route parameters are correctly extracted\n- [ ] Error handling is consistent\n- [ ] Documentation is updated\n\n## Troubleshooting\n\n### Route Returns 404\n\n- Check route mounting path vs route definition path\n- Verify authentication middleware is applied before route mounting\n- Ensure route module exports default app\n\n### Different Behavior Between Routes\n\n- Verify both routes use the same controller\n- Check that authentication middleware is applied to both\n- Confirm route parameters are extracted identically\n\n### Architecture Violations\n\n- Never import controllers in main router\n- Always go through route modules\n- Maintain consistent file naming conventions\n\nThis approach ensures clean, maintainable code while providing the flexibility of multiple URL paths for the same functionality.\n",[],[181,427],"f1c31a34-7387-11f0-8a1d-0224a6c84d84","04-view.md","01988473-765e-7709-bfba-97efff3c576d",["D",1754568816144],"# Instructions for Adding /views/glimpse/:id Endpoint\n\nHere are the step-by-step instructions that would lead directly to the correct, clean implementation:\n\n## 1. Analyze the Requirements\n\n- Endpoint: GET /views/glimpse/:id\n- Authentication: Required (existing Google OAuth)\n- Input: Notion page ID (not database ID)\n- Output: JSON response with full service response (minus UI elements)\n- Data source: Notion page properties\n\n## 2. Examine Current Architecture\n\n### Check existing services to understand data access patterns\n\n```\ncat /backend/services/notion.service.ts\n```\n\n### Check existing routes structure\n\n```\ncat /backend/routes/views/\\_views.routes.ts\n```\n\n### Understand authentication flow\n\n```\ncat /main.tsx # Look for auth middleware setup\n```\n\n## 3. Identify Missing Service Method\n\n- Current service has getDatabaseById() for database metadata\n- Need getPageById() for individual page data\n- Service should return full Notion response for flexibility\n\n## 4. Add Service Method First\n\n```\n// Add to /backend/services/notion.service.ts\nexport async function getPageById(pageId: string) {\n  try {\n    const response = await notion.pages.retrieve({\n      page_id: pageId,\n    });\n    return {\n      success: true,\n      data: response,\n      timestamp: new Date().toISOString(),\n    };\n  } catch (error) {\n    return {\n      success: false,\n      error: error.message,\n      timestamp: new Date().toISOString(),\n    };\n  }\n}\n```\n\n## 5. Create Controller with Minimal Processing\n\n```\n// Create /backend/controllers/glimpse.controller.ts\nimport { Context } from \"npm:hono@3.12.12\";\nimport { getPageById } from \"../services/notion.service.ts\";\n\nexport async function glimpseHandler(c: Context) {\nconst id = c.req.param(\"id\");\n\nif (!id) {\n  return c.json({ error: \"Demo ID is required\" }, 400);\n}\n\nconst result = await getPageById(id);\n\nif (!result.success) {\n  return c.json({ error: \"Failed to fetch demo data\", details: result.error }, 500);\n}\n\n// Filter out button properties from the response\nif (result.data?.properties) {\n  const filteredProperties = Object.fromEntries(\n  Object.entries(result.data.properties).filter(([key, value]) => value?.type !== \"button\")\n);\n\n    result.data.properties = filteredProperties;\n\n  }\n\n  return c.json(result);\n}\n```\n\n## 6. Add Route\n\n```\n// Update /backend/routes/views/\\_views.routes.ts\nimport { Hono } from \"npm:hono@3.12.12\";\nimport { glimpseHandler } from \"../../controllers/glimpse.controller.ts\";\n\nconst app = new Hono();\n\napp.get(\"/glimpse/:id\", glimpseHandler);\n\nexport default app;\n```\n\n## 7. Update Documentation\n\n**Add to /backend/routes/views/README.md**\n\n### GET /views/glimpse/:id\n\n- **Purpose**: Returns Notion page data as JSON (filtered for data consumption)\n- **Authentication**: Required (Google OAuth)\n- **Parameters**: `id` - Notion page ID\n- **Response**: Service response object with Notion page data (button properties removed)\n- **Filtering**: Removes UI-specific properties (type: \"button\") for cleaner data consumption\n\n## 8. Key Design Principles\n\n✅ Controller Best Practices:\n\n- Single Responsibility: Controller handles HTTP concerns + minimal data cleanup\n- Thin Layer: Minimal processing, focused on improving data consumption\n- Useful Filtering: Remove UI elements that don't belong in data APIs\n- Consistent Error Handling: Standard error response format\n\n✅ Service Layer:\n\n- Data Access: Handle all Notion API interactions\n- Consistent Response Format: Always return {success, data/error, timestamp}\n- Raw Data: Return unfiltered data from external APIs\n\n✅ Separation of Concerns:\n\n- Controller: HTTP validation, routing, error responses, basic data cleanup\n- Service: External API calls, data retrieval\n- Client: Complex data processing, extraction, formatting\n\n## 9. Response Structure\n\n{\n\"success\": true,\n\"data\": {\n\"object\": \"page\",\n\"id\": \"notion-page-id\",\n\"properties\": {\n\"Name\": {\n\"type\": \"title\",\n\"title\": [{\"plain_text\": \"Demo Name\"}]\n},\n\"Status\": {\n\"type\": \"select\",\n\"select\": {\"name\": \"Active\"}\n}\n// Button properties filtered out\n}\n},\n\"timestamp\": \"2025-07-15T17:25:00.000Z\"\n}\n\n## 10. Key Decision Points\n\n✅ Correct Approach:\n\n- Data Source: Use notion.pages.retrieve() for page data\n- Controller Logic: Keep minimal but include useful data cleanup\n- Property Filtering: Remove UI-specific elements (buttons) that don't belong in data APIs\n- Error Handling: Consistent service response pattern\n\n✅ Appropriate Controller Processing:\n\n- UI Element Removal: Filter out button properties (not data)\n- Security Cleanup: Remove potentially sensitive UI configurations\n- Performance: Reduce payload size by removing unnecessary properties\n\n❌ Avoid These Mistakes:\n\n- Over-processing: Don't extract/transform business data in controller\n- Tight Coupling: Don't assume specific property names or structures\n- Inconsistent Responses: Don't create custom response formats\n- Mixed Responsibilities: Don't mix HTTP handling with complex business logic\n\n## 11. Testing Strategy\n\n**Test authentication (should show login page)**\n\ncurl /views/glimpse/test-id\n\n**Test with valid Notion page ID (after auth)**\n\ncurl -H \"Cookie: auth-cookie\" /views/glimpse/actual-notion-page-id\n\n**Verify button properties are filtered out**\n\nResponse should not contain any properties with \"type\": \"button\"\n\n## 12. Benefits of This Approach\n\n- Clean Data: Removes UI clutter from data API responses\n- Maintainable: Clear separation between layers with focused responsibilities\n- Flexible: Client can still extract any business data from Notion response\n- Consistent: Follows existing service response patterns\n- Secure: Prevents exposure of UI configurations\n- Performance: Smaller payloads without unnecessary UI properties\n- Future-proof: Easy to extend filtering logic for other UI property types\n\n## 13. When to Add Controller Processing\n\n✅ Good reasons to process in controller:\n\n- Remove UI-specific elements (buttons, formulas for display)\n- Filter sensitive configuration data\n- Remove properties that are never useful for data consumption\n- Basic security/privacy filtering\n\n❌ Avoid processing in controller:\n\n- Complex business logic transformations\n- Data extraction that depends on specific use cases\n- Heavy computational processing\n- Application-specific data formatting\n- This approach creates a clean, maintainable endpoint that provides useful data filtering while maintaining architectural best practices and keeping the controller focused on its core responsibilities.\n",[],[181,434],"f1c312c8-7387-11f0-8a1d-0224a6c84d84","03-webhooks.md","01988473-765e-7709-bfba-90bc81bd57a5",["D",1754568816144],"# Webhook Authentication Architecture Instructions\n\n## Townie instructions (Townie should follow these)\n\n## Middleware Order\n\nPlace authentication middleware in the following order:\n\n1. **Notion webhook auth middleware** (X-API-KEY for `/tasks/*`)\n2. **Global user auth middleware** (for other protected routes)\n3. **Route handlers**\n\n## Webhook Authentication\n\n### Scope\n\n- Apply only to routes under /tasks/\\*\n- All /tasks endpoints expect POSTs from Notion webhooks\n\n### Implementation\n\n- Create `/backend/routes/webhookAuthCheck.ts`\n- Extract X-API-KEY header from incoming requests\n- Compare against NOTION_WEBHOOK_SECRET environment variable\n- Use constant-time comparison to prevent timing attacks\n- Return 401/403 for authentication failures with generic error messages\n- Log failed authentication attempts for monitoring\n\n### Route Implementation Requirements\n\n**CRITICAL:** All webhook routes MUST use POST method:\n\n```\n// ✅ CORRECT - Webhooks are POST requests\napp.post(\"/webhook-endpoint\", async (c) => {\n  // Handle webhook\n});\n\n// ❌ WRONG - This won't work with webhooks\napp.get(\"/webhook-endpoint\", async (c) => {\n  // Webhooks can't reach this\n});\n```\n\nWhy: Notion (and most webhook providers) send POST requests, never GET.\n\n### Middleware Application (EXACT CODE)\n\nApply middleware in this EXACT order in main.tsx:\n\n```\n// 1. Webhook auth - ONLY for /tasks/* routes\napp.use(\"/tasks/*\", webhookAuth);\n\n// 2. User auth - for ALL routes EXCEPT /tasks/*\napp.use(\"/api/*\", authCheck);\napp.use(\"/views/*\", authCheck);\napp.use(\"/\", authCheck);\n\n// Add root route - now serves the authenticated dashboard\napp.get(\"/\", dashboardRoute);\n\n// 3. Mount routes AFTER middleware\napp.route(\"/tasks\", taskRoutes);\n```\n\n**Important:** We've changed the global authentication from app.use(\"\\*\") to more specific auth route handling.\n\n**Before:**\n\n```\napp.use(\"*\", authCheck);  // Applied to ALL routes including /tasks/*\n```\n\n**After:**\n\n```\napp.use(\"/api/*\", authCheck);   // Applied to API routes\napp.use(\"/views/*\", authCheck); // Applied to view routes\napp.use(\"/\", authCheck);        // Applied to root route\n```\n\n**This ensures:**\n\n✅ `/` (root) still requires user authentication\n✅ `/api/*` routes still require user authentication\n✅ `/views/*` routes still require user authentication\n✅ `/tasks/*` routes only use webhook authentication (no user auth)\n\n**Common mistake:** Using app.use(\"\\*\", webhookAuth) - this applies to all routes incorrectly.\n\n### Flow Logic\n\n- Request to /tasks/\\* → Check X-API-KEY → If valid, proceed to route handler (skip global auth)\n- Request to /tasks/\\* → Check X-API-KEY → If invalid, return 401 (never reaches global auth)\n- Request to other routes → Skip webhook auth → Go to global auth → Then route handler\n\n### Testing Webhook Authentication\n\nTest in this exact order:\n\n1. **Test without header** (should fail):\n\nPOST /tasks/test\nExpected: 401 \"Authentication required\"\n\n1. **Test with wrong key** (should fail):\n\nPOST /tasks/test\nHeaders: {\"X-API-KEY\": \"wrong-key\"}\nExpected: 403 \"Authentication failed\"\n\n1. Test with correct key (should succeed):\n\nPOST /tasks/test  \n Headers: {\"X-API-KEY\": \"your-configured-secret-value\"}\nExpected: 200 (reaches your route handler)\n\n**If step 3 returns 404:** Your route is probably defined as GET instead of POST.\n\n### Debugging Webhook Auth Issues\n\nAdd this temporary debug endpoint:\n\n```\napp.get(\"/debug-webhook\", (c) => {\n  const secret = Deno.env.get(\"NOTION_WEBHOOK_SECRET\");\n  return c.json({\n    hasSecret: !!secret,\n    secretLength: secret?.length || 0,\n  });\n});\n```\n\n**Expected response:** {\"hasSecret\":true,\"secretLength\":>0}\n\nAdd this catch all endpoint:\n\n```\n// Catch-all handler for undefined webhook endpoints\n// This must be the LAST route defined to catch unmatched paths\napp.post(\"*\", (c) => {\n  const path = c.req.path;\n  const method = c.req.method;\n  const returnObj = {\n    error: \"Endpoint not found\",\n    path: path,\n    method: method,\n    availableEndpoints: [\n      \"GET /tasks/debug-webhook\",\n      \"POST /tasks/test\",\n      \"POST /tasks/notion-webhook\",\n    ],\n  };\n  console.log(returnObj);\n\n  return c.json(returnObj, 404);\n});\n```\n\n### Complete Working Example\n\nHere's a complete working webhook endpoint:\n\n```\n// backend/routes/tasks/_tasks.routes.ts\nimport { Hono } from \"npm:hono@3.12.12\";\n\nconst app = new Hono();\n\napp.post(\"/notion-webhook\", async (c) => {\n  // At this point, webhook auth has already passed\n  const body = await c.req.json();\n  console.log(\"Notion webhook received:\", body);\n\n  // Process the webhook...\n\n  return c.json({ success: true });\n});\n\nexport default app;\n```\n\nTest with:\n\nPOST /tasks/notion-webhook\nHeaders: {\"X-API-KEY\": \"your-configured-secret-value\"}\nBody: {\"test\": \"data\"}\nExpected: 200 {\"success\": true}\n\n## Security Considerations\n\n- Webhook middleware should return early (success or failure) without calling next()\n- Never pass webhook requests to the global auth middleware\n- Maintain complete separation between webhook auth and user auth mechanisms\n- Consider rate limiting on /tasks endpoints\n- Use generic error messages that don't reveal authentication mechanism details\n\n## Route Structure\n\n- /tasks/\\* → Webhook auth required (Notion POSTs)\n- /api/\\* → User auth required (if applicable)\n- /\\* → Public routes (static files, etc.)\n\n## Key Changes Made:\n\n1. Added Environment Setup section with clear instructions for setting real values (without revealing actual values)\n1. Added Route Implementation Requirements emphasizing POST method requirement\n1. Added exact middleware application code to prevent ordering mistakes\n1. Added comprehensive testing steps with expected responses (using generic placeholders)\n1. Added debugging section with tools to troubleshoot issues\n1. Added complete working example to verify implementation against\n1. Emphasized critical points with bold text and warning boxes\n1. Added common mistakes and how to avoid them\n\nThese revisions address all the issues we encountered while keeping sensitive values generic and secure.\n\n---\n\n**Townie, stop here! Before proceeding to additional steps, confirm that this step is working correctly.**\n\nIf everything is working as intended, it's important for the user to go to Notion and test the webhook.\n\n### Test the webhook\n\n1. Go to `main.tsx`, click the green `HTTP` button, and copy the URL of this Val.\n1. In Notion, add a button to the Glimpse Demos database\n1. Edit the automation on that button: add the URL fromj step 1 and then append `/tasks/notion-webhook` to it\n1. Click the 'custom header' link under the webhook URL field and add this key and value: **Key**: `X-API-KEY`, **Value**: ``. (Find the value in the `NOTION_WEBHOOK_SECRET` key in `vars.env`)\n1. Click the save button\n1. Click the automation button in the Notion database row\n1. 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\n\nNext, tell the user that they can merge this branch into main, then delete this branch, and then they can proceed to the next step: glimpse. Don't write any code.\n\n---\n",[],[181,441],"f1c30bc0-7387-11f0-8a1d-0224a6c84d84","02-auth.md","01988473-765e-7709-bfba-8fa0d4de7db7",["D",1754568816144],"# Complete Authentication Implementation Instructions\n\n## Townie instructions (Townie should follow these)\n\nRead through all of these instructions in order to understand the architecture of this Val, and implementation details important to this Val, and then once you have it all in your memory you should get to work.\n\nIf anything is unclear, you should stop and ask me for clarification before proceeding. Do not write code if you are unsure of what is expected.\n\n**Important:** there are checkpoints in these instructions where you are directed to stop and ask permission before proceeding. Follow those instructions and do not proceed without permission.\n\n## LastLogin Built-in Features\n\n**Important:** LastLogin automatically handles certain routes and authentication flows:\n\n- **`/auth/logout`** - LastLogin intercepts this route and handles logout automatically\n- **No custom logout route needed** in your Hono app\n- **Simply link to `/auth/logout`** and LastLogin will clear the session and redirect\n- **Authentication headers** - LastLogin adds `X-LastLogin-Email` header for authenticated requests\n\n**Authentication Flow:**\n\n1. **Unauthenticated requests** → LastLogin checks for session\n2. **No session** → Returns 401 or redirects to login\n3. **Valid session** → Adds `X-LastLogin-Email` header and passes to your app\n4. **`/auth/logout` requests** → LastLogin clears session automatically (never reaches your app)\n\n## Step 1. Core Architecture Setup\n\n### Main Application (main.tsx)\n\n**Add global authentication middleware to `main.tsx`:**\n\n```typescript\nimport { lastlogin } from \"https://esm.town/v/stevekrouse/lastlogin_safe\";\n\n// Import route modules\nimport authCheck from \"./backend/routes/authCheck.ts\";\n// other route modules\n\nconst app = new Hono();\n\n// Apply global authentication middleware to ALL routes\napp.use(\"*\", authCheck);\n\n// other routes\n\n// Export with LastLogin wrapper\nasync function handler(request: Request): Promise {\n  return app.fetch(request);\n}\n\n// Wrap and export the main HTTP handler with lastlogin\nexport default lastlogin(handler);\n```\n\n### Dashboard Route Organization\n\n**Best Practice: Separate the root dashboard route from main.tsx**\n\nInstead of defining the root route directly in `main.tsx`, create a dedicated dashboard route file:\n\n- **Create**: `/backend/routes/dashboard.tsx`\n- **Purpose**: Handle the authenticated user's main dashboard/landing page\n- `import dashboardRoute from \"./backend/routes/dashboard.tsx\";`\n- **Mount in main.tsx**: `app.get(\"/\", dashboardRoute)`\n\nThis approach:\n\n- Keeps `main.tsx` focused on app setup and middleware\n- Makes the dashboard logic easier to maintain and test\n- Follows the modular architecture pattern used throughout the app\n- Allows for easier dashboard enhancements without touching core routing\n\nThe dashboard route should:\n\n- Display user information (email from `c.get(\"userEmail\")`)\n- Display the `/api/health` endpoint results as raw JSON in a  tag; e.g., JSON.stringify(data, null, 2)\n- Include logout functionality via `/auth/logout`\n- Show a simple and professional welcome interface with minimal styling\n\n### Create `/backend/routes/authCheck.ts`\n\n**Authentication Middleware:**\n\n- Retrieve the user's email: `const email = c.req.header(\"X-LastLogin-Email\")`\n- If email exists, the user is authenticated - store in context and continue to your app\n- If no email, show login page with LoginWithGoogleButton\n- **Note:** You don't need to handle `/auth/logout` - LastLogin does this automatically\n\n**Login Page Requirements:**\n\n- `import { LoginWithGoogleButton } from \"https://esm.town/v/stevekrouse/LoginWithGoogleButton\"`\n- Use the `` React Component, optionally supplying the `text` attribute\n- Add \"via LastLogin\" underneath LoginWithGoogleButton, centered, secondary text, linking to https://lastlogin.io/\n- Pass the email from the server to the client-side code if using React hydration or similar techniques\n\n**For authenticated users:**\n\n- Store email in context: `c.set('userEmail', email)`\n- In your authenticated views, add logout functionality: `Logout`\n\n**Public Routes Whitelist:**\n\n- Add a `PUBLIC_ROUTES` array at the top for routes that should be accessible without authentication\n- **Don't include `/auth/logout`** in the whitelist (LastLogin handles it before your middleware runs)\n- Use for truly public routes like: `/demo/:id`, `/api/health`, static assets, etc.\n\nIf you encounter problems loading the React button, try this simple approach for authCheck.ts:\n\n```typescript\n// Public routes that don't require authentication\nconst PUBLIC_ROUTES = [\n  // Add public routes here as needed\n  // '/demo/:id',  // Example: public demo viewing\n  // '/api/public', // Example: public API endpoints\n];\n\n// Helper function to check if a route is public\nfunction isPublicRoute(path: string): boolean {\n  return PUBLIC_ROUTES.some((route) => {\n    // Handle exact matches\n    if (route === path) return true;\n\n    // Handle wildcard patterns (basic implementation)\n    if (route.includes(\"*\")) {\n      const pattern = route.replace(\"*\", \".*\");\n      return new RegExp(`^${pattern}$`).test(path);\n    }\n\n    // Handle route parameters (basic implementation)\n    if (route.includes(\":\")) {\n      const pattern = route.replace(/:[^/]+/g, \"[^/]+\");\n      return new RegExp(`^${pattern}$`).test(path);\n    }\n\n    return false;\n  });\n}\n\nexport default async (c, next) => {\n  // Allow public routes to bypass authentication\n  if (isPublicRoute(c.req.path)) {\n    await next();\n    return;\n  }\n\n  const email = c.req.header(\"X-LastLogin-Email\");\n\n  if (!email) {\n    // Show login page if not authenticated\n    return c.html(`\n      \n      \n      \n        Your App - Login Required\n      \n      \n        \n          Sign in
\n          Sign in to access your app.
\n          \n            Loading login button...
\n          
\n          \n            via LastLogin\n          
\n        
\n\n        \n      \n      \n    `);\n  }\n\n  // If authenticated, store email in context for use by routes\n  c.set(\"userEmail\", email);\n\n  // Continue to the next middleware/route\n  await next();\n};\n```\n\n## Common Gotchas\n\n**Logout Route:**\n\n- ❌ Don't create a custom `/auth/logout` route in your Hono app\n- ✅ Just link to `/auth/logout` - LastLogin handles it automatically\n- The logout link will work for authenticated users without any custom code\n- LastLogin intercepts `/auth/logout` at the wrapper level before it reaches your middleware\n\n**Public Routes:**\n\n- Use the whitelist in authCheck.ts for routes that should be accessible without authentication\n- `/auth/logout` doesn't need to be whitelisted (LastLogin handles it before your middleware runs)\n- Examples of routes that should be whitelisted: public demos, health checks, static assets\n\n**Authentication Headers:**\n\n- Authenticated requests will have `X-LastLogin-Email` header\n- Unauthenticated requests will not have this header\n- LastLogin wrapper handles session validation before your code runs\n\n**Error Handling:**\n\n- If LastLogin can't validate a session, it returns 401 before reaching your app\n- Your authCheck middleware only runs for requests that pass LastLogin's validation\n- No need to handle session expiration - LastLogin manages this\n\n---\n\n**Townie, stop here! Before proceeding to additional steps, confirm that this step is working correctly.**\n\nIf everything is working as intended, tell the user that they can test auth by opening up `main.tsx` in a preview and signing in with LastLogin.\n\nAfter that, the user can merge this branch into main, and then proceed to the next step: webhook authentication. Don't write any code.\n\n---\n",[],[181,448],"f1c30210-7387-11f0-8a1d-0224a6c84d84","01-scaffold.md","01988473-765e-7709-bfba-8a3a84c77916",["D",1754568816144],"# Val Scaffolding Instructions\n\n### Environment variables required\n\n- `NOTION_API_KEY` - Your Notion integration API key\n- `NOTION_WEBHOOK_SECRET` - Matches the X-API-KEY custom header coming from Notion webhooks to /tasks/\\* endpoint(s)\n- `GLANCE_DEMOS_DB_ID` - Your Notion database ID for demos, which are personalized to prospects and have unique URLs\n- `GLANCE_CONTENT_DB_ID` - Your Notion database ID for demo page content, which are compiled into demos\n- `GLANCE_INTERACTIONS_DB_ID` - Your Notion database ID for pageview metrics and the like\n\n## Townie instructions (Townie should follow these)\n\nRead through all of these instructions in order to understand the architecture of this Val, and implementation details important to this Val, and then once you have it all in your memory you should get to work.\n\nIf anything is unclear, you should stop and ask me for clarification before proceeding. Do not write code if you are unsure of what is expected.\n\n**Important:** there are checkpoints in these instructions where you are directed to stop and ask permission before proceeding. Follow those instructions and do not proceed without permission.\n\n## Architecture Overview (Read This First!)\n\nThis Val follows a strict layered architecture. Understanding these layers is critical before writing any code:\n\n### Layer Responsibilities\n\n**Services** (/backend/services/):\n\n- Single-purpose functions that make direct API calls to external systems\n- Pure functions that handle HTTP transport layer (response.ok)\n- Example: getDatabaseById(id), searchNotionDatabases()\n- Should NOT handle environment variables, business logic, or orchestrate multiple calls\n- Return consistent { success: boolean, data?: any, error?: string } format\n\n**Controllers** (/backend/controllers/):\n\n- Business logic and orchestration between services\n- Handle environment variables and configuration\n- Coordinate multiple service calls\n- Implement business rules and validation\n- Handle service business logic layer (result.success)\n- Example: getHealthStatus(), validateConfiguredDatabases()\n\n**Routes** (/backend/routes/):\n\n- HTTP request/response handling only\n- Call controllers, never services directly\n- Minimal logic - just HTTP concerns (parsing, validation, response formatting)\n- Example: parsing request params, calling controller, returning JSON\n\n### Service Response Pattern\n\nWe use a consistent two-layer response handling strategy:\n\n**Layer 1: HTTP Transport Layer** (response.ok)\n\n- Used when checking responses from external APIs (Notion, etc.)\n- Validates HTTP request succeeded (status 200-299)\n- Handles network failures, auth issues, server errors\n\n**Layer 2: Service Business Logic** (result.success)\n\n- Used when checking our ServiceResponse objects\n- Validates business operation succeeded\n- Handles application-level failures, data validation, business rule violations\n\n## Implementation Steps\n\n### Step 1: Create Directory Structure\n\nCreate this directory structure with README.md files:\n\n- main.tsx - entrypoint for this Val, where the Hono app is initialized\n- /backend - directory for backend code\n  - /routes - HTTP route handlers organized by functionality\n  - /api - JSON API endpoints for frontend/backend communication\n  - /tasks - Webhook handlers for Notion integrations\n  - /views - Server-side rendered views for frontend\n  - /services - External API integrations (pure API calls only)\n  - /controllers - Business logic coordination between routes and services\n  - /crons - Scheduled task handlers\n  - /types - Shared TypeScript type definitions\n  - /utils - Common utility functions\n- /frontend - Client-side files that render in the browser\n- /shared - Files used by both backend and frontend\n\nEach route subdirectory should have a \\_[directory_name].routes.ts file that mounts routes for that section.\n\n---\n\nTownie, stop here! Ask for permission to proceed.\n\n---\n\n### Step 2: Set Up Main App and Route Structure\n\n**main.tsx**\nSet up a Hono app like this:\n\n```\nimport { Hono } from \"npm:hono@3.12.12\";\n\n// Import route modules\nimport apiRoutes from \"./backend/routes/api/\\_api.routes.ts\";\nimport taskRoutes from \"./backend/routes/tasks/\\_tasks.routes.ts\";\nimport viewRoutes from \"./backend/routes/views/\\_views.routes.ts\";\n\nconst app = new Hono();\n\n// Unwrap Hono errors to see original error details\napp.onError((err, c) => {\n  throw err;\n});\n\n// Mount route modules\napp.route(\"/api\", apiRoutes);\napp.route(\"/tasks\", taskRoutes);\napp.route(\"/views\", viewRoutes);\n\nexport default app.fetch;\n```\n\n**Route Module Template**\nEach \\_[directory].routes.ts file should follow this pattern:\n\n```\nimport { Hono } from \"npm:hono@3.12.12\";\n\nconst app = new Hono();\n\n// TODO: Add routes here\n\nexport default app;\n```\n\n---\n\nTownie, stop here! Ask for permission to proceed.\n\n---\n\n### Step 3: Create Service Layer (API Calls Only)\n\nCreate /backend/services/notion.service.ts with ONLY direct Notion API calls:\n\n**Notion Service Requirements:**\n\n- Import Notion: `import { Client } from \"npm:@notionhq/client\";`\n- Initialize: `const notion = new Client({ auth: Deno.env.get(\"NOTION_API_KEY\") });`\n- Create these functions (API calls only, no business logic):\n  - `getDatabases()` - search for all databases\n  - `getDatabaseById(databaseId: string)` - retrieve specific database\n\n**Service Function Pattern:**\n\n```\nexport async function getDatabaseById(databaseId: string) {\n  try {\n    const response = await notion.databases.retrieve({\n      database_id: databaseId,\n    });\n    return {\n      success: true,\n      data: response,\n      timestamp: new Date().toISOString(),\n    };\n  } catch (error) {\n    return {\n      success: false,\n      error: error.message,\n      timestamp: new Date().toISOString(),\n    };\n  }\n}\n```\n\n**Important:** Services should NOT handle environment variables for database IDs or orchestrate multiple calls. That's controller responsibility.\n\n---\n\nTownie, stop here! Ask for permission to proceed.\n\n---\n\n### Step 4: Create Controller Layer (Business Logic)\n\nCreate /backend/controllers/health.controller.ts that orchestrates services:\n\n**Controller Requirements:**\n\n- Import service functions: `import { getDatabaseById } from \"../services/notion.service.ts\";`\n- Handle environment variables `(GLANCE_DEMOS_DB_ID, GLANCE_CONTENT_DB_ID, GLANCE_INTERACTIONS_DB_ID)`\n- Orchestrate multiple service calls\n- Implement business logic for health checking\n\n**Required Controller Functions:**\n\n- `getConfiguredDatabases()` - Check all configured databases using environment variables\n- `getHealthStatus()` - Generate formatted health response for API\n\n**Controller Function Pattern:**\n\n```\nexport async function getConfiguredDatabases() {\n  const demosDbId = Deno.env.get(\"GLANCE_DEMOS_DB_ID\");\n  // ... get other DB IDs\n\n  const databases = { demos: null, content: null, interactions: null };\n  const errors: string[] = [];\n\n  // For each configured database:\n  if (demosDbId) {\n    const result = await getDatabaseById(demosDbId); // Call service\n    if (result.success) {\n      databases.demos = result.data;\n    } else {\n      errors.push(`Demos DB: ${result.error}`);\n    }\n  } else {\n    errors.push(\"GLANCE_DEMOS_DB_ID not configured\");\n  }\n\n  // ... repeat for other databases\n\n  return {\n    success: errors.length === 0,\n    data: databases,\n    errors: errors.length > 0 ? errors : undefined,\n    timestamp: new Date().toISOString(),\n  };\n}\n```\n\n---\n\nTownie, stop here! Ask for permission to proceed.\n\n---\n\n### Step 5: Create Route Layer (HTTP Handling)\n\n**Add Health Endpoint**\n\nIn /backend/routes/api/\\_api.routes.ts:\n\n```\nimport { Hono } from \"npm:hono@3.12.12\";\nimport { getHealthStatus } from \"../../controllers/health.controller.ts\";\n\nconst app = new Hono();\n\napp.get(\"/health\", async (c) => {\n  const healthStatus = await getHealthStatus();\n  return c.json(healthStatus);\n});\n\nexport default app;\n```\n\n**Add Root Route**\n\nIn main.tsx, add a root route:\n\n```\n// Add this before mounting route modules\napp.get(\"/\", async (c) => {\n  return c.html(`Welcome
`);\n});\n```\n\n---\n\nTownie, stop here! Ask for permission to proceed.\n\n---\n\n## Architecture Validation\n\nBefore proceeding, verify your implementation follows the architecture:\n\n- Services only make direct API calls (no environment variables, no orchestration)\n- Controllers handle business logic and coordinate services\n- Routes only handle HTTP concerns and call controllers\n- No service calls directly from routes\n- Environment variables handled in controllers, not services\n- Consistent response patterns across all layers\n\n### Expected Behavior\n\nThe health endpoint should return:\n\n```\n{\n  \"status\": \"ok\",\n  \"timestamp\": \"2025-07-14T18:26:28.270Z\",\n  \"service\": \"glance-demos\",\n  \"databases\": {\n    \"configured\": true,\n    \"demos\": \"connected\",\n    \"content\": \"connected\",\n    \"interactions\": \"connected\"\n  }\n}\n```\n\nThis architecture is intended to create clear separation of concerns and should make the codebase maintainable and testable.\n\n---\n\n**Townie, stop here! Before proceeding to additional steps, confirm that this step is working correctly.**\n\n**Important**: If there was an error regarding environment variables, remind the user to upload `vars.env` to the Environment Variables section of this Val.\n\nOnce everything is working as intended, always conclude this step with these messages:\n\n1. Briefly summarize the scaffolding that was just completed and why it's important\n1. Provide the URL to the health endpoint so the user can see that the endpoint is live. (Always conclude this step with a link to the health endpoint, if you can provide one.)\n1. Tell the user that they can proceed to the next step: `/_townie/02-auth.md`.\n\nDon't write any code.\n\n---\n",[],[181,455],"f1c2ed16-7387-11f0-8a1d-0224a6c84d84","00-setup.md","01988473-765e-7709-bfba-8513579878b1",["D",1754568816144],"# SETUP\n\nUse this file to guide you through the Glimpse setup process.\n\nThe 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.\n\n## Prompts in this file\n\nThe prompts for you to enter into Townie are in code blocks, like this:\n\n```\nI'm a prompt for Townie\n```\n\nTownie 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.\n\nOnce those bits are complete, you can add features til your heart's content.\n\n## Prerequisites\n\n1. a val.town account\n1. `vt` on your computer. If not, follow [the instructions on the Github README](https://github.com/val-town/vt)\n1. Remix this Val on val.town, and give it a new name\n1. Use `vt` to clone the Val to your computer\n1. Add a file called `vars.env` at the root of the Val\n1. Add `vars.env` to the bottom of your .vtignore file, so that your environment variables aren't uploaded to val.town (they're secret)\n1. Add your environment variables to `vars.env`; if you don't have them, contact your administrator\n1. Go to the Environment Variables section of your Val on val.town and import the `vars.env` file\n\nOnce 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](https://docs.val.town/reference/environment-variables/).\n\n### Environment variables (required)\n\n**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.\n\n- `NOTION_API_KEY` - Your Notion integration API key\n- `NOTION_WEBHOOK_SECRET` - Matches the X-API-KEY custom header coming from Notion webhooks to /tasks/\\* endpoint(s)\n- `GLANCE_DEMOS_DB_ID` - Your Notion database ID for demos, which are personalized to prospects and have unique URLs\n- `GLANCE_CONTENT_DB_ID` - Your Notion database ID for demo page content, which are compiled into demos\n- `GLANCE_INTERACTIONS_DB_ID` - Your Notion database ID for pageview metrics and the like\n\n# Townie instructions\n\nOnce 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.\n\n**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.\"\n\nBranches 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](https://docs.val.town/vals/branches/)\n\nOk, now to the fun stuff.\n\n## 01-scaffold.md\n\n1. Go to Townie, select this Val, and prompt Townie with this line:\n\n```\nScaffold this Val with what you see in `/_townie/01-scaffold.md`\n```\n\n## 02-auth.md\n\n1. In val.town, create a branch in your Val called `auth`\n1. Go to Townie, select this Val, and then select the `auth` branch\n1. Prompt Townie with this line:\n\n```\nAdd auth to this Val with what you see in `/_townie/02-auth.md`\n```\n\nWork with Townie to make sure what appears at `/` is correct. Once it's correct, move on to the next step.\n\n## 03-webhooks.md\n\n1. In val.town, merge `auth` into `main`\n1. Delete the `auth` branch\n1. Create a branch in your Val called `webhooks`\n1. Go to Townie, select this Val, and then select the `webhooks` branch\n1. Prompt Townie with this line:\n\n```\nAdd webhook auth to this Val with what you see in `/_townie/03-webhooks.md`\n```\n\n### Test the webhook\n\n1. Go to `main.tsx`, click the green `HTTP` button, and copy the URL of this Val.\n1. In Notion, add a button to the Glimpse Demos database\n1. Edit the automation on that button: add the URL from step 1 and then append `/tasks/notion-webhook` to it\n1. Click the 'custom header' link under the webhook URL field and add this key and value: **Key**: `X-API-KEY`, **Value**: ``. (Find the value in the `NOTION_WEBHOOK_SECRET` key in `vars.env`)\n1. Click the save button\n1. Click the automation button in the Notion database row\n1. 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\n\n## 04-view.md\n\n1. Merge the `webhooks` branch into `main`\n1. Delete the `webhooks` branch\n1. Create a branch called `view`\n1. Go to Townie, select this Val, and then select the `view` branch\n1. Prompt Townie with this line:\n\n```\nAdd an endpoint at `/views/glimpse/:id` by following the instructions in `/_townie/04-view.md`\n```\n\nFor now we will just have to trust that this new endpoint works. We will verify that's true in the next few steps.\n\n## 05-glimpse.md\n\n1. Prompt Townie with this line:\n\n```\nAdd a route for `/glimpse/:id` by following the instructions in `/_townie/05-glimpse.md`.\n```\n\n## 06-link.md\n\nTODO: enter directions\n\n## 07-save.md\n\n1. Merge the `view` branch into main\n1. Delete the `view` branch\n1. Create a new branch called `save`\n\n```\nFollow the instructions in `/_townie/07-save.md` to add an endpoint at `/tasks/url`.\n```\n\n### Test the /tasks/url endpoint\n\n1. In Notion, add a button to a database row in the Glimpse Demos database called \"Staging: set URL\"\n1. Edit the automation on that button to be a webhook that hits `https:///tasks/url`\n1. Add the custom header for webhook auth: **Key**: `X-API-KEY` and **Value**: ``. (Find the value in the `NOTION_WEBHOOK_SECRET` key in `vars.env`)\n1. Save the button automation\n1. Click the button in Notion\n1. You should see the `URL` property update with a URL to a Glimpse endpoint on val.town\n1. If it fails, clues as to why are in the logs\n1. Go to the Logs in your Val and see the latest log statement\n1. If there's an error captured there, explain that to Townie\n\n## 08-related.md\n\n1. Merge `save` into main\n1. Delete the `save` branch\n1. Create a new branch called `related`\n\n```\nAdd related pages to the /glimpse/:id endpoint by following the instructions in `/_townie/08-related.md`\n```\n\nTODO: have Townie's success message at the end tell the user to update Notion automation with the URL on the main branch\n\n1. In Notion, click the URL in the `URL` property; it should not work. That URL is from a previous branch that we deleted.\n1. Go to `main.tsx` and get the URL for this branch\n1. Edit the automation on the \"Set URL\" button with that URL; make sure it incudes the `/tasks/url` endpoint\n1. Save the button automation\n1. Click the button in Notion\n1. You should see the `URL` property update with a URL to a Glimpse endpoint on val.town\n1. Click the new URL\n1. Authenticate\n1. CTRL+F `glimpseContent` -- that's the object that holds the related content you see in Notion\n\n## 09-cache.md\n\n1. Merge `related` into main\n1. Delete the `related` branch\n1. Create a new branch called `cache`\n\n```\nUse the instructions in /_townie/09-cache.md to implement a cache for Glimpse demos at the `/glimpse/:id` endpoint\n\n```\n\n1. merge `cache` into `main`\n1. set cron interval to 1 minute\n\nAfter merging into `main`:\n\nCRITICAL: Go to the Val Town web UI and set the cron schedule for `/backend/crons/cache_glimpse_data.ts` to run every minute\n\n## 10-react.md\n\nNow 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.\n\n1. Delete the `cache` branch\n1. Create a new branch called `react`\n\n```\nUse the instructions in `/_townie/10-react.md` to implement a React bootstrap for the `/glimpse/:id` endpoint\n\n```\n\n1. test `/glimpse/:id` endpoint in the `react` branch\n1. if it looks good, merge `react` into `main`\n1. delete `react` branch\n\n## 11-html.md\n\n1. Create a new branch called `html`\n1. Go to townie and select the `html` branch\n1. Enter this into townie:\n\nTODO: make sure that the html instructions are clear about persisting the page layout with header including auth, sidenav, main content and footer.\n\nTODO: UPDATE THE ENDPOINT BIT BELOW WITH A REAL URL BUILT BY TOWNIE LIKE IN THE LINK STEP ABOVE\n\n```\nuse 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\n```\n\n1. test `/glimpse/:id` endpoint in the `html` branch\n1. if it looks good, merge `html` into `main`\n1. delete `html` branch\n\n## 12-embed.md\n\n1. Create a new branch called `pdf-embeds`\n1. Go to Townie and select the `pdf-embeds` branch\n1. Enter this into Townie:\n\n```\nfollow the instructions in `/_townie/12-embed.md` to implement rendering for certain embed blocks\n\n```\n\nThe link is rendered as a button but it 404s. We need to implement the `/glimpse/:id/pdf` route.\n\n## 12-PDF-ROUTE.md\n\n1. Create a new branch called `pdf-route`\n1. Go to Townie and select the `pdf-route` branch\n1. Enter this into Townie:\n\n```\nfollow the instructions in /_townie/PDF-ROUTE.md to implement rendering for certain embed blocks\n\n```\n",[],[181,462],["D",1754568816144],[197,198,199,200,201,202,203,204,205,206,207,208,209],[181],["D",1754568816144],{"_104":103,"_111":107},{"_104":103,"_105":-5,"_106":107,"_18":58,"_108":109,"_110":25},{"_13":89,"_32":90,"_47":41,"_91":48,"_92":93,"_94":95,"_96":54,"_97":98,"_99":100,"_101":49,"_102":103},"ctx",{"_82":-5,"_133":508,"_509":510,"_511":512,"_513":25,"_514":25,"_515":25,"_516":62,"_517":-5,"_518":-7,"_519":-7,"_520":66,"_521":25,"_522":25,"_523":-5,"_524":25,"_525":25,"_526":25,"_527":-5},"ENV",{"_479":480,"_481":482,"_483":90,"_484":485,"_486":487,"_488":489,"_490":491,"_492":493,"_494":495,"_496":497,"_498":499,"_500":501,"_502":503,"_504":505,"_506":507},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]
Diff · v12
