Controllers

Business logic coordination between routes and services.

Controllers are the business logic layer that:

• Orchestrate multiple service calls and coordinate data flow
• Handle environment variables and application configuration
• Implement business rules, validation, and data transformation
• Convert between external API formats and application data models
• Return structured data objects (not HTTP responses)
• Provide consistent success/error response structure

Controllers do NOT:

• Handle HTTP request/response objects (except for specific patterns)
• Make direct external API calls (use services instead)
• Contain presentation logic or HTML generation (except auth flows)

All controller functions return:

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

When to use: Most API endpoints, business logic that can be tested independently

Characteristics:

• Accept simple parameters (strings, numbers, objects)
• Return structured data objects
• Can be called from multiple contexts (HTTP, cron, etc.)
• Easy to unit test

Data Flow:

Route → Controller → Service(s) → External API
Route ← Controller ← Service(s) ← External API

Input Data:

id: string  // Notion page UUID

Processing:

1. Validates page ID is provided
2. Calls getPageById(id) service
3. Filters out button properties (business rule)
4. Returns sanitized page data

Output Data:

{
  success: true,
  data: {
    id: string,
    properties: {
      // All properties except type: "button"
      [key: string]: NotionPropertyValue
    },
    parent: NotionParent,
    // ... other page fields
  },
  error: null
}

Input Data:

id: string  // Notion page UUID

Processing:

1. Validates page ID is provided
2. Calls getPageWithBlocks(id) service (orchestrates page + blocks)
3. Filters out button properties (business rule)
4. Returns complete page with content

Output Data:

{
  success: true,
  data: {
    // Page properties (filtered)
    id: string,
    properties: { [key: string]: NotionPropertyValue },
    // Block content (hierarchical)
    blocks: NotionBlock[],
    // ... other page fields
  },
  error: null
}

When to use: Authentication flows, webhooks, redirects, HTML responses

Characteristics:

• Accept Hono Context objects
• Return HTTP Response objects directly
• Handle HTTP-specific concerns (headers, redirects, HTML)
• Cannot be easily unit tested or reused

Input Data:

// HTTP Request Body (JSON)
{
  data?: { id: string },
  id?: string,
  page_id?: string
}

// HTTP Headers
{
  host: string  // Used to construct glimpse URL
}

Processing:

1. Extracts page ID from multiple possible webhook payload structures
2. Extracts host header to construct glimpse URL
3. Calls updatePageUrl(pageId, glimpseUrl) service
4. Returns HTTP JSON response with operation status

Output Data:

// HTTP Response (JSON)
{
  success: true,
  message: "Page URL updated successfully",
  pageId: string,
  url: string,  // The constructed glimpse URL
  timestamp: string
}

Input Data:

// From Auth Middleware Context
userEmail: string

// From Environment Variables
GLANCE_DEMOS_DB_ID: string

Processing:

1. Extracts user email from authentication context
2. Queries user database using findUserByEmail(databaseId, email)
3. If user not found, creates new record with createUserRecord(databaseId, email)
4. If user found, extracts URL from various property types
5. Validates URL format and redirects

Output Data:

• Success: HTTP redirect to user's personalized URL
• New User: HTTP redirect to /glimpse/thanks
• Error: HTML error page or JSON error response

User Record Data Structure:

// Expected in Notion database
{
  Email: {
    type: "email",
    email: string
  },
  URL?: {
    type: "url",
    url: string
  } | {
    type: "rich_text",
    rich_text: [{ plain_text: string }]
  }
}

Input Data:

// From Auth Middleware Context
userEmail: string

Processing:

1. Validates user is authenticated
2. Generates welcome HTML page with user email
3. Provides next steps and expectations

Output Data:

• Success: HTML welcome page
• Unauthenticated: HTTP redirect to /

{
  success: false,
  error: "User-friendly error message",
  details: "Technical error details from service",
  data: null
}

• User-facing errors: HTML error pages with styling
• Technical errors: JSON responses with debugging information
• Authentication errors: Redirects to login pages

• Remove sensitive properties (button types) from Notion responses
• Transform external API formats to application models

• Automatic user creation for new email addresses
• Multi-property URL extraction with fallback logic
• URL validation and format checking

• Flexible payload parsing for different webhook formats
• Dynamic URL construction based on request context
• Comprehensive error logging and debugging

• Database ID management from environment variables
• API key handling (delegated to services)
• Feature flag and configuration management