INTERFACES.md

Interfaces (suggested)

This document describes what an implementation should expose, not how.

Any implementation can choose REST, gRPC, CLI, library methods, etc. But it should provide equivalent capabilities.

Minimal operations

Account operations

• add_account(session_cookies, proxy_config?) -> account_id
• validate_account(account_id) -> { valid: bool, reason? }
• update_account(account_id, session_cookies?, proxy_config?)

Sync operations

• sync_full(account_id) -> SyncResult
• sync_incremental(account_id) -> SyncResult
• get_sync_status(account_id) -> { last_success_at?, last_error?, checkpoint? }

Message operations

• list_conversations(account_id, pagination?) -> Conversation[]
• list_messages(account_id, conversation_id, pagination?) -> Message[]
• send_message(account_id, to: user|conversation, text, idempotency_key?) -> SendResult

Event stream (optional but recommended)

Implementations may emit events such as:

• sync.started, sync.progress, sync.finished
• message.upserted
• conversation.upserted
• send.started, send.succeeded, send.failed