mail_manager/docs/interfaces.md

Mail Manager - Interface Relationships

This document visualizes all the interfaces in the mail_manager module and their relationships.

Overview

The mail manager uses a hierarchical structure where interfaces are organized by their domain responsibilities:

• Common Types: Base types and selectors
• Providers: Mail service providers (Gmail, IMAP, etc.)
• Services: Individual mail accounts/services
• Collections: Mailboxes and folders
• Messages: Email messages and their parts

---

Complete Interface Diagram

classDiagram
    %% Common/Base Types
    class SourceSelector {
        +string provider
        +string service
        +string collection
        +string message
    }
    
    class ApiRequest~T~ {
        +T data
    }
    
    class ApiResponse~T~ {
        +T data
        +Error error
    }
    
    class ListRange {
        +number offset
        +number limit
    }

    %% Provider Interfaces
    class ProviderInterface {
        +string @type
        +string identifier
        +string label
        +ProviderCapabilitiesInterface capabilities
    }
    
    class ProviderCapabilitiesInterface {
        +boolean ServiceList
        +boolean ServiceFetch
        +boolean ServiceExtant
        +boolean ServiceCreate
        +boolean ServiceModify
        +boolean ServiceDestroy
        +boolean ServiceDiscover
        +boolean ServiceTest
    }
    
    class ProviderListRequest {
        +SourceSelector sources
    }
    
    class ProviderListResponse {
        +ProviderInterface[identifier] providers
    }
    
    class ProviderFetchRequest {
        +string identifier
    }
    
    class ProviderFetchResponse {
        <<extends ProviderInterface>>
    }
    
    class ProviderExtantRequest {
        +SourceSelector sources
    }
    
    class ProviderExtantResponse {
        +boolean[identifier] exists
    }

    %% Service Interfaces
    class ServiceInterface {
        +string @type
        +string identifier
        +string provider
        +string label
        +ServiceCapabilitiesInterface capabilities
        +object configuration
    }
    
    class ServiceCapabilitiesInterface {
        +boolean CollectionList
        +boolean CollectionFetch
        +boolean CollectionExtant
        +boolean CollectionCreate
        +boolean CollectionModify
        +boolean CollectionDestroy
    }
    
    class ServiceListRequest {
        +SourceSelector sources
        +ListRange range
    }
    
    class ServiceListResponse {
        +ServiceInterface[identifier] services
    }
    
    class ServiceFetchRequest {
        +string provider
        +string identifier
    }
    
    class ServiceFetchResponse {
        <<extends ServiceInterface>>
    }
    
    class ServiceExtantRequest {
        +SourceSelector sources
    }
    
    class ServiceExtantResponse {
        +boolean[identifier] exists
    }
    
    class ServiceCreateRequest {
        +string provider
        +string label
        +object configuration
    }
    
    class ServiceCreateResponse {
        <<extends ServiceInterface>>
    }
    
    class ServiceModifyRequest {
        +string provider
        +string identifier
        +string label
        +object configuration
    }
    
    class ServiceModifyResponse {
        <<extends ServiceInterface>>
    }
    
    class ServiceDestroyRequest {
        +string provider
        +string identifier
    }
    
    class ServiceDestroyResponse {
        +boolean success
    }

    %% Collection Interfaces
    class CollectionInterface {
        +string @type
        +string identifier
        +string service
        +string provider
        +string label
        +CollectionCapabilitiesInterface capabilities
        +string[] flags
        +number messageCount
    }
    
    class CollectionCapabilitiesInterface {
        +boolean MessageList
        +boolean MessageFetch
        +boolean MessageExtant
        +boolean MessageCreate
        +boolean MessageModify
        +boolean MessageDestroy
    }
    
    class CollectionListRequest {
        +SourceSelector sources
        +ListRange range
    }
    
    class CollectionListResponse {
        +CollectionInterface[identifier] collections
    }
    
    class CollectionFetchRequest {
        +string provider
        +string service
        +string identifier
    }
    
    class CollectionFetchResponse {
        <<extends CollectionInterface>>
    }

    %% Message Interfaces
    class MessageInterface {
        +string @type
        +string identifier
        +string collection
        +string service
        +string provider
        +string[] flags
        +Date receivedDate
        +Date internalDate
        +MessageHeadersInterface headers
        +MessagePartInterface[] parts
    }
    
    class MessageHeadersInterface {
        +string from
        +string[] to
        +string[] cc
        +string[] bcc
        +string subject
        +string messageId
        +string[] references
        +string inReplyTo
        +Date date
    }
    
    class MessagePartInterface {
        +string partId
        +string mimeType
        +string filename
        +number size
        +MessagePartInterface[] subParts
        +object headers
        +string body
    }
    
    class MessageListRequest {
        +SourceSelector sources
        +ListRange range
        +string[] flags
    }
    
    class MessageListResponse {
        +MessageInterface[identifier] messages
    }
    
    class MessageFetchRequest {
        +string provider
        +string service
        +string collection
        +string identifier
    }
    
    class MessageFetchResponse {
        <<extends MessageInterface>>
    }

    %% Relationships
    ProviderInterface --> ProviderCapabilitiesInterface
    ProviderFetchResponse --|> ProviderInterface
    ProviderListResponse --> ProviderInterface
    
    ServiceInterface --> ServiceCapabilitiesInterface
    ServiceFetchResponse --|> ServiceInterface
    ServiceCreateResponse --|> ServiceInterface
    ServiceModifyResponse --|> ServiceInterface
    ServiceListResponse --> ServiceInterface
    
    CollectionInterface --> CollectionCapabilitiesInterface
    CollectionFetchResponse --|> CollectionInterface
    CollectionListResponse --> CollectionInterface
    
    MessageInterface --> MessageHeadersInterface
    MessageInterface --> MessagePartInterface
    MessagePartInterface --> MessagePartInterface : subParts
    MessageFetchResponse --|> MessageInterface
    MessageListResponse --> MessageInterface
    
    %% Selector Usage
    ProviderListRequest --> SourceSelector
    ProviderExtantRequest --> SourceSelector
    ServiceListRequest --> SourceSelector
    ServiceExtantRequest --> SourceSelector
    CollectionListRequest --> SourceSelector
    MessageListRequest --> SourceSelector

---

Hierarchical Structure

graph TD
    A[SourceSelector] --> B[Provider Level]
    B --> C[Service Level]
    C --> D[Collection Level]
    D --> E[Message Level]
    
    B --> B1[ProviderInterface]
    B --> B2[ProviderCapabilities]
    
    C --> C1[ServiceInterface]
    C --> C2[ServiceCapabilities]
    
    D --> D1[CollectionInterface]
    D --> D2[CollectionCapabilities]
    
    E --> E1[MessageInterface]
    E --> E2[MessageHeaders]
    E --> E3[MessagePart]

---

Request/Response Pattern

All operations follow a consistent request/response pattern:

sequenceDiagram
    participant Client
    participant API
    participant Provider
    
    Client->>API: {Operation}Request
    API->>Provider: Process Request
    Provider->>API: Data
    API->>Client: {Operation}Response

Operations by Level:

Provider Level:

• List, Fetch, Extant

Service Level:

• List, Fetch, Extant, Create, Modify, Destroy

Collection Level:

• List, Fetch, Extant, Create, Modify, Destroy

Message Level:

• List, Fetch, Extant, Create, Modify, Destroy

---

Capability Inheritance

graph LR
    A[ProviderCapabilities] -->|enables| B[ServiceCapabilities]
    B -->|enables| C[CollectionCapabilities]
    C -->|enables| D[Message Operations]

Capabilities cascade down the hierarchy - if a provider doesn't support ServiceList, then no services can be listed for that provider.

---

Key Patterns

1. Extends Pattern

Response interfaces extend their base interface:

• ProviderFetchResponse extends ProviderInterface
• ServiceFetchResponse extends ServiceInterface

2. Dictionary Pattern

List responses use identifier as key:

{
  [identifier: string]: Interface
}

3. SourceSelector Pattern

Resources are selected hierarchically:

{
  provider: "gmail",
  service: "user@example.com",
  collection: "INBOX",
  message: "msg123"
}

4. Recursive Structure

MessagePart can contain subParts:

MessagePartInterface {
  subParts?: MessagePartInterface[]
}

---

Usage Examples

Selecting a specific message:

const selector: SourceSelector = {
  provider: "gmail",
  service: "user@example.com",
  collection: "INBOX",
  message: "12345"
};

Listing all services for a provider:

const request: ServiceListRequest = {
  sources: {
    provider: "gmail"
  },
  range: {
    offset: 0,
    limit: 50
  }
};

---

Interface Files

• common.ts - Base types and selectors
• provider.ts - Provider-level interfaces
• service.ts - Service-level interfaces
• collection.ts - Collection-level interfaces
• message.ts - Message-level interfaces