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

```mermaid
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

```mermaid
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:

```mermaid
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

```mermaid
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:
```typescript
{
  [identifier: string]: Interface
}
```

### 3. **SourceSelector Pattern**
Resources are selected hierarchically:
```typescript
{
  provider: "gmail",
  service: "user@example.com",
  collection: "INBOX",
  message: "msg123"
}
```

### 4. **Recursive Structure**
MessagePart can contain subParts:
```typescript
MessagePartInterface {
  subParts?: MessagePartInterface[]
}
```

---

## Usage Examples

### Selecting a specific message:
```typescript
const selector: SourceSelector = {
  provider: "gmail",
  service: "user@example.com",
  collection: "INBOX",
  message: "12345"
};
```

### Listing all services for a provider:
```typescript
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