init: surfaces-bot — Telegram & Matrix prototype

- Surface Protocol: unified IncomingMessage/OutgoingUI/ChatContext - Telegram: Forum Topics (group + topics per chat) - Matrix: Space + rooms per chat - MockPlatformClient with PlatformClient Protocol - docs: surface-protocol, telegram/matrix specs, api-contract, claude-code-guide - project scaffold: src/, tests/, pyproject.toml Co-Authored-By: Claude Sonnet 4-6 <noreply@anthropic.com>
2026-03-27 00:35:42 +03:00 · 2026-03-27 00:35:42 +03:00 · b6df29bd9b
commit b6df29bd9b
29 changed files with 2504 additions and 0 deletions
--- a/docs/api-contract.md
+++ b/docs/api-contract.md
@ -0,0 +1,150 @@
+# API Contract — Lambda Platform
+
+> **Статус:** ЧЕРНОВИК — проектируем сами, не ждём SDK
+> **Автор:** @architect
+> **Последнее обновление:** заполнить дату
+
+Это описание того, что нам нужно от платформы.
+`MockPlatformClient` реализует этот контракт. При подключении реального SDK — только он меняется.
+
+---
+
+## Base URL
+
+```
+https://api.lambda-platform.io/v1
+```
+
+## Аутентификация
+
+```
+Authorization: Bearer {SERVICE_TOKEN}
+```
+
+Сервисный токен выдаётся команде поверхностей. Не путать с токеном пользователя.
+
+---
+
+## Users
+
+### GET /users/{external_id}?platform={platform}
+Получает или создаёт пользователя.
+
+**Query params:**
+- `platform` — `telegram` | `matrix`
+
+**Response 200:**
+```json
+{
+  "user_id": "usr_abc123",
+  "external_id": "12345678",
+  "platform": "telegram",
+  "display_name": "Иван Иванов",
+  "created_at": "2025-01-15T10:30:00Z",
+  "is_new": false
+}
+```
+
+---
+
+## Sessions
+
+### POST /sessions
+Создаёт новую сессию с AI-агентом.
+
+**Request:**
+```json
+{
+  "user_id": "usr_abc123",
+  "platform": "telegram",
+  "context": {}
+}
+```
+
+**Response 201:**
+```json
+{
+  "session_id": "ses_xyz789",
+  "agent_id": "agt_def456",
+  "created_at": "2025-01-15T10:30:00Z",
+  "expires_at": "2025-01-16T10:30:00Z"
+}
+```
+
+### GET /sessions/{session_id}
+Получает информацию о сессии.
+
+**Response 200:** — см. структуру выше + поле `status: "active" | "closed"`
+**Response 404:** `{"error": "SESSION_NOT_FOUND", "message": "..."}`
+
+### DELETE /sessions/{session_id}
+Завершает сессию.
+
+**Response 200:**
+```json
+{"closed": true}
+```
+
+---
+
+## Messages
+
+### POST /sessions/{session_id}/messages
+Отправляет сообщение и получает ответ агента.
+
+**Request:**
+```json
+{
+  "text": "Привет, что ты умеешь?",
+  "attachments": []
+}
+```
+
+**Response 200:**
+```json
+{
+  "message_id": "msg_qwe012",
+  "response": "Я AI-агент Lambda...",
+  "tokens_used": 142,
+  "finished": true
+}
+```
+
+### GET /sessions/{session_id}/messages?limit=20&offset=0
+История сообщений сессии.
+
+**Response 200:**
+```json
+[
+  {
+    "message_id": "msg_qwe012",
+    "user_text": "Привет",
+    "response": "Привет!",
+    "tokens_used": 42,
+    "created_at": "2025-01-15T10:31:00Z"
+  }
+]
+```
+
+---
+
+## Error format
+
+Все ошибки возвращаются в едином формате:
+
+```json
+{
+  "error": "ERROR_CODE",
+  "message": "Human readable description",
+  "details": {}
+}
+```
+
+Коды ошибок: `SESSION_NOT_FOUND`, `USER_NOT_FOUND`, `RATE_LIMITED`, `PLATFORM_ERROR`
+
+---
+
+## TODO (открытые вопросы к команде платформы)
+
+- [ ] Нужна ли стриминговая передача ответа (SSE / WebSocket)?
+- [ ] Как обрабатываются вложения (изображения, файлы)?