Services

External integrations and data persistence operations.

Services are the external integration layer that:

• Handle external system interactions (APIs, databases, storage)
• Make direct calls to external services (Notion API, blob storage, etc.)
• Handle transport layer concerns (network errors, response parsing)
• Return consistent, standardized response formats
• Are focused operations with no business logic or workflow management

Services do NOT:

• Implement business logic or workflow decisions
• Orchestrate multiple service calls (controllers handle this)
• Handle environment variables or configuration (controllers manage this)
• Transform data for business purposes (controllers handle transformation)

• Notion API operations → notion/page.service.ts
• Blob storage operations → blob.service.ts
• Database operations → database.service.ts
• Email sending → email.service.ts

• Data formatting → utils/date.helpers.ts
• Validation logic → utils/validation.helpers.ts
• String manipulation → utils/string.helpers.ts
• Mathematical calculations → utils/math.helpers.ts

• Always interact with systems outside the application
• Handle network operations, API calls, storage operations
• Manage external service authentication and configuration

• No business logic, just external operations
• Deterministic for the same external system state
• No workflow management or decision-making

• Consistent success/error response formats
• Complete error context from external systems
• Raw data from external APIs (no business filtering)

• Each service handles one external system or related operations
• Single responsibility for external integration concerns

All service functions return:

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

• index.ts - Main entry point with client configuration
• database.service.ts - Database queries and operations
• page.service.ts - Page retrieval and updates

• Generic blob storage operations
• Type-specific convenience functions
• Key management and cleanup operations

• email.service.ts - Email sending operations
• cache.service.ts - Caching operations
• file.service.ts - File system operations

// Controllers orchestrate services
const pageResult = await getPageById(pageId);
if (!pageResult.success) {
  return { success: false, error: pageResult.error };
}

const blobResult = await setAgentBlob(pageId, agentData);
// Controller handles business logic based on service results

// Services focus on external operations only
export async function getPageById(pageId: string): Promise<NotionServiceResponse> {
  try {
    const response = await notion.pages.retrieve({ page_id: pageId });
    return createSuccessResponse(response);
  } catch (error) {
    return createErrorResponse(error.message);
  }
}

• setBlobData(key, data) - Generic blob storage
• getBlobData(key) - Generic blob retrieval
• deleteBlobData(key) - Generic blob deletion
• listBlobKeys(prefix) - List blobs with optional prefix

• setAgentBlob(pageId, agentData) - Agent blob operations
• getAgentBlob(pageId) - Agent blob retrieval
• setViewingBlob(pageId, viewingData) - Viewing blob operations
• getViewingBlob(pageId) - Viewing blob retrieval

• generateBlobKey(type, id) - Standardized key patterns
• parseBlobKey(key) - Extract type and id from keys
• cleanupStaleBlobs(type, maxAge) - Generic cleanup operations

• getDatabases() - List all accessible databases
• getDatabaseById(databaseId) - Get database schema
• getDatabasePages(databaseId) - Query all pages in database
• findUserByEmail(databaseId, email) - Find user by email
• createUserRecord(databaseId, email) - Create new user record
• findAgentsByPersonId(databaseId, personId) - Find agents by person

• getPageById(pageId) - Get complete page data
• updatePageUrl(pageId, url) - Update page URL property
• updatePageProperty(pageId, properties) - Update page properties
• updateGlimpseAgentsProperty(pageId, agents) - Update agent relations
• clearGlimpseDemosProperty(agentId) - Clear demo relations
• getPageBlocks(pageId) - Get page content blocks
• getPageWithBlocks(pageId) - Get page with content

Services return detailed error information:

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

Common error scenarios:

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