Glance Demos

A Val Town application for managing and viewing demos with authentication.

• Authentication: Google OAuth via LastLogin
• Dashboard: User-friendly interface showing system status
• Health Monitoring: Real-time system health checks
• Modular Architecture: Clean separation of concerns

This application uses LastLogin for authentication:

• Login: Users sign in with their Google account
• Protected Routes: All routes require authentication except public endpoints
• Logout: Users can logout via /auth/logout (handled automatically by LastLogin)
• Session Management: Automatic session validation and renewal

The following routes are accessible without authentication:

• /api/health - System health status

Routes are protected by different authentication mechanisms:

User Authentication (Google OAuth via LastLogin):

• / - Main dashboard (shows user info and system status)
• /api/* - API endpoints (except health)
• /views/* - View routes including /views/glimpse/:id
• /glimpse/* - Shortcut routes including /glimpse/:id (equivalent to /views/glimpse/:id)

Webhook Authentication (X-API-KEY header):

• /tasks/* - Webhook endpoints for external integrations (POST requests only)
  • GET requests to /tasks/* are allowed without authentication for debug endpoints

├── backend/
│   ├── controllers/         # Business logic controllers
│   ├── routes/             # Route definitions and HTTP handling
│   │   ├── api/            # API endpoints
│   │   ├── glimpse/        # Glimpse routes (enhanced with React frontend)
│   │   ├── tasks/          # Task-related routes
│   │   ├── views/          # User-facing views
│   │   └── authCheck.ts    # Authentication middleware
│   └── services/           # External service integrations
├── frontend/               # React frontend assets
│   ├── glimpse.html        # HTML template for glimpse views
│   ├── glimpse.tsx         # React entry point
│   ├── components/         # React components
│   │   ├── GlimpseView.tsx # Main glimpse display component
│   │   ├── NotionBlock.tsx # Notion block renderer
│   │   └── NotionProperty.tsx # Property display component
│   └── README.md
├── shared/                 # Shared utilities and types
│   ├── types.ts           # TypeScript interfaces for Notion data
│   ├── utils.ts           # Shared utility functions
│   └── README.md
└── main.tsx               # Application entry point with static file serving

The application follows a clean MVC architecture with proper separation of concerns:

• Handles HTTP request/response formatting
• Extracts parameters from requests
• Applies authentication middleware
• Calls controller functions and formats responses
• Manages HTTP status codes and error responses

• Contains business logic and orchestrates service calls
• Returns plain data objects (not HTTP responses)
• Handles data validation and transformation
• Filters sensitive data (e.g., button properties)
• Provides consistent success/error response structure

• Handles external API calls (Notion, databases)
• Manages data persistence
• Returns structured results with success/error information

All controller functions return a consistent structure:

{
  success: boolean,
  data: any | null,
  error: string | null,
  details?: string  // Additional error context
}

Routes then format these into appropriate HTTP responses.

The application provides multiple routes for accessing page data and user authentication:

• GET /glimpse/login - User-specific login redirect

  • Requires user authentication (Google OAuth via LastLogin)
  • Looks up authenticated user's email in GLANCE_DEMOS_DB_ID database
  • If user found: Redirects to user's personal URL
  • If user not found: Creates new user record and redirects to /glimpse/thanks
  • Shows detailed error information for debugging database structure issues

• GET /glimpse/thanks - New user welcome page

  • Shows confirmation that user account was created
  • Explains next steps (admin review, email with demo link)
  • Provides timeline expectations (1-2 business days)

• GET /views/glimpse/:id - Get complete page data with blocks by Notion page ID (JSON only)
• GET /glimpse/:id - Enhanced with React Frontend - Content negotiation based on Accept header:
  • Browser requests (Accept: text/html): Returns rich React frontend with interactive Notion content display
  • API requests (Accept: application/json): Returns raw JSON data (same as before)
  • Fallback: If HTML template fails to load, automatically serves JSON

The /glimpse/:id endpoint now includes a rich React frontend when accessed via browser:

• Rich Notion Blocks: Supports headings, paragraphs, lists, code blocks, callouts, images, videos, tables, and more
• Property Display: Shows all page properties with type-specific formatting and icons
• Responsive Design: Mobile-friendly layout using TailwindCSS
• Server-Side Data Injection: Initial data injected to eliminate loading states

• Error Handling: Graceful error states with retry functionality
• Loading States: Smooth loading indicators
• Navigation: Easy return to dashboard
• Debug Mode: Raw data view in development environments

• Content Negotiation: Single endpoint serves both HTML and JSON
• Static File Serving: Frontend assets served via /frontend/* route
• React 18.2.0: Pinned version for consistency
• TypeScript Support: Shared types for Notion data structures

Note: The glimpse endpoints now provide both programmatic access (JSON) and user-friendly viewing (React frontend) from the same URL, maintaining backward compatibility while adding rich content display capabilities.

API endpoints for accessing Notion page data with different levels of detail:

• GET /api/demo/:id/properties - Returns page properties only
• GET /api/demo/:id - Returns page properties + all blocks recursively

Architecture:

• Routes: Handle HTTP concerns (parameter extraction, response formatting, status codes)
• Controllers: Contain business logic (getDemoProperties, getDemoFull)
• Services: Handle Notion API integration

Authentication Behavior:

• Browser requests: Require user authentication (Google OAuth via LastLogin)
• Internal requests: Bypass authentication when called from within the Val (identified by Deno user agent)

Response Format: Routes return the data directly from controllers on success:

{
  // Notion page object with properties
  // For full endpoint: also includes "blocks" array with recursive block data
}

On error, routes return:

{
  "error": "Error message",
  "details": "Additional error context"
}

Usage Examples:

// Internal call from within Val (no authentication needed)
const response = await fetch('/api/demo/page-id/properties');
const data = await response.json();

// External browser request (requires authentication)
// User must be logged in via Google OAuth

All glimpse routes:

• Require user authentication
• Return complete page data including properties and blocks recursively
• Filter out button properties from Notion page data
• Return standardized JSON responses (except authentication routes which redirect or show HTML)
• Use the same controller functions as the API endpoints for consistency

1. Authentication: User must be authenticated via Google OAuth (handled by LastLogin)
2. Database Lookup: System queries GLANCE_DEMOS_DB_ID database for user's email
3. User Creation: If not found, creates new user record with email address
4. Welcome Page: Redirects to /glimpse/thanks with next steps information
5. Admin Process: Admin reviews new users and adds demo URLs manually
6. User Return: User can return to /glimpse/login once URL is configured

The GLANCE_DEMOS_DB_ID database must contain:

• Email property: Contains user's email address (exact match with authenticated email)
• URL property: Contains user's redirect URL (optional for new users)

Supported URL property names: URL, Link, Redirect URL, Demo URL, url, link Supported URL property types: url, rich_text, title

The login endpoint provides detailed error information for debugging:

• Missing environment variables
• Database query failures
• User creation failures (falls back to access denied page)
• Invalid or missing URL properties
• URL format validation errors

The dashboard displays both routes in a comparison table for easy testing.

The application is built with:

• Hono: Web framework for routing and middleware
• LastLogin: Authentication service
• TypeScript: Type-safe development
• Val Town: Hosting platform

The application supports webhook endpoints for external integrations (like Notion webhooks):

Set the webhook secret in your environment:

NOTION_WEBHOOK_SECRET=your-secret-key-here

• POST /tasks/notion-webhook - Main webhook endpoint for Notion integrations (requires X-API-KEY header)
• POST /tasks/url - Updates Notion page URL property with glimpse URL (requires X-API-KEY header)
• POST /tasks/assign - Assigns agents to tasks based on Person property matching (requires X-API-KEY header)
• POST /tasks/test - Test endpoint for webhook authentication (requires X-API-KEY header)
• GET /tasks/debug-webhook - Debug endpoint to check webhook configuration

The assignment webhook automatically assigns agents to tasks based on Person property matching:

Workflow:

1. Receives webhook with page ID from Notion
2. Retrieves page properties to extract Person and Viewing properties
3. Checks if Viewing property is true - if not, skips assignment and logs result
4. Queries GLANCE_AGENTS_DB_ID database for agents with matching Person property
5. PHASE 1: Data Collection - Fetches complete page data for all agents (no side effects)
6. Validates all data collection succeeded - aborts if any agent data fetch fails
7. PHASE 2: Atomic Updates - Selective clearing and assignment updates
   • Step 2a: Checks each agent's current demo assignments
   • Selective Clearing: Only clears agents assigned to OTHER demos (not this one)
   • Step 2b: Updates demo page's "Glimpse agents" property
8. PHASE 3: Non-Critical Updates - Updates agent blob (non-blocking, won't fail webhook)

Relation Management:

• Smart Clearing: Only clears agents when they're assigned to different demos
• Preserves Same-Demo Assignments: No clearing when reassigning to the same demo
• Prevents Multiple Assignments: Ensures agents are only assigned to one demo at a time
• Efficient: Minimal API calls - only clears when necessary
• Reliable: Handles new agents, existing agents, and reassignments correctly

Relation Management:

• Simplified Approach: Only updates the demo page's "Glimpse agents" property
• Automatic Bidirectional Updates: Notion automatically updates agents' "Glimpse demos" properties
• No Manual Clearing: Eliminates the risk of clearing relations without repopulating them
• Reliable Reassignment: Works correctly even when reassigning the same agents

Error Handling & Reliability:

• Transactional Approach: Collects all required data before making any changes
• Early Validation: Aborts assignment if any agent data cannot be fetched
• Atomic Updates: Critical Notion updates happen together or not at all
• Non-Blocking Blob Updates: Blob failures are logged but don't fail the webhook
• Comprehensive Logging: Detailed checkpoint logging at each phase for debugging
• Graceful Degradation: Continues with available data when possible

Agent Blob Storage:

• Key Pattern: glimpse--agent--{pageId} (where pageId is from the webhook)
• Data Structure:

{
  "pageId": "page-id",
  "agents": [
    {
      "agentId": "agent-page-id",
      "agentName": "Agent Name",
      "agentEmail": "agent@example.com", 
      "agentMeetUrl": "https://meet.google.com/...",
      "agentPhone": "+1234567890"
    }
  ],
  "lastUpdated": "2025-09-10T19:52:00.000Z",
  "assignedAt": "2025-09-10T19:52:00.000Z"
}

Requirements:

• Page must have a Viewing property set to true (assignment only occurs for actively viewed pages)
• Page must have a Person property with assigned person
• Agents database must have pages with Person properties matching the assigned person
• Original page must have a "Glimpse agents" relation property
• Agent pages must have a "Glimpse demos" relation property

Viewing Property Support:

• Checkbox: true value
• Select: "true" option name
• Rich Text: "true" or "yes" text content (case-insensitive)

Response Format (Assignment Completed):

{
  "success": true,
  "message": "Task assignment completed successfully",
  "pageId": "page-id",
  "personId": "person-id", 
  "agentsAssigned": 2,
  "agentsClearedCount": 1,
  "agentsSkippedClearing": 1,
  "agentBlobUpdated": true,
  "timestamp": "2025-09-10T16:51:24.733Z"
}

Response Format (Assignment Skipped):

{
  "success": true,
  "message": "Page is not being viewed - assignment skipped",
  "pageId": "page-id",
  "viewing": false,
  "timestamp": "2025-09-10T16:51:24.733Z"
}

Relation Management:

• Smart Clearing: Only clears agents when they're assigned to different demos
• Preserves Same-Demo Assignments: No clearing when reassigning to the same demo
• Prevents Multiple Assignments: Ensures agents are only assigned to one demo at a time
• Efficient: Minimal API calls - only clears when necessary
• Reliable: Handles new agents, existing agents, and reassignments correctly
• Agent blob storage provides fast access to agent details without additional Notion API calls

Webhook endpoints require the X-API-KEY header:

curl -X POST https://your-val.web.val.run/tasks/test \
  -H "X-API-KEY: your-secret-key-here"

Use the webhook testing form in the dashboard:

1. Navigate to your dashboard at /
2. Find the "Webhook Endpoint" section
3. Enter your NOTION_WEBHOOK_SECRET value
4. Click "Test Webhook" to verify authentication

Configure these environment variables for full functionality:

• GLANCE_DEMOS_DB_ID - Notion database ID for demos
• GLANCE_CONTENT_DB_ID - Notion database ID for content
• GLANCE_INTERACTIONS_DB_ID - Notion database ID for interactions
• GLANCE_AGENTS_DB_ID - Notion database ID for agents
• NOTION_API_KEY - Notion API key for database access
• NOTION_WEBHOOK_SECRET - Secret key for webhook authentication

The application includes real-time viewing analytics with immediate Notion synchronization and email-based authorization:

• Email-based Access Control: Viewing analytics are only tracked when the authenticated user's email matches the page's Email property
• Frontend Authorization: Email comparison happens on the frontend before any API calls are made
• Zero Unauthorized Calls: Users without matching emails generate no viewing API requests
• Automatic Detection: System automatically extracts emails from Notion page properties and user authentication

• Fast blob updates: Page viewing status stored in Val Town blob storage for instant response (~100ms)
• Immediate Notion sync: When users start viewing pages, Notion database is updated immediately
• Automatic cleanup: Cron job runs every minute to mark stale sessions (>1 minute old) as not viewing

1. Authorization Check: Frontend compares user email with page Email property
2. Authorized Users: Frontend calls /api/viewing → Blob updated → Notion synced immediately
3. User continues viewing: Frontend updates blob every 4 seconds (no Notion calls)
4. User leaves/session stale: Cron detects stale session → Blob updated → Notion synced immediately
5. Unauthorized Users: No API calls made, no viewing analytics tracked

Pages must include an Email property in Notion for viewing analytics to work:

• Property Name: "Email" or "email"
• Property Type: Email type or Rich Text type
• Content: Must exactly match the authenticated user's email address

Pages in your Notion databases should include these properties for viewing analytics:

• Email (Email or Rich Text) - Required for authorization
• Viewing (Checkbox) - Real-time viewing status
• Last Viewed (Date) - Timestamp of last viewing activity
• Current Viewer (Rich Text) - Email of current viewer
• Tab Visible (Checkbox) - Whether page tab is currently visible

• Email Authorization: Compares authenticated user email with page Email property before tracking
• Page Visibility API: Tracks when users switch tabs or minimize windows
• Periodic updates: Calls viewing API every 4 seconds while page is active (authorized users only)
• Session management: Automatic cleanup handles crashed browsers and network issues
• Performance: Non-blocking API calls don't impact user experience, zero calls for unauthorized users