added AGENTS.md and docs for BalanceServer

BalanceServer/docs/API.md

@@ -0,0 +1,151 @@
+# HTTP API
+
+## Общие правила
+
+API предназначен для iOS/macOS/watchOS и Android Balance.
+
+Базовый URL задаётся клиентом и зависит от deployment environment.
+
+JSON:
+
+```http
+Content-Type: application/json
+```
+
+Защищённые endpoints используют:
+
+```http
+Authorization: Bearer <access-token>
+```
+
+## Authentication
+
+Основные операции:
+
+```text
+POST /v1/auth/register
+POST /v1/auth/login
+POST /v1/auth/logout
+POST /v1/auth/refresh
+```
+
+### Register
+
+Создаёт пользовательский аккаунт.
+
+Input должен валидироваться сервером. Password никогда не хранится plaintext.
+
+### Login
+
+Проверяет credentials и создаёт authenticated session.
+
+### Refresh
+
+Принимает refresh credential и выдаёт новый access credential согласно текущей server-side session policy.
+
+### Logout
+
+Инвалидирует текущую session/refresh state согласно текущей реализации.
+
+## Synchronization
+
+Основной endpoint:
+
+```text
+POST /v1/sync
+```
+
+Логический request:
+
+```json
+{
+  "cursor": 123,
+  "deviceId": "UUID",
+  "changes": [],
+  "pull": true
+}
+```
+
+Точная JSON schema должна оставаться совместимой с `ServerSync.swift` и Android `SyncRepository`.
+
+## Change
+
+Логическая форма:
+
+```json
+{
+  "entity": "transaction",
+  "id": "UUID",
+  "deleted": false,
+  "updatedAt": "2026-09-08T10:00:00Z",
+  "payload": {}
+}
+```
+
+Поддерживаемые entity:
+
+```text
+transaction
+category
+budget
+```
+
+## Push
+
+Client отправляет локальные изменения.
+
+Server должен:
+1. аутентифицировать пользователя;
+2. проверить ownership/ID;
+3. валидировать payload;
+4. применить изменения;
+5. создать server change entries;
+6. вернуть результат и актуальную sync metadata.
+
+Операция должна быть безопасна при retry.
+
+## Pull
+
+Client передаёт cursor.
+
+Server возвращает изменения после этого cursor, включая deletions.
+
+Если существует pagination, ответ должен содержать понятный признак продолжения и новый cursor/sequence.
+
+## Ошибки
+
+Рекомендуемый контракт:
+
+```json
+{
+  "error": {
+    "code": "invalid_request",
+    "message": "Human-readable safe message"
+  }
+}
+```
+
+Не возвращать:
+- SQL error;
+- stack trace;
+- password/token;
+- filesystem paths;
+- внутренние identifiers инфраструктуры.
+
+## HTTP status semantics
+
+Рекомендуемая семантика:
+
+```text
+200 OK     — успешный request
+201 Created — создание ресурса
+400 Bad Request — malformed/invalid input
+401 Unauthorized — missing/expired auth
+403 Forbidden — resource belongs to another user
+404 Not Found — resource/endpoint unavailable
+409 Conflict — semantic conflict, если endpoint использует такую семантику
+429 Too Many Requests — rate limit
+500 Internal Server Error — internal failure
+```
+
+Конкретные status codes текущей реализации имеют приоритет над этой общей рекомендацией.