typizer 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +60 -0
- package/README.md +273 -134
- package/dist/client.d.ts +323 -0
- package/dist/client.js +629 -0
- package/dist/core.d.ts +109 -0
- package/dist/core.js +339 -0
- package/dist/errors.d.ts +146 -0
- package/dist/errors.js +281 -0
- package/dist/files.d.ts +42 -0
- package/dist/files.js +159 -0
- package/dist/gen/index.d.ts +2 -2
- package/dist/gen/index.js +1 -1
- package/dist/gen/sdk.gen.d.ts +329 -5
- package/dist/gen/sdk.gen.js +588 -4
- package/dist/gen/types.gen.d.ts +2490 -245
- package/dist/index.d.ts +26 -3
- package/dist/index.js +33 -4
- package/dist/pagination.d.ts +30 -0
- package/dist/pagination.js +49 -0
- package/dist/run.d.ts +48 -0
- package/dist/run.js +45 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/dist/webhooks.d.ts +40 -0
- package/dist/webhooks.js +208 -0
- package/package.json +9 -7
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Изменения
|
|
2
|
+
|
|
3
|
+
Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), версии — [SemVer](https://semver.org/lang/ru/).
|
|
4
|
+
|
|
5
|
+
## [0.2.0] — 2026-11-14
|
|
6
|
+
|
|
7
|
+
Версия без поломок: всё из 0.1.0 работает как раньше, новый клиент добавлен рядом.
|
|
8
|
+
|
|
9
|
+
### Добавлено
|
|
10
|
+
|
|
11
|
+
- Клиент `Typizer` (`import Typizer from 'typizer'` или `import { Typizer } from 'typizer'`) по
|
|
12
|
+
единой спецификации SDK Typizer: ключ из `TYPIZER_API_KEY`, адрес по умолчанию
|
|
13
|
+
`https://api.typizer.ru`, таймаут попытки 75 с, `withOptions()`.
|
|
14
|
+
- `client.extract({ file, schema | catalog | typizer })` — документ и схема → данные одним вызовом:
|
|
15
|
+
локальный файл (путь, `Blob`/`File`, `Uint8Array`, `ReadableStream`) уходит в том же запросе
|
|
16
|
+
(`multipart/form-data`), SDK ждёт результат (серверное ожидание до 60 с, затем опрос, всего до
|
|
17
|
+
5 минут) и бросает `RunFailedError`/`WaitTimeoutError`.
|
|
18
|
+
- Ресурсы `client.runs` (`create`, `get`, `wait`, `list`, `output`, `retry`), `client.files`,
|
|
19
|
+
`client.typizers` (`versions`, `catalogUpdate`, `generate`, `xsd`), `client.catalog`,
|
|
20
|
+
`client.batches`, `client.webhookEndpoints` (`deliveries`, `test`); `client.me()`,
|
|
21
|
+
`client.balance()`, `client.usage()`, `client.organization()`, `client.status()`.
|
|
22
|
+
- Типизированные ошибки: `TypizerError` → `APIError` (`BadRequestError`, `AuthenticationError`,
|
|
23
|
+
`InsufficientBalanceError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`,
|
|
24
|
+
`IdempotencyConflictError`, `FileTooLargeError`, `UnsupportedFileTypeError`,
|
|
25
|
+
`UnprocessableDocumentError`, `RateLimitError`, `InternalServerError`,
|
|
26
|
+
`ServiceUnavailableError`), `APIConnectionError`/`APITimeoutError`, `RunFailedError`,
|
|
27
|
+
`WaitTimeoutError`, `WebhookVerificationError`, `ConfigurationError`.
|
|
28
|
+
- Автоматические повторы (сеть, таймаут, 408, 429, 500, 502–504) с `Retry-After` и экспоненциальной
|
|
29
|
+
паузой; `Idempotency-Key` на каждом `POST`, один на все повторы вызова.
|
|
30
|
+
- `.withResponse()` у каждого метода: `Response`, `requestId`, `idempotentReplayed`.
|
|
31
|
+
- Автопагинация: `for await (const run of client.runs.list())`, `Page` с `nextPage()`.
|
|
32
|
+
- Проверка подписи вебхуков без зависимостей: `verifyWebhook`, `isValidWebhook`,
|
|
33
|
+
`Typizer.webhooks.verify`; помощники прогона `run.needsReview`, `run.fieldsToReview()`,
|
|
34
|
+
`run.isTerminal`.
|
|
35
|
+
- Отмена через `AbortSignal`, опции `proxy` (с пакетом `undici`), `fetch`, `defaultHeaders`,
|
|
36
|
+
`appInfo`, логи (`logger`, `logLevel`, `TYPIZER_LOG`); ключ API в логах и строковых представлениях
|
|
37
|
+
маскируется.
|
|
38
|
+
- `VERSION`; заголовок `User-Agent: typizer-ts/<версия> (node/<версия>; <ОС>/<архитектура>)`.
|
|
39
|
+
|
|
40
|
+
### Исправлено
|
|
41
|
+
|
|
42
|
+
- `createTypizerClient` больше не ждёт ответа бесконечно: таймаут 75 с по умолчанию (опция
|
|
43
|
+
`timeout`, `0` — без таймаута) и заголовок `User-Agent: typizer-ts/<версия>`.
|
|
44
|
+
|
|
45
|
+
### Устарело
|
|
46
|
+
|
|
47
|
+
- Функции внутренних операций Кабинета (`startLogin`, `createCheckout`, `createApiKey`,
|
|
48
|
+
`createAgentThread`, `createDemoRun`, `deleteMe` и другие — всего 45, с ключом API они не работают)
|
|
49
|
+
помечены `@deprecated` и будут удалены в 1.0.0, вместе с переходом низкоуровневого слоя на
|
|
50
|
+
публичное описание API.
|
|
51
|
+
|
|
52
|
+
## [0.1.0] — 2026-11-07
|
|
53
|
+
|
|
54
|
+
### Добавлено
|
|
55
|
+
|
|
56
|
+
- Первый выпуск: функции для каждой операции API, сгенерированные из OpenAPI, типы моделей и
|
|
57
|
+
`createTypizerClient({ apiKey, baseUrl?, fetch? })`.
|
|
58
|
+
|
|
59
|
+
[0.2.0]: https://www.npmjs.com/package/typizer/v/0.2.0
|
|
60
|
+
[0.1.0]: https://www.npmjs.com/package/typizer/v/0.1.0
|
package/README.md
CHANGED
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
Официальный TypeScript SDK для [Typizer](https://typizer.ru) — сервиса, который извлекает данные из
|
|
4
4
|
документов (счета, УПД, накладные, договоры, сканы и фото) в JSON по вашей схеме.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
документация — [docs.typizer.ru](https://docs.typizer.ru).
|
|
6
|
+
Один клиент `Typizer` и одна строка на главный сценарий: документ и схема → данные. Повторы,
|
|
7
|
+
ключи идемпотентности, ожидание результата, типизированные ошибки, постраничный обход списков и
|
|
8
|
+
проверка подписи вебхуков — уже внутри. Полная документация — [docs.typizer.ru](https://docs.typizer.ru).
|
|
9
9
|
|
|
10
10
|
## Установка
|
|
11
11
|
|
|
@@ -13,208 +13,347 @@ SDK сгенерирован из OpenAPI-описания Typizer API: одна
|
|
|
13
13
|
npm i typizer
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
Пакет — только ESM, с типами в
|
|
17
|
-
и других средах с глобальным `fetch`. Зависимостей нет.
|
|
16
|
+
Пакет — только ESM, с типами в комплекте. Работает в Node.js 20+, Bun и Deno; зависимостей нет.
|
|
18
17
|
|
|
19
18
|
## Ключ API
|
|
20
19
|
|
|
21
20
|
1. Зарегистрируйтесь в кабинете [my.typizer.ru](https://my.typizer.ru).
|
|
22
21
|
2. Откройте раздел «Ключи API» и создайте ключ со скоупом `runs:write` (для запуска прогонов) —
|
|
23
22
|
подробнее о скоупах в [«Ключах API»](https://docs.typizer.ru/how-to/api-keys/).
|
|
24
|
-
3. Ключ (`tz_live_…`) показывается один раз. Сохраните
|
|
23
|
+
3. Ключ (`tz_live_…`) показывается один раз. Сохраните его в переменную окружения:
|
|
25
24
|
|
|
26
25
|
```sh
|
|
27
26
|
export TYPIZER_API_KEY="tz_live_…"
|
|
28
27
|
```
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
`new Typizer()` читает ключ из `TYPIZER_API_KEY` (или `new Typizer({ apiKey })`) и сразу падает с
|
|
30
|
+
`ConfigurationError`, если ключа нет. Адрес API — `https://api.typizer.ru` (меняется опцией
|
|
31
|
+
`baseUrl` или `TYPIZER_BASE_URL`). Ключ API — секрет сервера: не используйте его в коде, который
|
|
32
|
+
выполняется в браузере. Создайте один клиент на приложение — он безопасен для параллельных вызовов.
|
|
31
33
|
|
|
32
34
|
## Быстрый старт
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
+
```ts
|
|
37
|
+
import Typizer from 'typizer';
|
|
38
|
+
|
|
39
|
+
const client = new Typizer();
|
|
40
|
+
|
|
41
|
+
const run = await client.extract({
|
|
42
|
+
file: 'invoice.pdf', // путь, Blob/File, Uint8Array или ReadableStream
|
|
43
|
+
schema: {
|
|
44
|
+
type: 'object',
|
|
45
|
+
properties: {
|
|
46
|
+
invoice_number: { type: 'string' },
|
|
47
|
+
total: { type: 'number' },
|
|
48
|
+
inn: { type: 'string', 'x-typizer-check': 'inn' },
|
|
49
|
+
},
|
|
50
|
+
required: ['invoice_number', 'total'],
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
console.log(run.output); // { invoice_number: 'А-1024', total: 3660, inn: '7707083893' }
|
|
55
|
+
|
|
56
|
+
// Поля, которые не прошли проверку (контрольная сумма ИНН, сумма строк) или не найдены:
|
|
57
|
+
if (run.needsReview) {
|
|
58
|
+
for (const field of run.fieldsToReview()) {
|
|
59
|
+
console.log(field.path, field.status, field.reason, field.sources?.[0]?.page);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`extract` отправляет файл и схему **одним** запросом (`POST /v1/extract`), ждёт результат (до
|
|
65
|
+
5 минут: сервер держит запрос до 60 секунд, дальше SDK опрашивает прогон) и возвращает прогон
|
|
66
|
+
`succeeded`. Документ по ссылке — `{ url: 'https://typizer.ru/samples/invoice.pdf' }`, уже
|
|
67
|
+
загруженный файл — `{ fileId: 'file_…' }`. Порядок свойств схемы сохраняется: по нему идут столбцы
|
|
68
|
+
CSV/XLSX и элементы XML.
|
|
69
|
+
|
|
70
|
+
Тип результата можно задать самому:
|
|
36
71
|
|
|
37
72
|
```ts
|
|
38
|
-
import {
|
|
73
|
+
import { Typizer } from 'typizer';
|
|
39
74
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
}
|
|
75
|
+
interface Invoice {
|
|
76
|
+
invoice_number: string;
|
|
77
|
+
total: number;
|
|
78
|
+
}
|
|
44
79
|
|
|
45
|
-
const
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
invoice_number: { type: 'string' },
|
|
53
|
-
total: { type: 'number' },
|
|
54
|
-
inn: { type: 'string', 'x-typizer-check': 'inn' },
|
|
55
|
-
},
|
|
56
|
-
required: ['invoice_number', 'total'],
|
|
57
|
-
},
|
|
80
|
+
const client = new Typizer();
|
|
81
|
+
const run = await client.extract<Invoice>({
|
|
82
|
+
url: 'https://typizer.ru/samples/invoice.pdf',
|
|
83
|
+
schema: {
|
|
84
|
+
type: 'object',
|
|
85
|
+
properties: { invoice_number: { type: 'string' }, total: { type: 'number' } },
|
|
86
|
+
required: ['invoice_number', 'total'],
|
|
58
87
|
},
|
|
59
|
-
|
|
60
|
-
headers: { 'Idempotency-Key': crypto.randomUUID() }, // новый ключ на каждую операцию
|
|
88
|
+
timeout: 120_000, // ждать не дольше 2 минут (по умолчанию 5)
|
|
61
89
|
});
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
console.log(run.status); // 'succeeded' | 'failed' | 'queued' | 'processing'
|
|
65
|
-
console.log(run.output); // результат в формате JSON по вашей схеме
|
|
90
|
+
console.log(run.output?.total);
|
|
66
91
|
```
|
|
67
92
|
|
|
68
|
-
|
|
69
|
-
дождитесь его через `getRun({ client, path: { id: run.id } })` или вебхук (см. ниже и
|
|
70
|
-
[«Получить результат»](https://docs.typizer.ru/how-to/get-results/)).
|
|
93
|
+
## Схема из каталога
|
|
71
94
|
|
|
72
|
-
|
|
95
|
+
Готовые схемы для типовых документов — [каталог](https://docs.typizer.ru/how-to/catalog/):
|
|
96
|
+
счёт-фактура, УПД, ТОРГ-12 и другие. Ссылка — `slug`, `slug@мажорная-версия` или
|
|
97
|
+
`издатель/slug@версия` для схем сообщества:
|
|
73
98
|
|
|
74
|
-
|
|
75
|
-
|
|
99
|
+
```ts
|
|
100
|
+
import { Typizer } from 'typizer';
|
|
101
|
+
|
|
102
|
+
const client = new Typizer();
|
|
103
|
+
|
|
104
|
+
const run = await client.extract({ file: 'invoice.pdf', catalog: 'schet-faktura@1' });
|
|
105
|
+
console.log(run.catalog?.ref, run.output);
|
|
106
|
+
|
|
107
|
+
for await (const entry of client.catalog.list({ category: 'invoices' })) {
|
|
108
|
+
console.log(entry.ref, entry.title);
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Типизатор
|
|
113
|
+
|
|
114
|
+
Схему, которой вы пользуетесь постоянно, сохраните как типизатор и запускайте по `id`:
|
|
76
115
|
|
|
77
116
|
```ts
|
|
78
|
-
import {
|
|
79
|
-
import { createFile, createRun, createTypizer, createTypizerClient } from 'typizer';
|
|
117
|
+
import { Typizer } from 'typizer';
|
|
80
118
|
|
|
81
|
-
const client =
|
|
119
|
+
const client = new Typizer();
|
|
82
120
|
|
|
83
|
-
const
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
type: '
|
|
89
|
-
|
|
90
|
-
invoice_number: { type: 'string' },
|
|
91
|
-
total: { type: 'number' },
|
|
92
|
-
},
|
|
93
|
-
required: ['invoice_number', 'total'],
|
|
121
|
+
const typizer = await client.typizers.create({
|
|
122
|
+
name: 'Счета поставщиков',
|
|
123
|
+
schema: {
|
|
124
|
+
type: 'object',
|
|
125
|
+
properties: {
|
|
126
|
+
invoice_number: { type: 'string' },
|
|
127
|
+
total: { type: 'number' },
|
|
94
128
|
},
|
|
129
|
+
required: ['invoice_number', 'total'],
|
|
95
130
|
},
|
|
96
131
|
});
|
|
97
|
-
if (typizerError) throw new Error(typizerError.detail);
|
|
98
132
|
|
|
99
|
-
const {
|
|
100
|
-
|
|
101
|
-
body: { file: await openAsBlob('invoice.pdf', { type: 'application/pdf' }) },
|
|
102
|
-
});
|
|
103
|
-
if (fileError) throw new Error(fileError.detail);
|
|
133
|
+
const run = await client.extract({ file: 'invoice.pdf', typizer: typizer.id });
|
|
134
|
+
console.log(run.output);
|
|
104
135
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
query: { wait: 60 },
|
|
110
|
-
headers: { 'Idempotency-Key': crypto.randomUUID() },
|
|
111
|
-
});
|
|
112
|
-
console.log(run?.output);
|
|
136
|
+
// Все прогоны типизатора — постранично, следующая страница запрашивается сама:
|
|
137
|
+
for await (const r of client.runs.list({ typizerId: typizer.id })) {
|
|
138
|
+
console.log(r.id, r.status);
|
|
139
|
+
}
|
|
113
140
|
```
|
|
114
141
|
|
|
115
|
-
|
|
142
|
+
Другие ресурсы клиента: `client.runs` (`create`, `get`, `wait`, `list`, `output`, `retry`),
|
|
143
|
+
`client.files`, `client.typizers` (с `versions` и `catalogUpdate`), `client.catalog`,
|
|
144
|
+
`client.batches`, `client.webhookEndpoints`, а также `client.me()`, `client.balance()`,
|
|
145
|
+
`client.usage()`, `client.status()`. Поля моделей называются как в JSON API (`run.output_expired`,
|
|
146
|
+
`run.created_at`), параметры методов — в `camelCase` (`typizerId`, `webhookUrl`).
|
|
116
147
|
|
|
117
|
-
|
|
118
|
-
[справочнике API](https://docs.typizer.ru/reference/api/): `extract`, `createRun`, `getRun`,
|
|
119
|
-
`listRuns`, `createTypizer`, `createBatch`, `getBalance`, `createWebhookEndpoint` и другие.
|
|
120
|
-
Функция принимает `{ client, path?, query?, body?, headers? }` и возвращает
|
|
121
|
-
`Promise<{ data, error, request, response }>`:
|
|
122
|
-
- `data` — разобранный ответ при успехе, `error` — тело ошибки при коде 4xx/5xx; заполнено ровно
|
|
123
|
-
одно из двух, и после проверки `if (error)` TypeScript знает, что `data` определено;
|
|
124
|
-
- `response` — исходный `Response` (статус, заголовки вроде `Retry-After` и `X-Request-Id`).
|
|
148
|
+
## Ошибки
|
|
125
149
|
|
|
126
|
-
|
|
150
|
+
Всё, что бросает SDK, — подкласс `TypizerError`. Ответ API с ошибкой — `APIError` с полями
|
|
151
|
+
`status`, `code`, `detail`, `param`, `requestId` (приложите его к обращению в поддержку),
|
|
152
|
+
`retryable` и `retryAfter`; класс выбирается по коду из [«Кодов ошибок»](https://docs.typizer.ru/reference/errors/):
|
|
127
153
|
|
|
128
154
|
```ts
|
|
129
|
-
import
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
155
|
+
import {
|
|
156
|
+
APIConnectionError,
|
|
157
|
+
APIError,
|
|
158
|
+
InsufficientBalanceError,
|
|
159
|
+
RateLimitError,
|
|
160
|
+
RunFailedError,
|
|
161
|
+
Typizer,
|
|
162
|
+
WaitTimeoutError,
|
|
163
|
+
} from 'typizer';
|
|
164
|
+
|
|
165
|
+
const client = new Typizer();
|
|
166
|
+
|
|
167
|
+
try {
|
|
168
|
+
const run = await client.extract({ file: 'invoice.pdf', catalog: 'upd' });
|
|
169
|
+
console.log(run.output);
|
|
170
|
+
} catch (err) {
|
|
171
|
+
if (err instanceof RunFailedError) {
|
|
172
|
+
console.log('документ не распознан:', err.code, err.detail); // document_unreadable, …
|
|
173
|
+
} else if (err instanceof WaitTimeoutError) {
|
|
174
|
+
// прогон продолжается и будет оплачен — дождитесь его позже
|
|
175
|
+
const run = await client.runs.wait(err.runId);
|
|
176
|
+
console.log(run.status);
|
|
177
|
+
} else if (err instanceof InsufficientBalanceError) {
|
|
178
|
+
console.log('пополните баланс в кабинете');
|
|
179
|
+
} else if (err instanceof RateLimitError) {
|
|
180
|
+
console.log(`лимит запросов, повторить через ${err.retryAfter} с`);
|
|
181
|
+
} else if (err instanceof APIError) {
|
|
182
|
+
console.log(err.message); // [code] detail (HTTP 400, request_id=req_…, https://docs.typizer.ru/errors/…)
|
|
183
|
+
} else if (err instanceof APIConnectionError) {
|
|
184
|
+
console.log('нет связи с API'); // APITimeoutError — если истёк таймаут попытки
|
|
185
|
+
} else {
|
|
186
|
+
throw err;
|
|
187
|
+
}
|
|
133
188
|
}
|
|
134
189
|
```
|
|
135
190
|
|
|
136
|
-
|
|
137
|
-
`
|
|
191
|
+
Ошибки в аргументах (нет схемы, два документа сразу, `instructions` без `schema`) — обычный
|
|
192
|
+
`TypeError` до отправки запроса.
|
|
193
|
+
|
|
194
|
+
## Повторы и идемпотентность
|
|
138
195
|
|
|
139
|
-
|
|
196
|
+
SDK сам повторяет запрос (по умолчанию до 2 раз) при сетевой ошибке и таймауте, `429`, `500`,
|
|
197
|
+
`502`–`504` и `408`: ровно через `Retry-After`, если сервер его прислал, иначе с экспоненциальной
|
|
198
|
+
паузой 0,5 → 1 → 2 → 4 → 8 с. Каждый `POST` уходит с заголовком `Idempotency-Key` — один и тот же
|
|
199
|
+
во всех повторах, поэтому повтор не создаст второй прогон и не спишет страницы дважды. Таймаут
|
|
200
|
+
одной попытки — 75 секунд.
|
|
140
201
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
- `code` — машиночитаемый код: `'invalid_request'`, `'unauthorized'`, `'insufficient_balance'`,
|
|
144
|
-
`'rate_limited'`, …;
|
|
145
|
-
- `detail` — описание конкретного случая, `param` — поле запроса, если виновато оно;
|
|
146
|
-
- `doc_url` — страница этого кода: `https://docs.typizer.ru/errors/<code>/`;
|
|
147
|
-
- `request_id` — приложите его к обращению в поддержку (support@typizer.ru).
|
|
202
|
+
Если одна и та же операция может повториться между процессами (тот же счёт из той же очереди),
|
|
203
|
+
передайте свой ключ — сервер вернёт сохранённый ответ вместо нового прогона:
|
|
148
204
|
|
|
149
205
|
```ts
|
|
150
|
-
import {
|
|
206
|
+
import { Typizer } from 'typizer';
|
|
207
|
+
|
|
208
|
+
const client = new Typizer({ maxRetries: 4, timeout: 30_000 });
|
|
209
|
+
const invoiceId = '42';
|
|
210
|
+
|
|
211
|
+
const {
|
|
212
|
+
data: run,
|
|
213
|
+
idempotentReplayed,
|
|
214
|
+
requestId,
|
|
215
|
+
} = await client
|
|
216
|
+
.extract({
|
|
217
|
+
file: 'invoice.pdf',
|
|
218
|
+
catalog: 'schet-faktura',
|
|
219
|
+
idempotencyKey: `invoice-${invoiceId}`,
|
|
220
|
+
})
|
|
221
|
+
.withResponse();
|
|
222
|
+
console.log(run.id, idempotentReplayed, requestId);
|
|
223
|
+
|
|
224
|
+
// Настройки для отдельного вызова: { timeout, maxRetries, idempotencyKey, extraHeaders, signal }
|
|
225
|
+
const balance = await client.balance({ maxRetries: 0 });
|
|
226
|
+
console.log(balance.pages_available);
|
|
227
|
+
```
|
|
151
228
|
|
|
152
|
-
|
|
229
|
+
`.withResponse()` есть у каждого метода: кроме результата он отдаёт `Response` с заголовками
|
|
230
|
+
(`X-Request-Id`, `RateLimit-*`, `Location`) и признак `idempotentReplayed`. Учтите: повтор создания
|
|
231
|
+
конечной точки вебхука с тем же ключом отдаёт `secret: null` — секрет приходит только в первом
|
|
232
|
+
ответе. Ожидание можно отменить: `signal` (`AbortSignal`) прерывает и запрос, и паузу, и опрос.
|
|
153
233
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
234
|
+
## Вебхуки
|
|
235
|
+
|
|
236
|
+
Вместо ожидания результат можно получать вебхуком: `webhookUrl` в `extract`/`runs.create` или
|
|
237
|
+
конечная точка:
|
|
238
|
+
|
|
239
|
+
```ts
|
|
240
|
+
import { Typizer } from 'typizer';
|
|
241
|
+
|
|
242
|
+
const client = new Typizer();
|
|
243
|
+
|
|
244
|
+
const endpoint = await client.webhookEndpoints.create({
|
|
245
|
+
url: 'https://your-server.example/typizer/webhook',
|
|
246
|
+
events: ['run.succeeded', 'run.failed'],
|
|
159
247
|
});
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
248
|
+
console.log(endpoint.secret); // whsec_… — ключ для проверки подписи, храните как секрет
|
|
249
|
+
|
|
250
|
+
await client.webhookEndpoints.test(endpoint.id); // пришлёт тестовый run.succeeded
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Доставки подписаны по [Standard Webhooks](https://www.standardwebhooks.com). `verifyWebhook`
|
|
254
|
+
проверяет подпись и время (±5 минут) и возвращает событие; клиент и ключ API для этого не нужны.
|
|
255
|
+
Передайте **сырое** тело запроса — в Express это `express.raw`:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
import express from 'express';
|
|
259
|
+
import { verifyWebhook, WebhookVerificationError } from 'typizer';
|
|
260
|
+
|
|
261
|
+
const app = express();
|
|
262
|
+
|
|
263
|
+
app.post('/typizer/webhook', express.raw({ type: 'application/json' }), (req, res) => {
|
|
264
|
+
try {
|
|
265
|
+
const event = verifyWebhook(
|
|
266
|
+
req.body,
|
|
267
|
+
req.headers,
|
|
268
|
+
process.env.TYPIZER_WEBHOOK_SECRET as string,
|
|
269
|
+
);
|
|
270
|
+
if (event.run) console.log(event.type, event.run.id, event.run.output); // run.succeeded / run.failed
|
|
271
|
+
res.sendStatus(200);
|
|
272
|
+
} catch (err) {
|
|
273
|
+
if (err instanceof WebhookVerificationError) return res.sendStatus(400); // err.reason
|
|
274
|
+
throw err;
|
|
170
275
|
}
|
|
171
|
-
}
|
|
276
|
+
});
|
|
277
|
+
|
|
278
|
+
app.listen(3000);
|
|
172
279
|
```
|
|
173
280
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
ничего не создастся и не спишется. Остальные коды не исчезнут от повтора: сначала исправьте причину.
|
|
177
|
-
Все коды со статусами HTTP — [«Коды ошибок»](https://docs.typizer.ru/reference/errors/), правила
|
|
178
|
-
повторов — [«Обработка ошибок и повторов»](https://docs.typizer.ru/how-to/errors/).
|
|
281
|
+
`event.id` — ключ дедупликации (одно событие может прийти дважды). Есть и `isValidWebhook(...)`,
|
|
282
|
+
который возвращает `true`/`false` вместо исключения, и `Typizer.webhooks.verify(...)`.
|
|
179
283
|
|
|
180
|
-
|
|
181
|
-
`Problem`. Если удобнее исключения, передайте `throwOnError: true` в вызов: тогда функция бросает
|
|
182
|
-
тело ошибки, а возвращает `{ data }` без `error`.
|
|
284
|
+
## Прокси и свой HTTP-клиент
|
|
183
285
|
|
|
184
|
-
|
|
286
|
+
Встроенный `fetch` Node.js переменные `HTTPS_PROXY`/`NO_PROXY` не учитывает, пока не задан
|
|
287
|
+
`NODE_USE_ENV_PROXY=1` (Node.js 24+). Явный прокси — опция `proxy` (нужен пакет `undici`:
|
|
288
|
+
`npm i undici`; логин и пароль можно передать в URL). Свой `fetch` — опция `fetch`: тогда прокси и
|
|
289
|
+
TLS настраивает он. Корпоративный корневой сертификат подключается штатно:
|
|
290
|
+
`NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. Отключать проверку TLS SDK не предлагает.
|
|
185
291
|
|
|
186
|
-
|
|
187
|
-
|
|
292
|
+
```ts
|
|
293
|
+
import { Typizer } from 'typizer';
|
|
294
|
+
|
|
295
|
+
const viaProxy = new Typizer({ proxy: 'http://user:password@proxy.local:3128' });
|
|
296
|
+
|
|
297
|
+
const withOwnFetch = new Typizer({
|
|
298
|
+
fetch: (input, init) => fetch(input, init), // ваш fetch: агент, прокси, тесты
|
|
299
|
+
appInfo: { name: 'acme-erp', version: '2.1.0' }, // попадёт в User-Agent
|
|
300
|
+
});
|
|
301
|
+
console.log(String(viaProxy), String(withOwnFetch)); // ключ в строке маскируется: tz_live_…a1b2
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
## Логи
|
|
305
|
+
|
|
306
|
+
SDK пишет в `console` только предупреждения (например, о плановых работах — один раз). Подробнее:
|
|
307
|
+
`TYPIZER_LOG=debug` (строка на каждую HTTP-попытку: метод, путь, статус, `request_id`,
|
|
308
|
+
длительность) или `TYPIZER_LOG=info` (каждый повтор и его причина), либо опции `logLevel` и `logger`
|
|
309
|
+
(любой объект с методами `debug`, `info`, `warn`):
|
|
310
|
+
|
|
311
|
+
```ts
|
|
312
|
+
import { Typizer } from 'typizer';
|
|
313
|
+
|
|
314
|
+
const client = new Typizer({ logLevel: 'debug', logger: console });
|
|
315
|
+
await client.me(); // typizer: GET /v1/me -> 200 in 0.12s (request_id=req_…, attempt 1/3)
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Ключ API, тела запросов и ответов, имена файлов, `metadata` и секреты в логи не попадают никогда.
|
|
319
|
+
|
|
320
|
+
## Низкоуровневый клиент
|
|
321
|
+
|
|
322
|
+
Функции версии 0.1 — по одной на каждую операцию API, с именами `operationId` из
|
|
323
|
+
[справочника API](https://docs.typizer.ru/reference/api/) — остаются и работают как раньше;
|
|
324
|
+
`createTypizerClient` теперь отправляет `User-Agent` и ограничивает запрос 75 секундами (опция
|
|
325
|
+
`timeout`). Функции возвращают `{ data, error, response }` и сами не повторяют запросы:
|
|
188
326
|
|
|
189
327
|
```ts
|
|
190
|
-
import { createTypizerClient,
|
|
328
|
+
import { createTypizerClient, extract, getRun } from 'typizer';
|
|
191
329
|
|
|
192
330
|
const client = createTypizerClient({ apiKey: process.env.TYPIZER_API_KEY as string });
|
|
193
331
|
|
|
194
|
-
const { data:
|
|
332
|
+
const { data: run, error } = await extract({
|
|
195
333
|
client,
|
|
196
334
|
body: {
|
|
197
|
-
url: 'https://
|
|
198
|
-
|
|
335
|
+
url: 'https://typizer.ru/samples/invoice.pdf',
|
|
336
|
+
schema: { type: 'object', properties: { total: { type: 'number' } } },
|
|
199
337
|
},
|
|
338
|
+
query: { wait: 60 },
|
|
339
|
+
headers: { 'Idempotency-Key': crypto.randomUUID() },
|
|
200
340
|
});
|
|
201
|
-
if (error) throw new Error(error.detail);
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
await testWebhookEndpoint({ client, path: { id: endpoint.id } }); // пришлёт тестовый run.succeeded
|
|
341
|
+
if (error) throw new Error(`${error.code}: ${error.detail}`);
|
|
342
|
+
const fresh = await getRun({ client, path: { id: run.id } });
|
|
343
|
+
console.log(fresh.data?.status);
|
|
205
344
|
```
|
|
206
345
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Никогда не обрабатывайте тело вебхука, не проверив подпись.
|
|
346
|
+
Тип `Typizer` по-прежнему означает модель сохранённой схемы (`import type { Typizer } from
|
|
347
|
+
'typizer'`); тип экземпляра клиента — `TypizerClient`. Функции внутренних операций Кабинета (вход,
|
|
348
|
+
оплата, ключи API и другие — с ключом API они не работают) помечены `@deprecated` и уйдут в 1.0.
|
|
211
349
|
|
|
212
350
|
## Документация
|
|
213
351
|
|
|
214
352
|
- [Документация Typizer](https://docs.typizer.ru)
|
|
215
|
-
- [SDK
|
|
216
|
-
- [Справочник API](https://docs.typizer.ru/reference/api/)
|
|
353
|
+
- [SDK](https://docs.typizer.ru/reference/sdks/)
|
|
354
|
+
- [Справочник API](https://docs.typizer.ru/reference/api/)
|
|
217
355
|
- [Первый вызов API](https://docs.typizer.ru/tutorials/first-api-call/)
|
|
356
|
+
- [Изменения](CHANGELOG.md)
|
|
218
357
|
|
|
219
358
|
Вопросы и проблемы — support@typizer.ru.
|
|
220
359
|
|