@v3finance/monitoring-sdk 0.0.0-stage → 0.1.0

package/src/generated/types.ts

@@ -0,0 +1,355 @@
+// Generated from openapi/openapi.json by scripts/generate.ts — do not edit by hand.
+// chain-events API 1.0.0. Regenerate: npm run spec:update && npm run generate
+
+export interface ApiErrorBody {
+  error: {
+    /** @example "invalid_request" */
+    code: string
+    message: string
+    details?: Array<{
+      index: number
+      message: string
+    }>
+  }
+}
+
+export interface User {
+  id: string
+  email: string
+  name: string
+  role?: "admin" | "user"
+  banned?: boolean
+  createdAt?: string
+}
+
+export interface Identity {
+  actor: {
+    /** user — пользователь, client-key — ключ клиента */
+    kind: "user" | "client-key" | "admin"
+    via?: "session" | "api-key" | "token"
+    userId?: string | null
+    clientId?: string
+    keyId?: string
+  }
+  user: User | null
+  memberships: Array<{
+    clientId: string
+    role: "owner" | "admin" | "member"
+  }>
+}
+
+export interface ApiKey {
+  id: string
+  name: string | null
+  /** начало ключа — чтобы узнать его */
+  start: string
+  enabled: boolean
+  expiresAt: string | null
+  lastUsedAt: string | null
+  createdAt: string
+}
+
+export interface IssueKeyRequest {
+  /** length: 0..100 */
+  name?: string
+  /**
+   * срок; без него — бессрочный
+   *
+   * range: 1..3650
+   */
+  expiresInDays?: number
+}
+
+export interface IssuedKey {
+  id: string
+  /** полный ключ — показывается один раз */
+  key: string
+  start: string
+  name: string | null
+  expiresAt: string | null
+}
+
+export interface Network {
+  id: number
+  /** @example "tron" */
+  slug: string
+  /** @example "tron:0x2b6653dc" */
+  caip2: string
+  chainId: number
+  name: string
+  shortName: string | null
+  /** 1 — L1, 2 — L2 */
+  layer: 1 | 2
+  parent: string | null
+  l2Type: string | null
+  l2Stack: string | null
+  isTestnet: boolean
+  explorerUrl: string | null
+  /** сервис читает сеть: если false, вебхуков по ней нет */
+  enabled: boolean
+}
+
+export interface Asset {
+  id: number
+  network: string
+  caip19: string
+  standard: "native" | "erc20" | "trc20"
+  contract: string | null
+  symbol: string
+  name: string
+  decimals: number
+  /** порог включительно, в минимальных единицах: меньшие переводы не сообщаются */
+  minAmount: string
+  /** включён: о его переводах приходят вебхуки */
+  enabled: boolean
+}
+
+export interface Client {
+  id: string
+  name: string | null
+  webhookUrl: string
+  /** disabled — вебхуки не отправляются */
+  status: "active" | "disabled"
+  createdAt: string
+}
+
+export interface Member {
+  userId: string
+  email: string
+  name: string
+  role: "owner" | "admin" | "member"
+  createdAt: string
+}
+
+/** in — адрес получатель, out — отправитель, both — любой */
+export type Direction = "in" | "out" | "both"
+
+/** символы (`USDT`) или адреса контрактов; null — все активы сети, включая добавленные позже */
+export type AssetSelection = string[] | null
+
+export interface AddressInput {
+  /** slug или CAIP-2 */
+  network: string
+  address: string
+  /**
+   * ваша метка: id пользователя, номер счёта
+   *
+   * length: 0..200
+   */
+  label?: string
+  assets?: AssetSelection
+  direction?: Direction
+}
+
+export interface AddAddressesRequest {
+  /** items: 1..1000 */
+  addresses: AddressInput[]
+  assets?: AssetSelection
+  direction?: Direction
+}
+
+export interface UpdateAddressesRequest {
+  /** items: 1..1000 */
+  addresses: Array<{
+    network: string
+    address: string
+    assets?: AssetSelection
+    direction?: Direction
+  }>
+  assets?: AssetSelection
+  direction?: Direction
+}
+
+export interface Address {
+  id: number
+  network: string
+  caip10: string
+  address: string
+  label: string | null
+  /** символы активов подписки; null — все */
+  assets: string[] | null
+  direction: Direction
+  createdAt: string
+}
+
+/** delivered — вы ответили 2xx; retrying — последняя попытка не удалась, будет повтор; failed — повторы исчерпаны */
+export type DeliveryStatus = "delivered" | "retrying" | "failed"
+
+export interface Delivery {
+  id: number
+  clientId: string
+  network: string
+  asset: string
+  contract: string
+  txId: string
+  logIndex: number | null
+  block: number
+  /** время блока, мс */
+  blockTime: number
+  from: string
+  to: string
+  value: string
+  status: DeliveryStatus
+  attempts: number
+  lastHttpStatus: number | null
+  lastError: string | null
+  lastDurationMs: number | null
+  firstAttemptAt: string
+  lastAttemptAt: string
+  deliveredAt: string | null
+}
+
+export type DeliveryDetail = Delivery & {
+  /** куда ушла последняя попытка */
+  url: string
+  /** точное тело запроса */
+  body: string
+}
+
+export interface TxTransfer {
+  /** native — монета самой транзакцией; token — событие Transfer; internal — TRX изнутри контракта (TRON); trc10 — токен TRC-10 */
+  kind: "native" | "token" | "internal" | "trc10"
+  asset: string | null
+  /** адрес контракта, native или id токена TRC-10 */
+  contract: string
+  from: string
+  to: string
+  value: string
+  logIndex?: number
+  /** актив отслеживается: о таких переводах приходят вебхуки (если сумма не меньше порога) */
+  tracked: boolean
+}
+
+export interface Transaction {
+  network: string
+  caip2: string
+  txId: string
+  /** pending — ещё не в блоке */
+  status: "success" | "failed" | "pending"
+  failure: string | null
+  block: number | null
+  blockTime: number | null
+  /** от текущей головы сети; 0 — не в блоке */
+  confirmations: number
+  /** транзакцию уже не отменить */
+  final: boolean
+  /** кто подписал */
+  from: string
+  to: string | null
+  /** TRON — тип контракта (TransferContract, TriggerSmartContract…); EVM — transfer, contract_call, contract_creation */
+  type: string
+  /** нативная монета самой транзакции */
+  value: string
+  fee: {
+    asset: string
+    value: string
+  } | null
+  transfers: TxTransfer[]
+  /** ваши адреса на мониторинге в этой транзакции */
+  watched: Array<{
+    clientId: string
+    address: string
+    direction: Direction
+  }>
+  /** наши вебхуки вам по этой транзакции */
+  webhooks: Array<{
+    id: number
+    clientId: string
+    asset: string
+    value: string
+    status: DeliveryStatus
+    attempts: number
+    deliveredAt: string | null
+  }>
+}
+
+export interface WebhookTx {
+  /**
+   * сеть в верхнем регистре
+   * @example "TRON"
+   * @example "ETHEREUM"
+   */
+  network: string
+  /** @example "USDT" */
+  asset: string
+  /** адрес контракта или native */
+  contract: string
+  /** всегда TOPUP — и для входящего, и для исходящего: направление — по from и to */
+  type: "TOPUP"
+  /** хеш транзакции */
+  id: string
+  block: number
+  /** время блока, мс */
+  timestamp: number
+  from: string
+  to: string
+  /** в минимальных единицах */
+  value: string
+  /** у переводов токенов EVM: в одной транзакции их бывает несколько */
+  logIndex?: number
+}
+
+export interface WebhookPayload {
+  tx: WebhookTx
+  /** только у тестового вебхука — не зачислять */
+  test?: true
+}
+
+export interface TestWebhookRequest {
+  /** @defaultValue "USDT" */
+  asset?: "USDT" | "A7A5" | "TRX"
+  /** адрес TRON */
+  from?: string
+  /** адрес TRON */
+  to?: string
+  /** в минимальных единицах */
+  value?: string
+}
+
+export interface TestDelivery {
+  ok: boolean
+  /** HTTP-код вашего ответа */
+  status?: number
+  error?: string
+  durationMs: number
+}
+
+export interface TestWebhookResult {
+  delivery: TestDelivery
+  /** x-signature — сверьте со своим HMAC */
+  signature: string
+  /** точное тело запроса */
+  body: string
+}
+
+export interface LegacyAddresses {
+  /** items: 0..1000 */
+  addresses: string[]
+}
+
+export interface LegacyClientResult {
+  ok: true
+  client: {
+    id: string
+    webhookUrl: string
+    addresses: string[]
+  }
+}
+
+export interface LegacyError {
+  ok: false
+  error: string
+  details?: Array<{
+    index: number
+    message: string
+  }>
+}
+
+export interface LegacyTestResult {
+  ok: boolean
+  clientId: string
+  webhookUrl: string
+  delivery: TestDelivery
+  signature: string
+  body: string
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Официальный SDK API мониторинга адресов V3 Finance (https://monitoring.v3.finance): TRON и EVM-сети,
+ * подписанные вебхуки о переводах, история доставок, транзакции с подтверждениями и финальностью.
+ *
+ * Справочник API — https://monitoring.v3.finance/docs
+ *
+ * @packageDocumentation
+ */
+
+export { MonitoringClient } from './client.js'
+export type { ClientOptions, RequestOptions } from './core/http.js'
+export type { Page } from './core/pagination.js'
+export {
+  MonitoringApiError,
+  MonitoringConnectionError,
+  MonitoringError,
+  MonitoringTimeoutError,
+  WebhookSignatureError,
+  type ErrorDetail,
+} from './core/errors.js'
+
+export { AccountResource, AuthResource, PersonalKeysResource, type SignInResult } from './resources/account.js'
+export {
+  ADDRESS_BATCH_SIZE,
+  AddressesResource,
+  type AddAddressesResult,
+  type AddressDefaults,
+  type AddressRef,
+  type AddressSubscriptionUpdate,
+  type ListAddressesParams,
+  type RemoveAddressesResult,
+  type UpdateAddressesResult,
+} from './resources/addresses.js'
+export { AssetsResource, NetworksResource } from './resources/catalog.js'
+export {
+  ClientKeysResource,
+  ClientsResource,
+  type ListClientsParams,
+  type RotateSecretParams,
+  type RotateSecretResult,
+  type UpdateClientParams,
+} from './resources/clients.js'
+export { DeliveriesResource, type DeliveryFilter, type ListDeliveriesParams } from './resources/deliveries.js'
+export { TransactionsResource } from './resources/transactions.js'
+
+export {
+  isTestWebhook,
+  parseWebhook,
+  signWebhookBody,
+  verifyWebhookSignature,
+  WEBHOOK_HEADERS,
+  webhookIdempotencyKey,
+  type SignatureSource,
+  type WebhookBody,
+} from './webhooks.js'
+export { formatUnits, parseUnits } from './units.js'
+export { DEFAULT_BASE_URL, SDK_VERSION } from './version.js'
+
+// Типы запросов и ответов — из спецификации OpenAPI (src/generated/types.ts)
+export type * from './generated/types.js'

package/src/resources/account.ts

@@ -0,0 +1,87 @@
+import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
+import type { ApiKey, Identity, IssueKeyRequest, IssuedKey, User } from '../generated/types.js'
+
+/** Личные ключи: действуют от вашего имени с вашими правами — всё, что вы можете в панели */
+export class PersonalKeysResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  async list(options?: RequestOptions): Promise<ApiKey[]> {
+    const r = await this.#http.request<{ items: ApiKey[] }>({ method: 'GET', path: '/v1/me/keys', idempotent: true, options })
+    return r.items
+  }
+
+  /**
+   * Выпускает личный ключ. Работает только с клиентом, вошедшим по паролю ({@link MonitoringClient.signIn}):
+   * ключ не может выпустить себе замену. Полный ключ — в `key`, показывается один раз.
+   */
+  create(params: IssueKeyRequest = {}, options?: RequestOptions): Promise<IssuedKey> {
+    return this.#http.request({ method: 'POST', path: '/v1/me/keys', body: params, idempotent: false, options })
+  }
+
+  async revoke(keyId: string, options?: RequestOptions): Promise<void> {
+    await this.#http.request({ method: 'DELETE', path: `/v1/me/keys/${seg(keyId)}`, idempotent: true, options })
+  }
+}
+
+/** Кто вы и ваши ключи */
+export class AccountResource {
+  readonly #http: HttpClient
+  /** Личные ключи */
+  readonly keys: PersonalKeysResource
+
+  constructor(http: HttpClient) {
+    this.#http = http
+    this.keys = new PersonalKeysResource(http)
+  }
+
+  /**
+   * Кто сделал запрос: способ входа, пользователь и участие в клиентах с ролями. Для ключа клиента —
+   * `actor.kind === 'client-key'` и `actor.clientId`.
+   *
+   * @example
+   * ```ts
+   * const { actor } = await monitoring.account.me()
+   * const clientId = actor.clientId // для ключа клиента
+   * ```
+   */
+  me(options?: RequestOptions): Promise<Identity> {
+    return this.#http.request({ method: 'GET', path: '/v1/me', idempotent: true, options })
+  }
+}
+
+/** Результат входа по паролю */
+export interface SignInResult {
+  /** Токен сессии: передайте его в `sessionToken` или используйте готовый клиент из {@link MonitoringClient.signIn} */
+  token: string
+  user: User
+}
+
+/** Сессия: выход и смена пароля. Нужен клиент, вошедший по паролю */
+export class AuthResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /** Текущая сессия и пользователь; `null` — сессии нет или она истекла */
+  session(options?: RequestOptions): Promise<{ session: Record<string, unknown>; user: User } | null> {
+    return this.#http.request({ method: 'GET', path: '/api/auth/get-session', idempotent: true, options })
+  }
+
+  /** Завершает сессию; токен перестаёт работать */
+  async signOut(options?: RequestOptions): Promise<void> {
+    await this.#http.request({ method: 'POST', path: '/api/auth/sign-out', body: {}, idempotent: true, options })
+  }
+
+  /**
+   * Меняет пароль. Ключом пароль не сменить — только в сессии.
+   *
+   * @param params.revokeOtherSessions - завершить остальные сессии
+   */
+  async changePassword(params: { currentPassword: string; newPassword: string; revokeOtherSessions?: boolean }, options?: RequestOptions): Promise<void> {
+    await this.#http.request({ method: 'POST', path: '/api/auth/change-password', body: params, idempotent: false, options })
+  }
+}

package/src/resources/addresses.ts

@@ -0,0 +1,190 @@
+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'
+
+/** Столько адресов API принимает за один запрос; больше SDK разбивает на пачки сам */
+export const ADDRESS_BATCH_SIZE = 1000
+
+/**
+ * Подписка по умолчанию для всех адресов запроса — действует на элементы, где своей нет.
+ * Без неё адрес получает все активы сети в обе стороны.
+ */
+export interface AddressDefaults {
+  /** Символы (`USDT`) или адреса контрактов; `null` — все активы сети, включая добавленные позже */
+  assets?: AssetSelection
+  /** `in` — только входящие, `out` — только исходящие, `both` — любые */
+  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
+}
+
+export interface ListAddressesParams {
+  /** Только эта сеть */
+  network?: string
+  /** Размер страницы, до 5000; по умолчанию 500 */
+  limit?: number
+  /** Курсор: `next` прошлой страницы */
+  after?: number
+}
+
+/**
+ * Адреса клиента на мониторинге и их подписка: какие активы и в каком направлении сообщать.
+ *
+ * Новый адрес начинает отслеживаться через несколько секунд после добавления.
+ */
+export class AddressesResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /**
+   * Страница адресов с подпиской каждого.
+   *
+   * @example
+   * ```ts
+   * const page = await monitoring.addresses.list(clientId, { 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 })
+  }
+
+  /**
+   * Все адреса клиента — страница за страницей.
+   *
+   * @example
+   * ```ts
+   * for await (const a of monitoring.addresses.iterate(clientId)) console.log(a.network, a.address, a.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))
+  }
+
+  /**
+   * Ставит адреса на мониторинг. Уже отслеживаемые не меняются (подписку меняет {@link update}).
+   *
+   * Каждая пачка до {@link ADDRESS_BATCH_SIZE} адресов проверяется целиком: одна ошибка — пачка не записана.
+   * Больше 1000 адресов SDK отправит несколькими пачками по порядку; если пачка не прошла, предыдущие уже
+   * записаны, а номера в `error.details` указывают на элементы исходного массива. Повтор безопасен.
+   *
+   * @param defaults - подписка для элементов без своей; по умолчанию — все активы, обе стороны
+   * @throws {@link MonitoringApiError} 400 — адрес не той сети, неверный регистр TRON, неизвестный актив…
+   *
+   * @example
+   * ```ts
+   * // депозитные адреса: только входящие USDT
+   * await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…', label: 'user-42' }], {
+   *   assets: ['USDT'],
+   *   direction: 'in',
+   * })
+   * ```
+   */
+  async add(clientId: string, addresses: AddressInput[], defaults: AddressDefaults = {}, 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,
+      })
+      total.added += r.added
+      total.alreadyWatched += r.alreadyWatched
+    })
+    return total
+  }
+
+  /**
+   * Меняет подписку отслеживаемых адресов: меняется только переданное. Без `assets` активы остаются прежними,
+   * `assets: null` — снова все активы сети.
+   *
+   * @example
+   * ```ts
+   * await monitoring.addresses.update(clientId, [{ network: 'tron', address: 'T…' }], { direction: 'both' })
+   * ```
+   */
+  async update(clientId: string, addresses: AddressSubscriptionUpdate[], defaults: AddressDefaults = {}, 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,
+      })
+      total.updated += r.updated
+      total.notWatched += r.notWatched
+    })
+    return total
+  }
+
+  /** Снимает адреса с мониторинга. Больше 1000 — несколькими пачками */
+  async remove(clientId: string, 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,
+      })
+      total.removed += r.removed
+      total.notWatched += r.notWatched
+    })
+    return total
+  }
+
+  /** Пачками по порядку; номера ошибок по элементам — в нумерации исходного массива */
+  async #inBatches<T>(items: T[], send: (batch: T[]) => Promise<void>): Promise<void> {
+    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
+        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,
+        })
+      }
+    }
+  }
+}