From 95f1337fd4f33550586a0cbd87214c23f1a808b7 Mon Sep 17 00:00:00 2001
From: embeddevio <embeddev.iot@gmail.com>
Date: Thu, 22 Oct 2026 00:23:16 +0300
Subject: [PATCH] =?UTF-8?q?chore(ui):=20=D1=81=D0=BA=D1=80=D0=B8=D0=BF?=
 =?UTF-8?q?=D1=82=20=D0=B3=D0=B5=D0=BD=D0=B5=D1=80=D0=B0=D1=86=D0=B8=D0=B8?=
 =?UTF-8?q?=20TS-=D0=BA=D0=BB=D0=B8=D0=B5=D0=BD=D1=82=D0=B0=20=D0=B8=D0=B7?=
 =?UTF-8?q?=20OpenAPI=20(Refs=20#19)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ui/scripts/generate-api.sh: openapi-typescript@7 над docs/openapi.yaml.
- ui/src/api/generated/README.md: правила перегенерации и семантика writeOnly-секретов.
---
 ui/scripts/generate-api.sh     | 20 ++++++++++++++++++++
 ui/src/api/generated/README.md | 27 +++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 ui/scripts/generate-api.sh
 create mode 100644 ui/src/api/generated/README.md

diff --git a/ui/scripts/generate-api.sh b/ui/scripts/generate-api.sh
new file mode 100644
index 0000000..7ffd2b6
--- /dev/null
+++ b/ui/scripts/generate-api.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Генерация TypeScript-типов клиента из контракта (docs/openapi.yaml, issue #19).
+#
+# Требуется Node.js >= 20 (генератор запускается через npx, версия запинена).
+# Результат коммитится в ui/src/api/generated/schema.d.ts и проверяется в CI.
+set -euo pipefail
+
+root_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+spec="${root_dir}/docs/openapi.yaml"
+out_dir="${root_dir}/ui/src/api/generated"
+generator="openapi-typescript@7"
+
+if [[ ! -f "${spec}" ]]; then
+  echo "contract not found: ${spec}" >&2
+  exit 1
+fi
+
+mkdir -p "${out_dir}"
+npx --yes "${generator}" "${spec}" -o "${out_dir}/schema.d.ts"
+echo "OK: ${out_dir}/schema.d.ts <- ${spec}"
diff --git a/ui/src/api/generated/README.md b/ui/src/api/generated/README.md
new file mode 100644
index 0000000..f16f70b
--- /dev/null
+++ b/ui/src/api/generated/README.md
@@ -0,0 +1,27 @@
+# ui/src/api/generated — сгенерированный API-клиент
+
+**Файлы в этой папке не редактируются руками.**
+
+| Файл | Источник |
+|---|---|
+| `schema.d.ts` | `docs/openapi.yaml` (контракт API v1, issue #19) через `openapi-typescript@7` |
+
+## Перегенерация
+
+```bash
+bash ui/scripts/generate-api.sh
+```
+
+Требуется Node.js >= 20. CI-джоба `ts-client-is-current` повторяет генерацию и падает,
+если закоммиченный файл расходится со спецификацией.
+
+## Секреты
+
+Поля `private_key` (TunnelConfig), `preshared_key` (PeerConfig) и `password`
+(AuthLoginRequest) помечены в контракте `writeOnly`:
+
+* их **можно** передавать в запросах (`PUT /api/v1/config`, `POST /api/v1/auth/login`);
+* их **нельзя** ожидать в ответах — сервер обязан их вырезать (см. контрактный тест
+  `backend/tests/test_contract_responses.py::test_responses_contain_no_secret_material`).
+
+Поэтому UI читает секреты только из полей ввода и никогда не рендерит их из ответов API.