Services

External API integrations (pure API calls only).

Services are the data access layer that:

• Make direct API calls to external systems (Notion, databases, etc.)
• Handle HTTP transport layer concerns (network errors, response parsing)
• Return consistent, standardized response formats
• Are pure functions with no side effects beyond the API call
• Do NOT handle business logic, environment variables, or orchestrate multiple calls

All service functions return:

{
  success: boolean,
  data?: any,           // Present on success
  error?: string,       // Present on failure  
  timestamp: string     // ISO timestamp of the operation
}

• Simple primitives: string, number, boolean only
• No complex objects: Controllers handle object extraction/validation
• No HTTP contexts: Services are transport-agnostic

• Raw API responses: Unmodified data from external APIs
• No business logic filtering: Controllers handle data transformation
• Complete error context: Full error messages from external systems

• Input: None
• Output: Raw Notion search response with all accessible databases
• Data Structure:

  {
    success: true,
    data: {
      results: NotionDatabase[],
      next_cursor: string | null,
      has_more: boolean
    },
    timestamp: string
  }

• Input: Database UUID string
• Output: Complete Notion database object with schema
• Data Structure:

  {
    success: true,
    data: {
      id: string,
      title: RichText[],
      properties: { [key: string]: PropertySchema },
      // ... full Notion database object
    },
    timestamp: string
  }

• Input: Database UUID string
• Output: All pages in the database with properties
• Data Structure:

  {
    success: true,
    data: {
      results: NotionPage[],
      next_cursor: string | null,
      has_more: boolean
    },
    timestamp: string
  }

• Input: Page UUID string
• Output: Complete Notion page object with properties
• Data Structure:

  {
    success: true,
    data: {
      id: string,
      properties: { [key: string]: PropertyValue },
      parent: { database_id: string } | { page_id: string },
      // ... full Notion page object
    },
    timestamp: string
  }

• Input: Page UUID string
• Output: Hierarchical block structure with recursive children
• Data Structure:

  {
    success: true,
    data: {
      results: NotionBlock[] // Each block may have .children array
    },
    timestamp: string
  }

• Input: Page UUID string
• Output: Combined page properties and block content
• Data Structure:

  {
    success: true,
    data: {
      // All page properties
      id: string,
      properties: { [key: string]: PropertyValue },
      // Plus blocks array
      blocks: NotionBlock[]
    },
    timestamp: string
  }

• Input: Page UUID and URL string
• Output: Updated page object
• Behavior: Updates the "URL" property specifically
• Data Structure: Same as getPageById response

• Input: Database UUID and email address string
• Output: Query results for pages matching email
• Data Structure:

  {
    success: true,
    data: {
      results: NotionPage[], // Pages with Email property matching
      next_cursor: string | null,
      has_more: boolean
    },
    timestamp: string
  }

• Input: Database UUID and email address string
• Output: Newly created page object
• Behavior: Creates page with "Email" property set
• Data Structure: Same as getPageById response

Services return detailed error information:

{
  success: false,
  error: "Notion API error message", // Direct from external API
  timestamp: string
}

Common error scenarios:

• Network failures: Connection timeouts, DNS issues
• Authentication: Invalid API keys, expired tokens
• Authorization: Insufficient permissions for resources
• Validation: Invalid UUIDs, missing required fields
• Rate limiting: API quota exceeded