typizer 0.1.0 → 0.3.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 ADDED
@@ -0,0 +1,76 @@
1
+ # Изменения
2
+
3
+ Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), версии — [SemVer](https://semver.org/lang/ru/).
4
+
5
+ ## [0.3.0] — 2026-11-16
6
+
7
+ Совместимо с 0.2: прежние вызовы работают без изменений.
8
+
9
+ ### Добавлено
10
+
11
+ - Причина `code_mismatch` у `fields[*].reason`: значение поля расходится со штрихкодом или QR-кодом на
12
+ документе. Сервис сам читает коды (платёжный QR по ГОСТ Р 56042-2014, QR чека, «Честный знак»),
13
+ чтобы точнее заполнять поля вашей схемы; ответ — по-прежнему только поля схемы, отдельного списка
14
+ кодов в прогоне нет.
15
+
16
+ ### Изменено
17
+
18
+ - Низкоуровневый слой перегенерирован из текущего описания API: внутренние операции Кабинета
19
+ (поддержка) добавлены с пометкой deprecated — с ключом API они не работают и уйдут в 1.0.
20
+
21
+ ## [0.2.0] — 2026-11-14
22
+
23
+ Версия без поломок: всё из 0.1.0 работает как раньше, новый клиент добавлен рядом.
24
+
25
+ ### Добавлено
26
+
27
+ - Клиент `Typizer` (`import Typizer from 'typizer'` или `import { Typizer } from 'typizer'`) по
28
+ единой спецификации SDK Typizer: ключ из `TYPIZER_API_KEY`, адрес по умолчанию
29
+ `https://api.typizer.ru`, таймаут попытки 75 с, `withOptions()`.
30
+ - `client.extract({ file, schema | catalog | typizer })` — документ и схема → данные одним вызовом:
31
+ локальный файл (путь, `Blob`/`File`, `Uint8Array`, `ReadableStream`) уходит в том же запросе
32
+ (`multipart/form-data`), SDK ждёт результат (серверное ожидание до 60 с, затем опрос, всего до
33
+ 5 минут) и бросает `RunFailedError`/`WaitTimeoutError`.
34
+ - Ресурсы `client.runs` (`create`, `get`, `wait`, `list`, `output`, `retry`), `client.files`,
35
+ `client.typizers` (`versions`, `catalogUpdate`, `generate`, `xsd`), `client.catalog`,
36
+ `client.batches`, `client.webhookEndpoints` (`deliveries`, `test`); `client.me()`,
37
+ `client.balance()`, `client.usage()`, `client.organization()`, `client.status()`.
38
+ - Типизированные ошибки: `TypizerError` → `APIError` (`BadRequestError`, `AuthenticationError`,
39
+ `InsufficientBalanceError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`,
40
+ `IdempotencyConflictError`, `FileTooLargeError`, `UnsupportedFileTypeError`,
41
+ `UnprocessableDocumentError`, `RateLimitError`, `InternalServerError`,
42
+ `ServiceUnavailableError`), `APIConnectionError`/`APITimeoutError`, `RunFailedError`,
43
+ `WaitTimeoutError`, `WebhookVerificationError`, `ConfigurationError`.
44
+ - Автоматические повторы (сеть, таймаут, 408, 429, 500, 502–504) с `Retry-After` и экспоненциальной
45
+ паузой; `Idempotency-Key` на каждом `POST`, один на все повторы вызова.
46
+ - `.withResponse()` у каждого метода: `Response`, `requestId`, `idempotentReplayed`.
47
+ - Автопагинация: `for await (const run of client.runs.list())`, `Page` с `nextPage()`.
48
+ - Проверка подписи вебхуков без зависимостей: `verifyWebhook`, `isValidWebhook`,
49
+ `Typizer.webhooks.verify`; помощники прогона `run.needsReview`, `run.fieldsToReview()`,
50
+ `run.isTerminal`.
51
+ - Отмена через `AbortSignal`, опции `proxy` (с пакетом `undici`), `fetch`, `defaultHeaders`,
52
+ `appInfo`, логи (`logger`, `logLevel`, `TYPIZER_LOG`); ключ API в логах и строковых представлениях
53
+ маскируется.
54
+ - `VERSION`; заголовок `User-Agent: typizer-ts/<версия> (node/<версия>; <ОС>/<архитектура>)`.
55
+
56
+ ### Исправлено
57
+
58
+ - `createTypizerClient` больше не ждёт ответа бесконечно: таймаут 75 с по умолчанию (опция
59
+ `timeout`, `0` — без таймаута) и заголовок `User-Agent: typizer-ts/<версия>`.
60
+
61
+ ### Устарело
62
+
63
+ - Функции внутренних операций Кабинета (`startLogin`, `createCheckout`, `createApiKey`,
64
+ `createAgentThread`, `createDemoRun`, `deleteMe` и другие — всего 45, с ключом API они не работают)
65
+ помечены `@deprecated` и будут удалены в 1.0.0, вместе с переходом низкоуровневого слоя на
66
+ публичное описание API.
67
+
68
+ ## [0.1.0] — 2026-11-07
69
+
70
+ ### Добавлено
71
+
72
+ - Первый выпуск: функции для каждой операции API, сгенерированные из OpenAPI, типы моделей и
73
+ `createTypizerClient({ apiKey, baseUrl?, fetch? })`.
74
+
75
+ [0.2.0]: https://www.npmjs.com/package/typizer/v/0.2.0
76
+ [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
- SDK сгенерирован из OpenAPI-описания Typizer API: одна функция на каждую операцию REST API, с теми
7
- же именами полей и кодами ошибок, и типы TypeScript для каждого запроса и ответа. Полная
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, с типами в комплекте (`@types/…` не нужен). Работает в Node.js 20+, Bun, Deno
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
- Ключ API — секрет сервера: не используйте его в коде, который выполняется в браузере.
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
- Извлечь данные из документа по разовой схеме (`POST /v1/extract`). `wait: 60` держит запрос до
35
- завершения прогона, но не дольше 60 секунд:
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 { createTypizerClient, extract } from 'typizer';
73
+ import { Typizer } from 'typizer';
39
74
 
40
- const client = createTypizerClient({
41
- apiKey: process.env.TYPIZER_API_KEY as string,
42
- // baseUrl по умолчанию — https://api.typizer.ru
43
- });
75
+ interface Invoice {
76
+ invoice_number: string;
77
+ total: number;
78
+ }
44
79
 
45
- const { data: run, error } = await extract({
46
- client,
47
- body: {
48
- url: 'https://typizer.ru/samples/invoice.pdf',
49
- schema: {
50
- type: 'object',
51
- properties: {
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
- query: { wait: 60 },
60
- headers: { 'Idempotency-Key': crypto.randomUUID() }, // новый ключ на каждую операцию
88
+ timeout: 120_000, // ждать не дольше 2 минут (по умолчанию 5)
61
89
  });
62
- if (error) throw new Error(`${error.code}: ${error.detail} (${error.doc_url})`);
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
- Если прогон не успел завершиться за `wait`, придёт `Run` со статусом `queued` или `processing` —
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
- Схему удобно сохранить как типизатор (`POST /v1/typizers`) и запускать его по `id`. Файл с диска
75
- сначала загружается через `createFile`, затем передаётся в прогон по `file_id`:
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 { openAsBlob } from 'node:fs';
79
- import { createFile, createRun, createTypizer, createTypizerClient } from 'typizer';
117
+ import { Typizer } from 'typizer';
80
118
 
81
- const client = createTypizerClient({ apiKey: process.env.TYPIZER_API_KEY as string });
119
+ const client = new Typizer();
82
120
 
83
- const { data: typizer, error: typizerError } = await createTypizer({
84
- client,
85
- body: {
86
- name: 'Счета поставщиков',
87
- schema: {
88
- type: 'object',
89
- properties: {
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 { data: file, error: fileError } = await createFile({
100
- client,
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
- const { data: run } = await createRun({
106
- client,
107
- path: { id: typizer.id },
108
- body: { file_id: file.id },
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
- Каждая операция API — отдельная асинхронная функция с тем же именем, что `operationId` в
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 type { Problem, Run, Typizer, WebhookEndpoint } from 'typizer';
130
-
131
- function summary(run: Run): string {
132
- return `${run.id}: ${run.status}, страниц списано ${run.pages.billed ?? 0}`;
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
- `createTypizerClient({ apiKey, baseUrl?, fetch? })` добавляет заголовок
137
- `Authorization: Bearer <apiKey>`; `fetch` можно подменить (тесты, свой агент или прокси).
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
- Любая ошибка API приходит в формате `application/problem+json` (RFC 9457). По умолчанию функции не
142
- бросают исключение, а возвращают тело ошибки в `error` (тип `Problem`):
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 { createRun, createTypizerClient } from 'typizer';
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
- const client = createTypizerClient({ apiKey: process.env.TYPIZER_API_KEY as string });
229
+ `.withResponse()` есть у каждого метода: кроме результата он отдаёт `Response` с заголовками
230
+ (`X-Request-Id`, `RateLimit-*`, `Location`) и признак `idempotentReplayed`. Учтите: повтор создания
231
+ конечной точки вебхука с тем же ключом отдаёт `secret: null` — секрет приходит только в первом
232
+ ответе. Ожидание можно отменить: `signal` (`AbortSignal`) прерывает и запрос, и паузу, и опрос.
153
233
 
154
- const { error, response } = await createRun({
155
- client,
156
- path: { id: 'tz_…' },
157
- body: { url: 'https://typizer.ru/samples/invoice.pdf' },
158
- headers: { 'Idempotency-Key': crypto.randomUUID() },
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
- if (error) {
161
- switch (error.code) {
162
- case 'rate_limited':
163
- console.log(`повторить через ${response?.headers.get('Retry-After')} с`);
164
- break;
165
- case 'insufficient_balance':
166
- console.log('пополните баланс в кабинете');
167
- break;
168
- default:
169
- console.log(error.code, error.detail, error.doc_url, error.request_id);
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
- Повторять имеет смысл `rate_limited` (после `Retry-After`), `upstream_unavailable` и
175
- `internal_error`; при сетевой ошибке повторяйте запрос с тем же `Idempotency-Key` — второй раз
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
- Сетевая ошибка (нет ответа сервера) тоже попадает в `error` — как исключение `fetch`, а не
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
- Вместо ожидания результат можно получать вебхуком: укажите `webhook_url` в запросе на прогон или
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, createWebhookEndpoint, testWebhookEndpoint } from 'typizer';
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: endpoint, error } = await createWebhookEndpoint({
332
+ const { data: run, error } = await extract({
195
333
  client,
196
334
  body: {
197
- url: 'https://your-server.example/typizer/webhook',
198
- events: ['run.succeeded', 'run.failed'],
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
- console.log(endpoint.secret); // whsec_… — ключ для проверки подписи, храните как секрет
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
- Вебхуки подписываются по спецификации [Standard Webhooks](https://www.standardwebhooks.com)
208
- (HMAC-SHA256). Функции проверки подписи в SDK нет: готовая реализация на `node:crypto` без
209
- сторонних пакетов и тестовый вектор — в [«Приёме вебхуков»](https://docs.typizer.ru/how-to/webhooks/).
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 для TypeScript и Python](https://docs.typizer.ru/reference/sdks/)
216
- - [Справочник API](https://docs.typizer.ru/reference/api/) — REST-операция за каждой функцией SDK
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