@v3finance/monitoring-sdk 0.1.0 → 0.2.0

package/src/generated/types.ts

@@ -1,12 +1,18 @@
 // 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
+// V3 Finance Monitoring API 1.0.0. Regenerate: npm run spec:update && npm run generate
 
 export interface ApiErrorBody {
   error: {
-    /** @example "invalid_request" */
+    /**
+     * Machine-readable error code.
+     * @example "invalid_request"
+     */
     code: string
+    /** Human-readable description. */
     message: string
+    /** Per-item problems of a batch request. */
     details?: Array<{
+      /** Index of the item in the request. */
       index: number
       message: string
     }>
@@ -24,12 +30,14 @@ export interface User {
 
 export interface Identity {
   actor: {
-    /** user — пользователь, client-key — ключ клиента */
-    kind: "user" | "client-key" | "admin"
-    via?: "session" | "api-key" | "token"
-    userId?: string | null
+    /** `client-key` for a client API key. */
+    kind: "client-key" | "user" | "admin"
+    /** Your client ID (client API keys). */
     clientId?: string
+    /** ID of the API key (client API keys). */
     keyId?: string
+    userId?: string | null
+    via?: "session" | "api-key" | "token"
   }
   user: User | null
   memberships: Array<{
@@ -38,101 +46,82 @@ export interface Identity {
   }>
 }
 
-export interface ApiKey {
+export interface Client {
+  /** Client ID. */
   id: string
   name: string | null
-  /** начало ключа — чтобы узнать его */
-  start: string
-  enabled: boolean
-  expiresAt: string | null
-  lastUsedAt: string | null
+  /** Where webhooks are sent. */
+  webhookUrl: string
+  /** `disabled` — webhooks are not sent. */
+  status: "active" | "disabled"
+  /** format: date-time */
   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" */
+  /**
+   * Network identifier used across the API.
+   * @example "tron"
+   */
   slug: string
-  /** @example "tron:0x2b6653dc" */
+  /**
+   * CAIP-2 chain ID.
+   * @example "tron:0x2b6653dc"
+   */
   caip2: string
   chainId: number
   name: string
   shortName: string | null
-  /** 1 — L1, 2 — L2 */
+  /** 1 for L1 networks, 2 for L2 rollups. */
   layer: 1 | 2
   parent: string | null
   l2Type: string | null
   l2Stack: string | null
   isTestnet: boolean
   explorerUrl: string | null
-  /** сервис читает сеть: если false, вебхуков по ней нет */
+  /** Transfers on this network are monitored. */
   enabled: boolean
 }
 
+export interface NetworkList {
+  items: Network[]
+}
+
 export interface Asset {
   id: number
+  /** Network slug. */
   network: string
+  /** CAIP-19 asset ID. */
   caip19: string
   standard: "native" | "erc20" | "trc20"
   contract: string | null
+  /** @example "USDT" */
   symbol: string
   name: string
   decimals: number
-  /** порог включительно, в минимальных единицах: меньшие переводы не сообщаются */
+  /** Smallest transfer you are notified about, in the smallest unit (inclusive). */
   minAmount: string
-  /** включён: о его переводах приходят вебхуки */
+  /** Transfers of this asset are monitored. */
   enabled: boolean
 }
 
-export interface Client {
-  id: string
-  name: string | null
-  webhookUrl: string
-  /** disabled — вебхуки не отправляются */
-  status: "active" | "disabled"
-  createdAt: string
+export interface AssetList {
+  items: Asset[]
 }
 
-export interface Member {
-  userId: string
-  email: string
-  name: string
-  role: "owner" | "admin" | "member"
-  createdAt: string
-}
-
-/** in — адрес получатель, out — отправитель, both — любой */
+/** `in` — the address receives, `out` — the address sends, `both` — either. */
 export type Direction = "in" | "out" | "both"
 
-/** символы (`USDT`) или адреса контрактов; null — все активы сети, включая добавленные позже */
+/** Asset symbols (`USDT`) or contract addresses. `null` — all assets of the network, including ones added later. */
 export type AssetSelection = string[] | null
 
 export interface AddressInput {
-  /** slug или CAIP-2 */
+  /** Network slug or CAIP-2 ID. */
   network: string
   address: string
   /**
-   * ваша метка: id пользователя, номер счёта
+   * Your reference, e.g. a user or account ID.
    *
    * length: 0..200
    */
@@ -148,31 +137,74 @@ export interface AddAddressesRequest {
   direction?: Direction
 }
 
+export interface AddAddressesResult {
+  /** Addresses that started being monitored. */
+  added: number
+  /** Addresses that were already monitored and left unchanged. */
+  alreadyWatched: number
+}
+
+export interface AddressUpdate {
+  network: string
+  address: string
+  assets?: AssetSelection
+  direction?: Direction
+}
+
 export interface UpdateAddressesRequest {
   /** items: 1..1000 */
-  addresses: Array<{
-    network: string
-    address: string
-    assets?: AssetSelection
-    direction?: Direction
-  }>
+  addresses: AddressUpdate[]
   assets?: AssetSelection
   direction?: Direction
 }
 
+export interface UpdateAddressesResult {
+  /** Addresses whose subscription was changed. */
+  updated: number
+  /** Addresses that are not monitored. */
+  notWatched: number
+}
+
+export interface AddressRef {
+  /** Network slug or CAIP-2 ID. */
+  network: string
+  address: string
+}
+
+export interface RemoveAddressesRequest {
+  /** items: 1..1000 */
+  addresses: AddressRef[]
+}
+
+export interface RemoveAddressesResult {
+  /** Addresses that stopped being monitored. */
+  removed: number
+  /** Addresses that were not monitored. */
+  notWatched: number
+}
+
 export interface Address {
   id: number
   network: string
+  /** CAIP-10 account ID. */
   caip10: string
   address: string
   label: string | null
-  /** символы активов подписки; null — все */
+  /** Subscribed asset symbols; `null` — all assets. */
   assets: string[] | null
   direction: Direction
+  /** format: date-time */
   createdAt: string
 }
 
-/** delivered — вы ответили 2xx; retrying — последняя попытка не удалась, будет повтор; failed — повторы исчерпаны */
+/** A page of addresses. */
+export interface AddressPage {
+  items: Address[]
+  /** Cursor for the next page — pass it as `after`. `null` when there are no more pages. */
+  next: number | null
+}
+
+/** `delivered` — you responded with 2xx; `retrying` — the last attempt failed and will be retried; `failed` — all attempts failed. */
 export type DeliveryStatus = "delivered" | "retrying" | "failed"
 
 export interface Delivery {
@@ -181,42 +213,54 @@ export interface Delivery {
   network: string
   asset: string
   contract: string
+  /** Transaction hash. */
   txId: string
   logIndex: number | null
   block: number
-  /** время блока, мс */
+  /** Block time, milliseconds since epoch. */
   blockTime: number
   from: string
   to: string
+  /** Amount in the smallest unit. */
   value: string
   status: DeliveryStatus
   attempts: number
   lastHttpStatus: number | null
   lastError: string | null
   lastDurationMs: number | null
+  /** format: date-time */
   firstAttemptAt: string
+  /** format: date-time */
   lastAttemptAt: string
   deliveredAt: string | null
 }
 
 export type DeliveryDetail = Delivery & {
-  /** куда ушла последняя попытка */
+  /** URL of the last attempt. */
   url: string
-  /** точное тело запроса */
+  /** Exact request body. */
   body: string
 }
 
+/** A page of deliveries, newest first. */
+export interface DeliveryPage {
+  items: Delivery[]
+  /** Cursor for the next page — pass it as `before`. `null` when there are no more pages. */
+  next: number | null
+}
+
 export interface TxTransfer {
-  /** native — монета самой транзакцией; token — событие Transfer; internal — TRX изнутри контракта (TRON); trc10 — токен TRC-10 */
+  /** `native` — sent by the transaction itself; `token` — a token Transfer event; `internal` — TRX sent by a contract; `trc10` — a TRC-10 token. */
   kind: "native" | "token" | "internal" | "trc10"
   asset: string | null
-  /** адрес контракта, native или id токена TRC-10 */
+  /** Token contract address, `native`, or the TRC-10 token ID. */
   contract: string
   from: string
   to: string
+  /** Amount in the smallest unit. */
   value: string
   logIndex?: number
-  /** актив отслеживается: о таких переводах приходят вебхуки (если сумма не меньше порога) */
+  /** The asset is monitored: transfers of at least its `minAmount` are notified. */
   tracked: boolean
 }
 
@@ -224,34 +268,34 @@ export interface Transaction {
   network: string
   caip2: string
   txId: string
-  /** pending — ещё не в блоке */
+  /** `pending` — not yet included in a block. */
   status: "success" | "failed" | "pending"
   failure: string | null
   block: number | null
   blockTime: number | null
-  /** от текущей головы сети; 0 — не в блоке */
+  /** Blocks since inclusion, counting the block itself; `0` when pending. */
   confirmations: number
-  /** транзакцию уже не отменить */
+  /** The transaction can no longer be reverted. */
   final: boolean
-  /** кто подписал */
+  /** Signer of the transaction. */
   from: string
   to: string | null
-  /** TRON — тип контракта (TransferContract, TriggerSmartContract…); EVM — transfer, contract_call, contract_creation */
+  /** TRON contract type (`TransferContract`, `TriggerSmartContract`, …) or, on EVM networks, `transfer`, `contract_call` or `contract_creation`. */
   type: string
-  /** нативная монета самой транзакции */
+  /** Native amount sent by the transaction itself. */
   value: string
   fee: {
     asset: string
     value: string
   } | null
   transfers: TxTransfer[]
-  /** ваши адреса на мониторинге в этой транзакции */
+  /** Your monitored addresses involved in the transaction. */
   watched: Array<{
     clientId: string
     address: string
     direction: Direction
   }>
-  /** наши вебхуки вам по этой транзакции */
+  /** Webhooks sent to you for this transaction. */
   webhooks: Array<{
     id: number
     clientId: string
@@ -265,91 +309,61 @@ export interface Transaction {
 
 export interface WebhookTx {
   /**
-   * сеть в верхнем регистре
+   * Network slug in upper case.
    * @example "TRON"
    * @example "ETHEREUM"
    */
   network: string
   /** @example "USDT" */
   asset: string
-  /** адрес контракта или native */
+  /** Token contract address or `native`. */
   contract: string
-  /** всегда TOPUP — и для входящего, и для исходящего: направление — по from и to */
+  /** Always `TOPUP`, for both directions: compare `from` and `to` with your addresses. */
   type: "TOPUP"
-  /** хеш транзакции */
+  /** Transaction hash. */
   id: string
   block: number
-  /** время блока, мс */
+  /** Block time, milliseconds since epoch. */
   timestamp: number
   from: string
   to: string
-  /** в минимальных единицах */
+  /** Amount in the smallest unit. */
   value: string
-  /** у переводов токенов EVM: в одной транзакции их бывает несколько */
+  /** Position of the transfer in the block, for EVM token transfers. */
   logIndex?: number
 }
 
 export interface WebhookPayload {
   tx: WebhookTx
-  /** только у тестового вебхука — не зачислять */
+  /** Present on test webhooks only. */
   test?: true
 }
 
 export interface TestWebhookRequest {
   /** @defaultValue "USDT" */
   asset?: "USDT" | "A7A5" | "TRX"
-  /** адрес TRON */
+  /** TRON address. */
   from?: string
-  /** адрес TRON */
+  /** TRON address. */
   to?: string
-  /** в минимальных единицах */
+  /** Amount in the smallest unit. */
   value?: string
 }
 
 export interface TestDelivery {
+  /** Your endpoint responded with 2xx. */
   ok: boolean
-  /** HTTP-код вашего ответа */
+  /** Status code of your response. */
   status?: number
+  /** Connection error. */
   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
+  /** Value of the `x-signature` header. */
   signature: string
+  /** Exact request body. */
   body: string
 }

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * Официальный SDK API мониторинга адресов V3 Finance (https://monitoring.v3.finance): TRON и EVM-сети,
- * подписанные вебхуки о переводах, история доставок, транзакции с подтверждениями и финальностью.
+ * Official TypeScript SDK for the V3 Finance Monitoring API: monitor addresses on TRON and EVM networks and receive
+ * signed webhooks for every incoming and outgoing transfer.
  *
- * Справочник API — https://monitoring.v3.finance/docs
+ * API reference: https://monitoring.v3.finance/docs
  *
  * @packageDocumentation
  */
@@ -19,29 +19,12 @@ export {
   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 { AccountResource } from './resources/account.js'
+export { ADDRESS_BATCH_SIZE, AddressesResource, type ListAddressesParams, type SubscriptionDefaults } 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 { WebhooksResource } from './resources/webhooks.js'
 
 export {
   isTestWebhook,
@@ -56,5 +39,5 @@ export {
 export { formatUnits, parseUnits } from './units.js'
 export { DEFAULT_BASE_URL, SDK_VERSION } from './version.js'
 
-// Типы запросов и ответов — из спецификации OpenAPI (src/generated/types.ts)
+// Request and response types, generated from the OpenAPI specification
 export type * from './generated/types.js'

package/src/resources/account.ts

@@ -1,87 +1,33 @@
-import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
-import type { ApiKey, Identity, IssueKeyRequest, IssuedKey, User } from '../generated/types.js'
+import type { RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { Client } 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 })
-  }
-}
-
-/** Кто вы и ваши ключи */
+/** Your client: the account your API key belongs to. */
 export class AccountResource {
-  readonly #http: HttpClient
-  /** Личные ключи */
-  readonly keys: PersonalKeysResource
+  readonly #scope: Scope
+  readonly #resolveId: () => Promise<string>
 
-  constructor(http: HttpClient) {
-    this.#http = http
-    this.keys = new PersonalKeysResource(http)
+  /** @internal */
+  constructor(scope: Scope, resolveId: () => Promise<string>) {
+    this.#scope = scope
+    this.#resolveId = resolveId
   }
 
   /**
-   * Кто сделал запрос: способ входа, пользователь и участие в клиентах с ролями. Для ключа клиента —
-   * `actor.kind === 'client-key'` и `actor.clientId`.
+   * Retrieves your client, including its webhook URL and status.
    *
    * @example
    * ```ts
-   * const { actor } = await monitoring.account.me()
-   * const clientId = actor.clientId // для ключа клиента
+   * const account = await monitoring.account.get()
+   * console.log(account.webhookUrl, account.status)
    * ```
    */
-  me(options?: RequestOptions): Promise<Identity> {
-    return this.#http.request({ method: 'GET', path: '/v1/me', idempotent: true, options })
+  async get(options?: RequestOptions): Promise<Client> {
+    return this.#scope.http.request({ method: 'GET', path: await this.#scope.clientPath(), 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 })
+  /** Returns your client ID — the value of the `x-client-id` header on every webhook. */
+  id(): Promise<string> {
+    return this.#resolveId()
   }
 }