@v3finance/monitoring-sdk 0.1.0 → 0.2.0

package/src/resources/addresses.ts

@@ -1,126 +1,105 @@
 import { MonitoringApiError } from '../core/errors.js'
-import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
-import { paginate, type Page } from '../core/pagination.js'
-import type { Address, AddressInput, AssetSelection, Direction, UpdateAddressesRequest } from '../generated/types.js'
+import type { RequestOptions } from '../core/http.js'
+import { paginate } from '../core/pagination.js'
+import type { Scope } from '../core/scope.js'
+import type {
+  AddAddressesResult,
+  Address,
+  AddressInput,
+  AddressPage,
+  AddressRef,
+  AddressUpdate,
+  AssetSelection,
+  Direction,
+  RemoveAddressesResult,
+  UpdateAddressesResult,
+} from '../generated/types.js'
 
-/** Столько адресов API принимает за один запрос; больше SDK разбивает на пачки сам */
+/** Maximum number of addresses the API accepts per request. Larger lists are split into batches automatically. */
 export const ADDRESS_BATCH_SIZE = 1000
 
 /**
- * Подписка по умолчанию для всех адресов запроса — действует на элементы, где своей нет.
- * Без неё адрес получает все активы сети в обе стороны.
+ * Default subscription for every address in a request that does not set its own. Without it, an address is notified
+ * about all assets of its network in both directions.
  */
-export interface AddressDefaults {
-  /** Символы (`USDT`) или адреса контрактов; `null` — все активы сети, включая добавленные позже */
+export interface SubscriptionDefaults {
+  /** Asset symbols (`USDT`) or contract addresses. `null` — all assets of the network, including ones added later. */
   assets?: AssetSelection
-  /** `in` — только входящие, `out` — только исходящие, `both` — любые */
+  /** `in` — incoming only, `out` — outgoing only, `both` — either. */
   direction?: Direction
 }
 
-/** Адрес в сети — для снятия с мониторинга */
-export interface AddressRef {
-  /** Сеть: slug (`tron`, `ethereum`) или CAIP-2 (`eip155:1`) */
-  network: string
-  address: string
-}
-
-/** Новая подписка одного адреса; что не передано — не меняется */
-export type AddressSubscriptionUpdate = UpdateAddressesRequest['addresses'][number]
-
-export interface AddAddressesResult {
-  /** Добавлено новых адресов */
-  added: number
-  /** Уже отслеживались — их подписка не менялась */
-  alreadyWatched: number
-}
-
-export interface UpdateAddressesResult {
-  /** Найдено и изменено */
-  updated: number
-  /** Не на мониторинге у этого клиента */
-  notWatched: number
-}
-
-export interface RemoveAddressesResult {
-  /** Снято с мониторинга */
-  removed: number
-  /** Не отслеживались */
-  notWatched: number
-}
-
+/** Parameters of {@link AddressesResource.list}. */
 export interface ListAddressesParams {
-  /** Только эта сеть */
+  /** Only addresses on this network. */
   network?: string
-  /** Размер страницы, до 5000; по умолчанию 500 */
+  /** Page size, up to 5000. Defaults to 500. */
   limit?: number
-  /** Курсор: `next` прошлой страницы */
+  /** Cursor: `next` of the previous page. */
   after?: number
 }
 
-/**
- * Адреса клиента на мониторинге и их подписка: какие активы и в каком направлении сообщать.
- *
- * Новый адрес начинает отслеживаться через несколько секунд после добавления.
- */
+/** Addresses you monitor and their subscriptions: which assets and which direction you are notified about. */
 export class AddressesResource {
-  readonly #http: HttpClient
-  constructor(http: HttpClient) {
-    this.#http = http
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
   }
 
   /**
-   * Страница адресов с подпиской каждого.
+   * Lists monitored addresses, one page at a time.
    *
    * @example
    * ```ts
-   * const page = await monitoring.addresses.list(clientId, { network: 'tron' })
+   * const { items, next } = await monitoring.addresses.list({ network: 'tron' })
    * ```
    */
-  list(clientId: string, params: ListAddressesParams = {}, options?: RequestOptions): Promise<Page<Address, number>> {
-    return this.#http.request({ method: 'GET', path: `/v1/clients/${seg(clientId)}/addresses`, query: { ...params }, idempotent: true, options })
+  async list(params: ListAddressesParams = {}, options?: RequestOptions): Promise<AddressPage> {
+    return this.#scope.http.request({ method: 'GET', path: `${await this.#scope.clientPath()}/addresses`, query: { ...params }, idempotent: true, options })
   }
 
   /**
-   * Все адреса клиента — страница за страницей.
+   * Iterates over all monitored addresses, fetching pages as needed.
    *
    * @example
    * ```ts
-   * for await (const a of monitoring.addresses.iterate(clientId)) console.log(a.network, a.address, a.direction)
+   * for await (const address of monitoring.addresses.iterate({ network: 'tron' })) {
+   *   console.log(address.address, address.assets ?? 'all assets', address.direction)
+   * }
    * ```
    */
-  iterate(clientId: string, params: Omit<ListAddressesParams, 'after'> = {}, options?: RequestOptions): AsyncGenerator<Address, void, undefined> {
-    return paginate<Address, number>((after) => this.list(clientId, { ...params, after }, options))
+  iterate(params: Omit<ListAddressesParams, 'after'> = {}, options?: RequestOptions): AsyncGenerator<Address, void, undefined> {
+    return paginate<Address>((after) => this.list({ ...params, after }, options))
   }
 
   /**
-   * Ставит адреса на мониторинг. Уже отслеживаемые не меняются (подписку меняет {@link update}).
+   * Starts monitoring addresses. New addresses are picked up within seconds. Addresses that are already monitored are
+   * left unchanged — use {@link AddressesResource.update} to change their subscription.
    *
-   * Каждая пачка до {@link ADDRESS_BATCH_SIZE} адресов проверяется целиком: одна ошибка — пачка не записана.
-   * Больше 1000 адресов SDK отправит несколькими пачками по порядку; если пачка не прошла, предыдущие уже
-   * записаны, а номера в `error.details` указывают на элементы исходного массива. Повтор безопасен.
+   * Each batch of up to {@link ADDRESS_BATCH_SIZE} addresses is validated as a whole: if any item is invalid, the
+   * batch is not applied. Larger lists are sent in batches, in order; if a batch fails, the previous batches have
+   * already been applied, and the indexes in `error.details` refer to your original list. Retrying is safe.
    *
-   * @param defaults - подписка для элементов без своей; по умолчанию — все активы, обе стороны
-   * @throws {@link MonitoringApiError} 400 — адрес не той сети, неверный регистр TRON, неизвестный актив…
+   * @param addresses - Addresses to monitor. An EVM address is monitored per network: add it once per network.
+   * @param defaults - Subscription for addresses that do not set their own.
+   * @throws {@link MonitoringApiError} `400` with `details` when an address is invalid for its network or an asset
+   * is unknown.
    *
    * @example
    * ```ts
-   * // депозитные адреса: только входящие USDT
-   * await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…', label: 'user-42' }], {
+   * // deposit addresses: incoming USDT only
+   * await monitoring.addresses.add([{ network: 'tron', address: 'TA8Hg…', label: 'user-42' }], {
    *   assets: ['USDT'],
    *   direction: 'in',
    * })
    * ```
    */
-  async add(clientId: string, addresses: AddressInput[], defaults: AddressDefaults = {}, options?: RequestOptions): Promise<AddAddressesResult> {
+  async add(addresses: AddressInput[], defaults: SubscriptionDefaults = {}, options?: RequestOptions): Promise<AddAddressesResult> {
     const total: AddAddressesResult = { added: 0, alreadyWatched: 0 }
-    await this.#inBatches(addresses, async (batch) => {
-      const r = await this.#http.request<AddAddressesResult>({
-        method: 'POST',
-        path: `/v1/clients/${seg(clientId)}/addresses`,
-        body: { ...defaults, addresses: batch },
-        idempotent: true,
-        options,
-      })
+    await this.#batches(addresses, async (batch, path) => {
+      const r = await this.#scope.http.request<AddAddressesResult>({ method: 'POST', path: `${path}/addresses`, body: { ...defaults, addresses: batch }, idempotent: true, options })
       total.added += r.added
       total.alreadyWatched += r.alreadyWatched
     })
@@ -128,61 +107,57 @@ export class AddressesResource {
   }
 
   /**
-   * Меняет подписку отслеживаемых адресов: меняется только переданное. Без `assets` активы остаются прежними,
-   * `assets: null` — снова все активы сети.
+   * Changes the subscription of monitored addresses. Only the fields you pass are changed: omit `assets` to keep the
+   * current assets, or pass `null` to subscribe to all assets of the network.
    *
    * @example
    * ```ts
-   * await monitoring.addresses.update(clientId, [{ network: 'tron', address: 'T…' }], { direction: 'both' })
+   * await monitoring.addresses.update([{ network: 'tron', address: 'TA8Hg…' }], { direction: 'both' })
    * ```
    */
-  async update(clientId: string, addresses: AddressSubscriptionUpdate[], defaults: AddressDefaults = {}, options?: RequestOptions): Promise<UpdateAddressesResult> {
+  async update(addresses: AddressUpdate[], defaults: SubscriptionDefaults = {}, options?: RequestOptions): Promise<UpdateAddressesResult> {
     const total: UpdateAddressesResult = { updated: 0, notWatched: 0 }
-    await this.#inBatches(addresses, async (batch) => {
-      const r = await this.#http.request<UpdateAddressesResult>({
-        method: 'POST',
-        path: `/v1/clients/${seg(clientId)}/addresses/update`,
-        body: { ...defaults, addresses: batch },
-        idempotent: true,
-        options,
-      })
+    await this.#batches(addresses, async (batch, path) => {
+      const r = await this.#scope.http.request<UpdateAddressesResult>({ method: 'POST', path: `${path}/addresses/update`, body: { ...defaults, addresses: batch }, idempotent: true, options })
       total.updated += r.updated
       total.notWatched += r.notWatched
     })
     return total
   }
 
-  /** Снимает адреса с мониторинга. Больше 1000 — несколькими пачками */
-  async remove(clientId: string, addresses: AddressRef[], options?: RequestOptions): Promise<RemoveAddressesResult> {
+  /**
+   * Stops monitoring addresses.
+   *
+   * @example
+   * ```ts
+   * await monitoring.addresses.remove([{ network: 'tron', address: 'TA8Hg…' }])
+   * ```
+   */
+  async remove(addresses: AddressRef[], options?: RequestOptions): Promise<RemoveAddressesResult> {
     const total: RemoveAddressesResult = { removed: 0, notWatched: 0 }
-    await this.#inBatches(addresses, async (batch) => {
-      const r = await this.#http.request<RemoveAddressesResult>({
-        method: 'POST',
-        path: `/v1/clients/${seg(clientId)}/addresses/remove`,
-        body: { addresses: batch },
-        idempotent: true,
-        options,
-      })
+    await this.#batches(addresses, async (batch, path) => {
+      const r = await this.#scope.http.request<RemoveAddressesResult>({ method: 'POST', path: `${path}/addresses/remove`, body: { addresses: batch }, idempotent: true, options })
       total.removed += r.removed
       total.notWatched += r.notWatched
     })
     return total
   }
 
-  /** Пачками по порядку; номера ошибок по элементам — в нумерации исходного массива */
-  async #inBatches<T>(items: T[], send: (batch: T[]) => Promise<void>): Promise<void> {
+  /** Sends items in batches, in order; maps per-item error indexes back to the original list. */
+  async #batches<T>(items: T[], send: (batch: T[], clientPath: string) => Promise<void>): Promise<void> {
+    const path = await this.#scope.clientPath()
     for (let offset = 0; offset < items.length; offset += ADDRESS_BATCH_SIZE) {
       try {
-        await send(items.slice(offset, offset + ADDRESS_BATCH_SIZE))
-      } catch (e) {
-        if (!(e instanceof MonitoringApiError) || offset === 0) throw e
+        await send(items.slice(offset, offset + ADDRESS_BATCH_SIZE), path)
+      } catch (error) {
+        if (!(error instanceof MonitoringApiError) || offset === 0) throw error
         throw new MonitoringApiError({
-          status: e.status,
-          code: e.code,
-          message: `${e.message.replace(/ \(HTTP \d+, [\w-]+\)$/, '')}; addresses before #${offset} were already applied`,
-          details: e.details.map((d) => ({ ...d, index: d.index + offset })),
-          requestId: e.requestId,
-          body: e.body,
+          status: error.status,
+          code: error.code,
+          message: `${error.message.replace(/ \(HTTP \d+, [\w-]+\)$/, '')}; addresses before index ${offset} were already applied`,
+          details: error.details.map((d) => ({ ...d, index: d.index + offset })),
+          requestId: error.requestId,
+          body: error.body,
         })
       }
     }

package/src/resources/catalog.ts

@@ -1,47 +1,56 @@
-import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
-import type { Asset, Network } from '../generated/types.js'
+import { seg, type RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { Asset, AssetList, Network, NetworkList } from '../generated/types.js'
 
-/** Сети: TRON и EVM-сети с идентификаторами CAIP-2 */
+/** Supported networks. */
 export class NetworksResource {
-  readonly #http: HttpClient
-  constructor(http: HttpClient) {
-    this.#http = http
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
   }
 
-  /** Все сети. `enabled: false` — сеть описана, но не читается: вебхуков по ней нет */
+  /** Lists all networks. Transfers are monitored on networks with `enabled: true`. */
   async list(options?: RequestOptions): Promise<Network[]> {
-    const r = await this.#http.request<{ items: Network[] }>({ method: 'GET', path: '/v1/networks', idempotent: true, options })
+    const r = await this.#scope.http.request<NetworkList>({ method: 'GET', path: '/v1/networks', idempotent: true, options })
     return r.items
   }
 
-  /** Сеть по slug (`tron`) или CAIP-2 (`eip155:1`) */
+  /**
+   * Retrieves a network.
+   *
+   * @param network - Network slug (`tron`, `ethereum`) or CAIP-2 ID (`eip155:1`).
+   */
   get(network: string, options?: RequestOptions): Promise<Network> {
-    return this.#http.request({ method: 'GET', path: `/v1/networks/${seg(network)}`, idempotent: true, options })
+    return this.#scope.http.request({ method: 'GET', path: `/v1/networks/${seg(network)}`, idempotent: true, options })
   }
 }
 
-/** Активы: нативные монеты и токены. Вебхуки приходят о переводах включённых активов не меньше порога `minAmount` */
+/** Native coins and tokens. You are notified about transfers of enabled assets of at least `minAmount`. */
 export class AssetsResource {
-  readonly #http: HttpClient
-  constructor(http: HttpClient) {
-    this.#http = http
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
   }
 
   /**
-   * Активы — все или одной сети.
+   * Lists assets, optionally of one network.
    *
    * @example
    * ```ts
-   * const usdt = (await monitoring.assets.list({ network: 'tron' })).find((a) => a.symbol === 'USDT')
-   * formatUnits(webhook.tx.value, usdt!.decimals)
+   * const usdt = (await monitoring.assets.list({ network: 'tron' })).find((asset) => asset.symbol === 'USDT')
    * ```
    */
   async list(params: { network?: string } = {}, options?: RequestOptions): Promise<Asset[]> {
-    const r = await this.#http.request<{ items: Asset[] }>({ method: 'GET', path: '/v1/assets', query: params, idempotent: true, options })
+    const r = await this.#scope.http.request<AssetList>({ method: 'GET', path: '/v1/assets', query: params, idempotent: true, options })
     return r.items
   }
 
+  /** Retrieves an asset by ID. */
   get(assetId: number, options?: RequestOptions): Promise<Asset> {
-    return this.#http.request({ method: 'GET', path: `/v1/assets/${seg(assetId)}`, idempotent: true, options })
+    return this.#scope.http.request({ method: 'GET', path: `/v1/assets/${seg(assetId)}`, idempotent: true, options })
   }
 }

package/src/resources/deliveries.ts

@@ -1,69 +1,82 @@
-import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
-import { paginate, type Page } from '../core/pagination.js'
-import type { Delivery, DeliveryDetail, DeliveryStatus } from '../generated/types.js'
+import { seg, type RequestOptions } from '../core/http.js'
+import { paginate } from '../core/pagination.js'
+import type { Scope } from '../core/scope.js'
+import type { Delivery, DeliveryDetail, DeliveryPage, DeliveryStatus } from '../generated/types.js'
 
-/** Фильтры истории; все необязательны и сочетаются */
+/** Filters for webhook deliveries. All are optional and can be combined. */
 export interface DeliveryFilter {
-  /** `delivered` — вы ответили 2xx, `retrying` — будет повтор, `failed` — повторы исчерпаны */
+  /** `delivered`, `retrying` or `failed`. */
   status?: DeliveryStatus
-  /** Сеть: slug или CAIP-2 */
+  /** Network slug or CAIP-2 ID. */
   network?: string
-  /** Символ актива */
+  /** Asset symbol. */
   asset?: string
-  /** Хеш транзакции */
+  /** Transaction hash. */
   tx?: string
-  /** Отправитель или получатель */
+  /** Sender or recipient address. */
   address?: string
-  /** Первая попытка не раньше (дата или время) */
+  /** First attempt at or after this time. */
   since?: Date | string
-  /** Первая попытка раньше (не включая) */
+  /** First attempt before this time. */
   until?: Date | string
 }
 
+/** Parameters of {@link DeliveriesResource.list}. */
 export interface ListDeliveriesParams extends DeliveryFilter {
-  /** Размер страницы, до 500; по умолчанию 100 */
+  /** Page size, up to 500. Defaults to 100. */
   limit?: number
-  /** Курсор: `next` прошлой страницы */
+  /** Cursor: `next` of the previous page. */
   before?: number
 }
 
-const iso = (v: Date | string | undefined) => (v instanceof Date ? v.toISOString() : v)
+const iso = (value: Date | string | undefined) => (value instanceof Date ? value.toISOString() : value)
 
 /**
- * История вебхуков клиента: что, когда и куда отправлено, сколько было попыток и что вы ответили.
- * Повторы одного вебхука — одна запись. Хранится 90 дней.
+ * Every webhook sent to you: status, attempts and your endpoint's response. Retries of the same webhook are one
+ * delivery with an attempt count. Deliveries are kept for 90 days.
  */
 export class DeliveriesResource {
-  readonly #http: HttpClient
-  constructor(http: HttpClient) {
-    this.#http = http
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
   }
 
   /**
-   * Страница истории, новые сверху.
+   * Lists deliveries, newest first, one page at a time.
    *
    * @example
    * ```ts
-   * const { items } = await monitoring.deliveries.list(clientId, { status: 'failed', since: new Date(Date.now() - 86_400_000) })
+   * const { items } = await monitoring.deliveries.list({ status: 'failed', since: new Date(Date.now() - 86_400_000) })
    * ```
    */
-  list(clientId: string, params: ListDeliveriesParams = {}, options?: RequestOptions): Promise<Page<Delivery, number>> {
-    return this.#http.request({
+  async list(params: ListDeliveriesParams = {}, options?: RequestOptions): Promise<DeliveryPage> {
+    return this.#scope.http.request({
       method: 'GET',
-      path: `/v1/clients/${seg(clientId)}/deliveries`,
+      path: `${await this.#scope.clientPath()}/deliveries`,
       query: { ...params, since: iso(params.since), until: iso(params.until) },
       idempotent: true,
       options,
     })
   }
 
-  /** Вся история по фильтру — от новых к старым, страница за страницей */
-  iterate(clientId: string, filter: DeliveryFilter & { limit?: number } = {}, options?: RequestOptions): AsyncGenerator<Delivery, void, undefined> {
-    return paginate<Delivery, number>((before) => this.list(clientId, { ...filter, before }, options))
+  /**
+   * Iterates over all deliveries matching the filter, newest first.
+   *
+   * @example
+   * ```ts
+   * for await (const delivery of monitoring.deliveries.iterate({ status: 'failed' })) {
+   *   console.log(delivery.txId, delivery.attempts, delivery.lastHttpStatus ?? delivery.lastError)
+   * }
+   * ```
+   */
+  iterate(filter: DeliveryFilter & { limit?: number } = {}, options?: RequestOptions): AsyncGenerator<Delivery, void, undefined> {
+    return paginate<Delivery>((before) => this.list({ ...filter, before }, options))
   }
 
-  /** Одна запись с URL последней попытки и точным телом запроса */
-  get(clientId: string, deliveryId: number, options?: RequestOptions): Promise<DeliveryDetail> {
-    return this.#http.request({ method: 'GET', path: `/v1/clients/${seg(clientId)}/deliveries/${seg(deliveryId)}`, idempotent: true, options })
+  /** Retrieves a delivery with the URL of the last attempt and the exact request body. */
+  async get(deliveryId: number, options?: RequestOptions): Promise<DeliveryDetail> {
+    return this.#scope.http.request({ method: 'GET', path: `${await this.#scope.clientPath()}/deliveries/${seg(deliveryId)}`, idempotent: true, options })
   }
 }

package/src/resources/transactions.ts

@@ -1,33 +1,34 @@
-import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
+import { seg, type RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
 import type { Transaction } from '../generated/types.js'
 
-/** Любая транзакция сети по хешу — не только те, о которых пришёл вебхук */
+/** Any transaction on a supported network, by hash. */
 export class TransactionsResource {
-  readonly #http: HttpClient
-  constructor(http: HttpClient) {
-    this.#http = http
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
   }
 
   /**
-   * Статус, блок, подтверждения, финальность, комиссия и все переводы внутри транзакции; для ваших адресов —
-   * направление и вебхуки, которые мы по ней отправили.
-   *
-   * `final: true` — транзакцию уже не отменить: в TRON блок солидифицирован (около минуты), в EVM —
-   * финализирован (Ethereum — около 13 минут). Крупные суммы зачисляйте после `final`.
+   * Retrieves a transaction — not only the ones you were notified about: status, confirmations, finality, fee and
+   * every transfer inside it, plus your monitored addresses and the webhooks sent to you for it.
    *
-   * Не больше 60 запросов в минуту на ключ; при превышении SDK подождёт и повторит.
+   * `final: true` means the transaction can no longer be reverted: on TRON the block is solidified (about 1 minute),
+   * on EVM networks it is finalized (about 13 minutes on Ethereum). Credit large amounts once the transaction is final.
    *
-   * @param network - slug (`tron`, `ethereum`) или CAIP-2
-   * @param hash - EVM — `0x` + 64 hex; TRON — 64 hex (можно с `0x`)
-   * @throws {@link MonitoringApiError} 404 — такой транзакции в сети нет
+   * @param network - Network slug (`tron`, `ethereum`) or CAIP-2 ID.
+   * @param hash - EVM: `0x` followed by 64 hex characters. TRON: 64 hex characters.
+   * @throws {@link MonitoringApiError} `404` when the transaction does not exist on the network.
    *
    * @example
    * ```ts
-   * const tx = await monitoring.transactions.get('tron', webhook.tx.id)
-   * if (tx.status === 'success' && tx.final) credit(webhook)
+   * const tx = await monitoring.transactions.get('tron', event.tx.id)
+   * if (tx.status === 'success' && tx.final) await credit(event.tx)
    * ```
    */
   get(network: string, hash: string, options?: RequestOptions): Promise<Transaction> {
-    return this.#http.request({ method: 'GET', path: `/v1/networks/${seg(network)}/transactions/${seg(hash)}`, idempotent: true, options })
+    return this.#scope.http.request({ method: 'GET', path: `/v1/networks/${seg(network)}/transactions/${seg(hash)}`, idempotent: true, options })
   }
 }

package/src/resources/webhooks.ts

@@ -0,0 +1,36 @@
+import type { RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { TestWebhookRequest, TestWebhookResult } from '../generated/types.js'
+
+/** Test your webhook endpoint. To receive webhooks, see {@link parseWebhook}. */
+export class WebhooksResource {
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /**
+   * Sends a signed test webhook to your webhook URL and returns the outcome, the signature and the exact body sent.
+   * Test webhooks have `"test": true` in the body and the `x-webhook-test: 1` header — do not credit them.
+   * Limited to 10 per minute.
+   *
+   * @example
+   * ```ts
+   * const { delivery } = await monitoring.webhooks.sendTest({ asset: 'USDT' })
+   * if (!delivery.ok) console.error('Endpoint responded with', delivery.status ?? delivery.error)
+   * ```
+   */
+  async sendTest(params: TestWebhookRequest = {}, options?: RequestOptions): Promise<TestWebhookResult> {
+    return this.#scope.http.request({
+      method: 'POST',
+      path: `${await this.#scope.clientPath()}/webhooks/test`,
+      body: params,
+      idempotent: false,
+      // 502 means "your endpoint did not accept it": an outcome, not a failed request
+      acceptStatuses: [502],
+      options,
+    })
+  }
+}

package/src/units.ts

@@ -1,26 +1,26 @@
 /**
- * Суммы в API и вебхуках — строки в минимальных единицах (sun, wei; у USDT 6 знаков после запятой): uint256 не
- * помещается в `number`. Эти функции переводят их в привычный вид и обратно без потери точности.
- * Знаки после запятой актива — `decimals` из `monitoring.assets.list()`.
+ * Amounts in the API and in webhooks are decimal strings in the asset's smallest unit (sun, wei; USDT has 6 decimals),
+ * because uint256 values do not fit in a `number`. These helpers convert them without losing precision. The decimals
+ * of every asset are returned by `monitoring.assets.list()`.
  */
 
 const INTEGER = /^-?\d+$/
 const DECIMAL = /^(\d+)(?:\.(\d+))?$/
 
 /**
- * Минимальные единицы → строка в монетах.
+ * Converts an amount in the smallest unit to a decimal string.
  *
  * @example
  * ```ts
- * formatUnits('100000000', 6)            // '100'     — 100 USDT
- * formatUnits('1500000', 6)              // '1.5'
- * formatUnits('10090000000000000', 18)   // '0.01009' — ETH
+ * formatUnits('100000000', 6)          // '100'     — 100 USDT
+ * formatUnits('1500000', 6)            // '1.5'
+ * formatUnits('10090000000000000', 18) // '0.01009' — ETH
  * ```
  */
 export function formatUnits(value: string | bigint, decimals: number): string {
   assertDecimals(decimals)
   const raw = typeof value === 'bigint' ? value.toString() : value.trim()
-  if (!INTEGER.test(raw)) throw new RangeError(`formatUnits: integer in minimal units expected, got ${JSON.stringify(value)}`)
+  if (!INTEGER.test(raw)) throw new RangeError(`formatUnits: expected an integer amount in the smallest unit, got ${JSON.stringify(value)}`)
   const negative = raw.startsWith('-')
   const digits = (negative ? raw.slice(1) : raw).replace(/^0+(?=\d)/, '')
   if (decimals === 0) return (negative && digits !== '0' ? '-' : '') + digits
@@ -32,25 +32,25 @@ export function formatUnits(value: string | bigint, decimals: number): string {
 }
 
 /**
- * Строка в монетах → минимальные единицы.
+ * Converts a decimal string to an amount in the smallest unit.
  *
- * @throws RangeError — больше знаков после запятой, чем у актива, или не число
+ * @throws RangeError when the amount is not a non-negative decimal or has more decimal places than the asset.
  *
  * @example
  * ```ts
- * parseUnits('1.5', 6)   // '1500000'
- * parseUnits('100', 6)   // '100000000'
+ * parseUnits('1.5', 6) // '1500000'
+ * parseUnits('100', 6) // '100000000'
  * ```
  */
 export function parseUnits(amount: string, decimals: number): string {
   assertDecimals(decimals)
   const m = DECIMAL.exec(amount.trim())
-  if (!m) throw new RangeError(`parseUnits: non-negative decimal expected, got ${JSON.stringify(amount)}`)
+  if (!m) throw new RangeError(`parseUnits: expected a non-negative decimal, got ${JSON.stringify(amount)}`)
   const fraction = m[2] ?? ''
   if (fraction.length > decimals) throw new RangeError(`parseUnits: ${amount} has more than ${decimals} decimal places`)
   return BigInt(m[1]! + fraction.padEnd(decimals, '0')).toString()
 }
 
 function assertDecimals(decimals: number): void {
-  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) throw new RangeError(`decimals: integer 0..255 expected, got ${decimals}`)
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) throw new RangeError(`decimals: expected an integer from 0 to 255, got ${decimals}`)
 }