Initial commit

docs/interfaces.md

@@ -0,0 +1,428 @@
+# 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