docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/sdk/ts.md
новий файл +71
−0
1
+
# TypeScript SDK
2
+
3
+
:::block class="floatinginfobox"
4
+
| | |
5
+
| --- | --- |
6
+
| **Пакет** | `@ufotech/rpc-ts-sdk` (npm) |
7
+
| **Версія** | 1.0.4 |
8
+
| **Залежності** | немає; Node.js 18+ (вбудований `fetch`) |
9
+
| **Код** | [GitHub](https://github.com/UFO-Tech/rpc-ts-sdk) |
10
+
:::
11
+
12
+
Генератор TypeScript-інтерфейсів зі схем документа OpenRPC. Для сервера на [JsonRpcBundle](/docs/api/json-rpc-bundle) це DTO й enum з `components.schemas` відповіді `GET /rpc` — типи, які фронтенд отримує й надсилає.
13
+
14
+
:::info
15
+
Пакет генерує **лише типи даних**, а не клієнт з методами: запити надсилайте будь-яким HTTP-клієнтом, а згенеровані інтерфейси використовуйте для параметрів і результатів.
16
+
:::
17
+
18
+
## Встановлення
19
+
20
+
```bash
21
+
npm install -g @ufotech/rpc-ts-sdk # або локально: npm install -D @ufotech/rpc-ts-sdk
22
+
```
23
+
24
+
## Генерація з консолі
25
+
26
+
```bash
27
+
rpc-ts-sdk-gen -i https://api.example.com/rpc -o ./src/api/schemas.ts
28
+
rpc-ts-sdk-gen -i ./openrpc.json -o ./src/api/schemas.ts
29
+
```
30
+
31
+
| Опція | За замовчуванням | Опис |
32
+
| --- | --- | --- |
33
+
| `-i`, `--input` | `openrpc.json` у поточному каталозі | Шлях або URL документа OpenRPC |
34
+
| `-o`, `--out` | `schemas.ts` у поточному каталозі | Файл з інтерфейсами |
35
+
36
+
## Генерація з коду
37
+
38
+
```ts
39
+
import { generateSchemas } from '@ufotech/rpc-ts-sdk/generate-schemas';
40
+
41
+
await generateSchemas({
42
+
input: 'https://api.example.com/rpc',
43
+
output: './src/api/schemas.ts',
44
+
});
45
+
```
46
+
47
+
:::warning
48
+
README пакета показує імпорт з `@ufo-tech/rpc-ts-sdk`, але пакет опубліковано як `@ufotech/rpc-ts-sdk`, а в `exports` є лише шлях `./generate-schemas`. Імпортуйте саме `@ufotech/rpc-ts-sdk/generate-schemas`.
49
+
:::
50
+
51
+
## Що генерується
52
+
53
+
* інтерфейс для кожної схеми з `components.schemas`;
54
+
* `enum` → union-типи значень, `oneOf` / `anyOf` → union-типи, масиви, вкладені об'єкти, `$ref`, nullable-поля;
55
+
* базовий інтерфейс помилки:
56
+
57
+
```ts
58
+
export interface RpcError {
59
+
code: number;
60
+
message: string;
61
+
data?: any;
62
+
}
63
+
```
64
+
65
+
Якщо в документі немає `components.schemas`, генерація завершується помилкою `No components.schemas found!`.
66
+
67
+
## Поради
68
+
69
+
* Генеруйте типи на етапі збирання фронтенду — так вони завжди відповідають актуальній документації сервера.
70
+
* Для різних [версій](/docs/api/json-rpc-bundle/functionality/versions) чи [груп](/docs/api/json-rpc-bundle/functionality/groups) API генеруйте окремі файли з відповідних адрес (`/rpc/v2`, `/rpc/internal`).
71
+
* Захищену `protected_doc` документацію генератор отримати не може (запит без заголовків) — збережіть документ у файл і генеруйте з нього.