@v3finance/monitoring-sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this package. The format follows [Keep a Changelog](https://keepachangelog.com), versions —
+[SemVer](https://semver.org).
+
+## 0.1.0 — 2026-10-28
+
+First release.
+
+- `MonitoringClient`: account and personal keys, sign-in, networks and assets, your client (webhook URL, signing
+  secret, client keys, members, test webhook), addresses and subscriptions with automatic batching, webhook history,
+  transaction lookup with confirmations and finality.
+- Webhooks: `parseWebhook`, `verifyWebhookSignature`, `signWebhookBody`, `isTestWebhook`, `webhookIdempotencyKey`.
+- Amounts: `formatUnits`, `parseUnits`.
+- Timeouts, cancellation, retries on 429 and 503, typed errors with per-item details.
+- Types generated from the OpenAPI spec of the API.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 V3 Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# @v3finance/monitoring-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official TypeScript SDK for the [V3 Finance address monitoring API](https://monitoring.v3.finance/docs):
+watch addresses on TRON and EVM networks and receive a signed webhook for every incoming and outgoing transfer.
+
+- **Typed end to end** — request and response types are generated from the API's OpenAPI spec, with docs on hover.
+- **Webhooks** — signature verification and typed parsing with no network calls, using Web Crypto.
+- **Built for production** — timeouts, cancellation, retries on rate limits, typed errors with per-item details,
+  automatic batching of large address lists, async iteration over pages.
+- **Zero runtime dependencies** — Node.js 20+, Bun, Deno, Cloudflare Workers; ESM and CommonJS.
+
+[Русская версия ниже](#по-русски).
+
+## Install
+
+```bash
+npm install @v3finance/monitoring-sdk
+```
+
+Server-side only: an API key in a browser is visible to anyone.
+
+## Quick start
+
+```ts
+import { MonitoringClient } from '@v3finance/monitoring-sdk'
+
+const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY })
+
+// your client id: for a client key it is in the key's identity
+const { actor } = await monitoring.account.me()
+const clientId = actor.clientId!
+
+// deposit addresses: incoming USDT only
+await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr', label: 'user-42' }], {
+  assets: ['USDT'],
+  direction: 'in',
+})
+```
+
+## Authentication
+
+| Credential | How to get it | What it can do |
+|---|---|---|
+| Client key `ce_…` | panel → client → API keys, or `clients.keys.create()` | addresses, history and transactions of that client |
+| Personal key `ce_user_…` | panel → Account, or `account.keys.create()` after signing in | everything you can do in the panel, with your role |
+| Session | `MonitoringClient.signIn({ email, password })` | same as a personal key |
+
+```ts
+const monitoring = new MonitoringClient({ apiKey: 'ce_…' })
+const { client } = await MonitoringClient.signIn({ email, password })
+```
+
+## Receiving webhooks
+
+Every webhook is a `POST` with JSON `{ tx: { network, asset, contract, type, id, block, timestamp, from, to, value, logIndex? } }`
+and an `x-signature` header — HMAC-SHA256 of the raw body with your client's secret. Verify it against the **raw**
+body: re-serialized JSON will not match.
+
+```ts
+import express from 'express'
+import { isTestWebhook, parseWebhook, webhookIdempotencyKey, WebhookSignatureError } from '@v3finance/monitoring-sdk'
+
+app.post('/webhooks/monitoring', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const event = await parseWebhook(req.body, req.headers, process.env.MONITORING_WEBHOOK_SECRET!)
+    if (!isTestWebhook(event)) await creditOnce(webhookIdempotencyKey(event), event.tx)
+    res.sendStatus(200)
+  } catch (e) {
+    if (e instanceof WebhookSignatureError) return res.sendStatus(401)
+    throw e
+  }
+})
+```
+
+Hono, Next.js route handlers, Cloudflare Workers:
+
+```ts
+const event = await parseWebhook(await request.text(), request.headers, env.MONITORING_WEBHOOK_SECRET)
+```
+
+Rules of delivery:
+
+- Answer **2xx within 15 seconds**; otherwise the webhook is retried after 10 s, 1 min and 5 min.
+- The same webhook can arrive more than once — process it idempotently by `webhookIdempotencyKey(event)`.
+- `type` is always `TOPUP` for both directions: compare `from` and `to` with your addresses.
+- A webhook is sent as soon as the transfer is in a block, before finality. For large amounts check
+  `final` first (below).
+- Test webhooks (`isTestWebhook(event)`, header `x-webhook-test: 1`) must not be credited.
+
+## Transactions: confirmations and finality
+
+Any transaction by hash, not only the ones you got a webhook for:
+
+```ts
+const tx = await monitoring.transactions.get('tron', event.tx.id)
+tx.status        // 'success' | 'failed' | 'pending'
+tx.confirmations // from the current head of the network
+tx.final         // cannot be reverted: TRON — solidified (~1 min), Ethereum — finalized (~13 min)
+tx.transfers     // every transfer inside: native, tokens, TRON internal TRX transfers
+tx.watched       // your watched addresses in this transaction
+tx.webhooks      // webhooks we sent you for it
+```
+
+## Addresses and subscriptions
+
+```ts
+await monitoring.addresses.add(clientId, items, { assets: ['USDT'], direction: 'in' }) // more than 1000 — batched for you
+await monitoring.addresses.update(clientId, [{ network: 'tron', address: 'T…' }], { direction: 'both' })
+await monitoring.addresses.remove(clientId, [{ network: 'tron', address: 'T…' }])
+
+for await (const a of monitoring.addresses.iterate(clientId, { network: 'tron' })) {
+  console.log(a.address, a.assets ?? 'all assets', a.direction)
+}
+```
+
+A subscription narrows what you are notified about: `assets` — symbols or contract addresses (`null` — all assets of
+the network, including ones added later), `direction` — `in`, `out` or `both`. EVM addresses are per network: watch
+one address on several networks with several items.
+
+## Webhook history
+
+```ts
+for await (const d of monitoring.deliveries.iterate(clientId, { status: 'failed', since: new Date(Date.now() - 86_400_000) })) {
+  console.log(d.txId, d.attempts, d.lastHttpStatus ?? d.lastError)
+}
+const detail = await monitoring.deliveries.get(clientId, id) // exact body and URL
+```
+
+## Your client
+
+Owner and admin of a client (session or personal key):
+
+```ts
+await monitoring.clients.update(clientId, { webhookUrl: 'https://example.com/webhooks/monitoring' })
+const { secretKey } = await monitoring.clients.rotateSecret(clientId) // the old secret stops working at once
+const { key } = await monitoring.clients.keys.create(clientId, { name: 'backend', expiresInDays: 365 })
+const result = await monitoring.clients.sendTestWebhook(clientId, { asset: 'USDT' }) // result.delivery.ok
+```
+
+## Amounts
+
+Amounts are strings in minimal units (sun, wei; USDT has 6 decimals). Convert without losing precision:
+
+```ts
+import { formatUnits, parseUnits } from '@v3finance/monitoring-sdk'
+
+formatUnits('100000000', 6) // '100'
+parseUnits('1.5', 6)        // '1500000'
+```
+
+Decimals of every asset: `monitoring.assets.list()`.
+
+## Errors, retries, timeouts
+
+```ts
+import { MonitoringApiError, MonitoringConnectionError } from '@v3finance/monitoring-sdk'
+
+try {
+  await monitoring.addresses.add(clientId, items)
+} catch (e) {
+  if (e instanceof MonitoringApiError) {
+    e.status    // 400
+    e.code      // 'invalid_request'
+    e.details   // [{ index: 3, message: 'not a valid TRON address' }]
+    e.requestId // send it to support
+  }
+}
+```
+
+- `429` and `503` are retried with the server's `Retry-After` or exponential backoff (`maxRetries`, default 2).
+  Network errors are retried only for requests that are safe to repeat.
+- Every request has a timeout (`timeoutMs`, default 30 s) and accepts an `AbortSignal`:
+  `monitoring.addresses.list(clientId, {}, { signal })`.
+- All errors extend `MonitoringError`.
+
+## API reference
+
+- Interactive reference: https://monitoring.v3.finance/docs
+- OpenAPI 3.1: https://monitoring.v3.finance/openapi.json
+- All request and response types are exported: `import type { Transaction, WebhookPayload } from '@v3finance/monitoring-sdk'`.
+
+## Versioning
+
+[SemVer](https://semver.org). While the version is `0.x`, minor releases may contain breaking changes; they are listed in
+[CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## По-русски
+
+Официальный SDK API мониторинга адресов V3 Finance: адреса в TRON и EVM-сетях, подписанные вебхуки о переводах,
+история доставок, транзакции с подтверждениями и финальностью. Подсказки в редакторе — по-русски.
+
+```bash
+npm install @v3finance/monitoring-sdk
+```
+
+**Только для сервера** — ключ в браузере увидит любой. Node.js 20+, Bun, Deno, Cloudflare Workers; ESM и CommonJS.
+
+```ts
+import { MonitoringClient, parseWebhook, isTestWebhook, webhookIdempotencyKey } from '@v3finance/monitoring-sdk'
+
+const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY }) // ключ клиента ce_…
+const clientId = (await monitoring.account.me()).actor.clientId!
+
+// депозитные адреса: только входящие USDT
+await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…', label: 'user-42' }], { assets: ['USDT'], direction: 'in' })
+
+// приём вебхука: подпись — по сырому телу
+const event = await parseWebhook(rawBody, headers, process.env.MONITORING_WEBHOOK_SECRET!)
+if (!isTestWebhook(event)) await creditOnce(webhookIdempotencyKey(event), event.tx)
+
+// перед зачислением крупной суммы — финальность
+const tx = await monitoring.transactions.get('tron', event.tx.id)
+if (tx.status === 'success' && tx.final) { /* зачислить */ }
+```
+
+Главное при приёме вебхуков:
+
+- отвечайте **2xx за 15 секунд**, иначе повторы через 10 с, 1 мин и 5 мин;
+- один вебхук может прийти повторно — обрабатывайте идемпотентно по `webhookIdempotencyKey(event)`;
+- `type` всегда `TOPUP` — направление определяйте по `from` и `to`;
+- вебхук уходит сразу, как перевод попал в блок, до финальности: крупные суммы зачисляйте после `final`;
+- тестовые вебхуки (`isTestWebhook`, заголовок `x-webhook-test: 1`) не зачислять.
+
+Ключи: **ключ клиента** `ce_…` — адреса, история и транзакции своего клиента; **личный ключ** `ce_user_…` — всё, что вы
+можете в панели (URL вебхука, секрет, ключи клиента, тестовый вебхук). Ошибки — `MonitoringApiError` со статусом, кодом
+и ошибками по элементам (`details`); повторы при 429 и 503, таймауты и отмена через `AbortSignal` — встроены.
+Суммы — строки в минимальных единицах: `formatUnits('100000000', 6) === '100'`.
+
+Справочник API: https://monitoring.v3.finance/docs.
+
+## Development
+
+```bash
+npm install
+npm run spec:update   # snapshot of https://monitoring.v3.finance/openapi.json → openapi/openapi.json
+npm run generate      # → src/generated/types.ts
+npm run typecheck && npm test && npm run build
+npm run build && MONITORING_API_KEY=ce_… node scripts/smoke.ts   # against the real API, with a client key
+```
+
+Releases: bump `version` in `package.json` and `src/version.ts`, update `CHANGELOG.md`, publish a GitHub release
+`vX.Y.Z` — the `publish` workflow publishes to npm with Trusted Publishing.
+
+## License
+
+[MIT](./LICENSE)

package/dist/cjs/client.d.ts

@@ -0,0 +1,65 @@
+import { type ClientOptions, type RequestOptions } from './core/http.js';
+import { AccountResource, AuthResource, type SignInResult } from './resources/account.js';
+import { AddressesResource } from './resources/addresses.js';
+import { AssetsResource, NetworksResource } from './resources/catalog.js';
+import { ClientsResource } from './resources/clients.js';
+import { DeliveriesResource } from './resources/deliveries.js';
+import { TransactionsResource } from './resources/transactions.js';
+/**
+ * Клиент API мониторинга адресов V3 Finance: адреса и подписки, история вебхуков, транзакции, ваш клиент и ключи.
+ * Только для сервера: ключ в браузере увидит любой.
+ *
+ * @example С ключом клиента — для бэкенда
+ * ```ts
+ * import { MonitoringClient } from '@v3finance/monitoring-sdk'
+ *
+ * const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY })
+ * await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…' }], { assets: ['USDT'], direction: 'in' })
+ * ```
+ *
+ * @example По паролю — для скриптов, которым нужны права пользователя
+ * ```ts
+ * const { client } = await MonitoringClient.signIn({ email, password })
+ * const { key } = await client.account.keys.create({ name: 'ci' })
+ * ```
+ */
+export declare class MonitoringClient {
+    #private;
+    /** Кто вы и ваши личные ключи */
+    readonly account: AccountResource;
+    /** Выход и смена пароля (для клиента, вошедшего по паролю) */
+    readonly auth: AuthResource;
+    /** Сети */
+    readonly networks: NetworksResource;
+    /** Нативные монеты и токены */
+    readonly assets: AssetsResource;
+    /** Ваш клиент: URL вебхука, секрет, ключи, участники, тестовый вебхук */
+    readonly clients: ClientsResource;
+    /** Адреса на мониторинге и подписка */
+    readonly addresses: AddressesResource;
+    /** История вебхуков */
+    readonly deliveries: DeliveriesResource;
+    /** Транзакция по хешу: статус, подтверждения, финальность */
+    readonly transactions: TransactionsResource;
+    /**
+     * @param options - ключ (`apiKey`) или токен сессии (`sessionToken`), адрес API, таймаут, повторы
+     * @throws {@link MonitoringError} переданы и ключ, и токен; нет `fetch`
+     */
+    constructor(options?: ClientOptions);
+    /** Адрес API, с которым работает клиент */
+    get baseUrl(): string;
+    /**
+     * Вход по email и паролю: возвращает клиента с токеном сессии. Регистрации нет — пользователей заводит
+     * администратор сервиса. Не больше 3 попыток за 10 секунд с одного IP.
+     *
+     * @param options - настройки клиента, кроме учётных данных
+     * @throws {@link MonitoringApiError} 401 — неверный email или пароль
+     */
+    static signIn(credentials: {
+        email: string;
+        password: string;
+    }, options?: Omit<ClientOptions, 'apiKey' | 'sessionToken'>, requestOptions?: RequestOptions): Promise<SignInResult & {
+        client: MonitoringClient;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAGlE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAgB;;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,WAAW;IACX,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,uBAAuB;IACvB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAA;IAI3C;;;OAGG;IACH,YAAY,OAAO,GAAE,aAAkB,EAUtC;IAED,2CAA2C;IAC3C,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;;;OAMG;IACH,OAAa,MAAM,CACjB,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAChD,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,cAAc,CAAM,EAC5D,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,YAAY,GAAG;QAAE,MAAM,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAYtD;CACF"}

package/dist/cjs/client.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonitoringClient = void 0;
+const http_js_1 = require("./core/http.js");
+const account_js_1 = require("./resources/account.js");
+const addresses_js_1 = require("./resources/addresses.js");
+const catalog_js_1 = require("./resources/catalog.js");
+const clients_js_1 = require("./resources/clients.js");
+const deliveries_js_1 = require("./resources/deliveries.js");
+const transactions_js_1 = require("./resources/transactions.js");
+const version_js_1 = require("./version.js");
+/**
+ * Клиент API мониторинга адресов V3 Finance: адреса и подписки, история вебхуков, транзакции, ваш клиент и ключи.
+ * Только для сервера: ключ в браузере увидит любой.
+ *
+ * @example С ключом клиента — для бэкенда
+ * ```ts
+ * import { MonitoringClient } from '@v3finance/monitoring-sdk'
+ *
+ * const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY })
+ * await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…' }], { assets: ['USDT'], direction: 'in' })
+ * ```
+ *
+ * @example По паролю — для скриптов, которым нужны права пользователя
+ * ```ts
+ * const { client } = await MonitoringClient.signIn({ email, password })
+ * const { key } = await client.account.keys.create({ name: 'ci' })
+ * ```
+ */
+class MonitoringClient {
+    /** Кто вы и ваши личные ключи */
+    account;
+    /** Выход и смена пароля (для клиента, вошедшего по паролю) */
+    auth;
+    /** Сети */
+    networks;
+    /** Нативные монеты и токены */
+    assets;
+    /** Ваш клиент: URL вебхука, секрет, ключи, участники, тестовый вебхук */
+    clients;
+    /** Адреса на мониторинге и подписка */
+    addresses;
+    /** История вебхуков */
+    deliveries;
+    /** Транзакция по хешу: статус, подтверждения, финальность */
+    transactions;
+    #http;
+    /**
+     * @param options - ключ (`apiKey`) или токен сессии (`sessionToken`), адрес API, таймаут, повторы
+     * @throws {@link MonitoringError} переданы и ключ, и токен; нет `fetch`
+     */
+    constructor(options = {}) {
+        this.#http = new http_js_1.HttpClient(options, version_js_1.DEFAULT_BASE_URL);
+        this.account = new account_js_1.AccountResource(this.#http);
+        this.auth = new account_js_1.AuthResource(this.#http);
+        this.networks = new catalog_js_1.NetworksResource(this.#http);
+        this.assets = new catalog_js_1.AssetsResource(this.#http);
+        this.clients = new clients_js_1.ClientsResource(this.#http);
+        this.addresses = new addresses_js_1.AddressesResource(this.#http);
+        this.deliveries = new deliveries_js_1.DeliveriesResource(this.#http);
+        this.transactions = new transactions_js_1.TransactionsResource(this.#http);
+    }
+    /** Адрес API, с которым работает клиент */
+    get baseUrl() {
+        return this.#http.baseUrl;
+    }
+    /**
+     * Вход по email и паролю: возвращает клиента с токеном сессии. Регистрации нет — пользователей заводит
+     * администратор сервиса. Не больше 3 попыток за 10 секунд с одного IP.
+     *
+     * @param options - настройки клиента, кроме учётных данных
+     * @throws {@link MonitoringApiError} 401 — неверный email или пароль
+     */
+    static async signIn(credentials, options = {}, requestOptions) {
+        const http = new http_js_1.HttpClient(options, version_js_1.DEFAULT_BASE_URL);
+        const r = await http.request({
+            method: 'POST',
+            path: '/api/auth/sign-in/email',
+            body: credentials,
+            idempotent: false,
+            auth: false,
+            // повтор при отказе 429 только сожжёт попытки входа
+            options: { maxRetries: 0, ...requestOptions },
+        });
+        return { token: r.token, user: r.user, client: new MonitoringClient({ ...options, sessionToken: r.token }) };
+    }
+}
+exports.MonitoringClient = MonitoringClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;;AAAA,4CAAoF;AAEpF,uDAAyF;AACzF,2DAA4D;AAC5D,uDAAyE;AACzE,uDAAwD;AACxD,6DAA8D;AAC9D,iEAAkE;AAClE,6CAA+C;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH;IACE,iCAAiC;IACxB,OAAO,CAAiB;IACjC,8DAA8D;IACrD,IAAI,CAAc;IAC3B,WAAW;IACF,QAAQ,CAAkB;IACnC,+BAA+B;IACtB,MAAM,CAAgB;IAC/B,yEAAyE;IAChE,OAAO,CAAiB;IACjC,uCAAuC;IAC9B,SAAS,CAAmB;IACrC,uBAAuB;IACd,UAAU,CAAoB;IACvC,6DAA6D;IACpD,YAAY,CAAsB;IAElC,KAAK,CAAY;IAE1B;;;OAGG;IACH,YAAY,OAAO,GAAkB,EAAE;QACrC,IAAI,CAAC,KAAK,GAAG,IAAI,oBAAU,CAAC,OAAO,EAAE,6BAAgB,CAAC,CAAA;QACtD,IAAI,CAAC,OAAO,GAAG,IAAI,4BAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC9C,IAAI,CAAC,IAAI,GAAG,IAAI,yBAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,6BAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,2BAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC5C,IAAI,CAAC,OAAO,GAAG,IAAI,4BAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,gCAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClD,IAAI,CAAC,UAAU,GAAG,IAAI,kCAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpD,IAAI,CAAC,YAAY,GAAG,IAAI,sCAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1D,CAAC;IAED,2CAA2C;IAC3C,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAA;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,WAAgD,EAChD,OAAO,GAAmD,EAAE,EAC5D,cAA+B;QAE/B,MAAM,IAAI,GAAG,IAAI,oBAAU,CAAC,OAAO,EAAE,6BAAgB,CAAC,CAAA;QACtD,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAgC;YAC1D,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,yBAAyB;YAC/B,IAAI,EAAE,WAAW;YACjB,UAAU,EAAE,KAAK;YACjB,IAAI,EAAE,KAAK;YACX,oDAAoD;YACpD,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,cAAc,EAAE;SAC9C,CAAC,CAAA;QACF,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,gBAAgB,CAAC,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAA;IAC9G,CAAC;CACF"}

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,64 @@
+import type { ApiErrorBody } from '../generated/types.js';
+/** Ошибка по элементу запроса: номер элемента в переданном массиве и причина */
+export type ErrorDetail = NonNullable<ApiErrorBody['error']['details']>[number];
+/**
+ * Базовый класс всех ошибок SDK. Ловите его, чтобы перехватить любую ошибку SDK.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await monitoring.addresses.add(clientId, items)
+ * } catch (e) {
+ *   if (e instanceof MonitoringApiError && e.status === 400) console.log(e.details)
+ *   else throw e
+ * }
+ * ```
+ */
+export declare class MonitoringError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** API ответил ошибкой: HTTP 4xx или 5xx */
+export declare class MonitoringApiError extends MonitoringError {
+    /** HTTP-статус ответа */
+    readonly status: number;
+    /**
+     * Машинный код ошибки: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`,
+     * `rate_limited`, `upstream_error`, `upstream_rate_limited`, `unavailable`…
+     */
+    readonly code: string;
+    /** Ошибки по элементам запроса (например, какой адрес из переданных не подошёл); пустой массив, если их нет */
+    readonly details: ErrorDetail[];
+    /** Идентификатор запроса (`cf-ray`) — укажите его, если обращаетесь в поддержку */
+    readonly requestId: string | undefined;
+    /** Тело ответа как есть */
+    readonly body: unknown;
+    constructor(init: {
+        status: number;
+        code: string;
+        message: string;
+        details?: ErrorDetail[];
+        requestId?: string;
+        body?: unknown;
+    });
+    /** Временная ошибка — лимит частоты или недоступный провайдер: запрос можно повторить позже */
+    get retryable(): boolean;
+}
+/** Ответа нет: сбой сети или соединения */
+export declare class MonitoringConnectionError extends MonitoringError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Запрос не уложился в таймаут (`timeoutMs`) */
+export declare class MonitoringTimeoutError extends MonitoringConnectionError {
+    constructor(timeoutMs: number);
+}
+/** Подпись вебхука не прошла проверку: тело подделано, изменено по дороге или проверяется не тем секретом */
+export declare class WebhookSignatureError extends MonitoringError {
+    constructor(message?: string);
+}
+/** Тело ошибки в любом из форматов API: `/v1`, старые пути (`{ok: false}`), вход (`{code, message}`) */
+export declare function apiErrorFrom(status: number, body: unknown, requestId: string | undefined): MonitoringApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/E;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED,4CAA4C;AAC5C,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAA;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IAEtB,YAAY,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,EAQ/H;IAED,+FAA+F;IAC/F,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED,2CAA2C;AAC3C,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED,iDAAiD;AACjD,qBAAa,sBAAuB,SAAQ,yBAAyB;IACnE,YAAY,SAAS,EAAE,MAAM,EAG5B;CACF;AAED,6GAA6G;AAC7G,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,YAAY,OAAO,SAA+B,EAGjD;CACF;AAED,wGAAwG;AACxG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CAW7G"}

package/dist/cjs/core/errors.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSignatureError = exports.MonitoringTimeoutError = exports.MonitoringConnectionError = exports.MonitoringApiError = exports.MonitoringError = void 0;
+exports.apiErrorFrom = apiErrorFrom;
+/**
+ * Базовый класс всех ошибок SDK. Ловите его, чтобы перехватить любую ошибку SDK.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await monitoring.addresses.add(clientId, items)
+ * } catch (e) {
+ *   if (e instanceof MonitoringApiError && e.status === 400) console.log(e.details)
+ *   else throw e
+ * }
+ * ```
+ */
+class MonitoringError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MonitoringError';
+    }
+}
+exports.MonitoringError = MonitoringError;
+/** API ответил ошибкой: HTTP 4xx или 5xx */
+class MonitoringApiError extends MonitoringError {
+    /** HTTP-статус ответа */
+    status;
+    /**
+     * Машинный код ошибки: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`,
+     * `rate_limited`, `upstream_error`, `upstream_rate_limited`, `unavailable`…
+     */
+    code;
+    /** Ошибки по элементам запроса (например, какой адрес из переданных не подошёл); пустой массив, если их нет */
+    details;
+    /** Идентификатор запроса (`cf-ray`) — укажите его, если обращаетесь в поддержку */
+    requestId;
+    /** Тело ответа как есть */
+    body;
+    constructor(init) {
+        super(`${init.message} (HTTP ${init.status}, ${init.code})`);
+        this.name = 'MonitoringApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details ?? [];
+        this.requestId = init.requestId;
+        this.body = init.body;
+    }
+    /** Временная ошибка — лимит частоты или недоступный провайдер: запрос можно повторить позже */
+    get retryable() {
+        return this.status === 429 || this.status === 503;
+    }
+}
+exports.MonitoringApiError = MonitoringApiError;
+/** Ответа нет: сбой сети или соединения */
+class MonitoringConnectionError extends MonitoringError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MonitoringConnectionError';
+    }
+}
+exports.MonitoringConnectionError = MonitoringConnectionError;
+/** Запрос не уложился в таймаут (`timeoutMs`) */
+class MonitoringTimeoutError extends MonitoringConnectionError {
+    constructor(timeoutMs) {
+        super(`request timed out after ${timeoutMs} ms`);
+        this.name = 'MonitoringTimeoutError';
+    }
+}
+exports.MonitoringTimeoutError = MonitoringTimeoutError;
+/** Подпись вебхука не прошла проверку: тело подделано, изменено по дороге или проверяется не тем секретом */
+class WebhookSignatureError extends MonitoringError {
+    constructor(message = 'webhook signature mismatch') {
+        super(message);
+        this.name = 'WebhookSignatureError';
+    }
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/** Тело ошибки в любом из форматов API: `/v1`, старые пути (`{ok: false}`), вход (`{code, message}`) */
+function apiErrorFrom(status, body, requestId) {
+    const b = (body ?? {});
+    const v1 = typeof b.error === 'object' && b.error !== null ? b.error : undefined;
+    const message = (typeof v1?.message === 'string' && v1.message) ||
+        (typeof b.error === 'string' && b.error) ||
+        (typeof b.message === 'string' && b.message) ||
+        `HTTP ${status}`;
+    const code = (typeof v1?.code === 'string' && v1.code) || (typeof b.code === 'string' && b.code.toLowerCase()) || defaultCode(status);
+    const details = (Array.isArray(v1?.details) ? v1.details : Array.isArray(b.details) ? b.details : []);
+    return new MonitoringApiError({ status, code, message, details, requestId, body });
+}
+function defaultCode(status) {
+    const codes = { 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 409: 'conflict', 429: 'rate_limited' };
+    return codes[status] ?? (status >= 500 ? 'server_error' : 'http_error');
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"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"}