@v3finance/monitoring-sdk 0.0.0-stage → 0.2.0

package/src/core/pagination.ts

@@ -0,0 +1,20 @@
+/**
+ * A page of results. `next` is the cursor of the next page; `null` when there are no more pages.
+ *
+ * @typeParam T - Item type.
+ */
+export interface Page<T> {
+  items: T[]
+  next: number | null
+}
+
+/** @internal Yields every item, fetching the next page only when the current one is exhausted. */
+export async function* paginate<T>(fetchPage: (cursor: number | undefined) => Promise<Page<T>>): AsyncGenerator<T, void, undefined> {
+  let cursor: number | undefined
+  for (;;) {
+    const page = await fetchPage(cursor)
+    yield* page.items
+    if (page.next === null || page.next === undefined) return
+    cursor = page.next
+  }
+}

package/src/core/scope.ts

@@ -0,0 +1,8 @@
+import type { HttpClient } from './http.js'
+
+/** @internal What resources share: the transport and the client ID of the API key. */
+export interface Scope {
+  http: HttpClient
+  /** Path segment of the client: resolved from the API key once, then cached. */
+  clientPath: () => Promise<string>
+}

package/src/generated/types.ts

@@ -0,0 +1,369 @@
+// Generated from openapi/openapi.json by scripts/generate.ts — do not edit by hand.
+// V3 Finance Monitoring API 1.0.0. Regenerate: npm run spec:update && npm run generate
+
+export interface ApiErrorBody {
+  error: {
+    /**
+     * 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
+    }>
+  }
+}
+
+export interface User {
+  id: string
+  email: string
+  name: string
+  role?: "admin" | "user"
+  banned?: boolean
+  createdAt?: string
+}
+
+export interface Identity {
+  actor: {
+    /** `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<{
+    clientId: string
+    role: "owner" | "admin" | "member"
+  }>
+}
+
+export interface Client {
+  /** Client ID. */
+  id: string
+  name: string | null
+  /** Where webhooks are sent. */
+  webhookUrl: string
+  /** `disabled` — webhooks are not sent. */
+  status: "active" | "disabled"
+  /** format: date-time */
+  createdAt: string
+}
+
+export interface Network {
+  id: number
+  /**
+   * Network identifier used across the API.
+   * @example "tron"
+   */
+  slug: string
+  /**
+   * CAIP-2 chain ID.
+   * @example "tron:0x2b6653dc"
+   */
+  caip2: string
+  chainId: number
+  name: string
+  shortName: string | null
+  /** 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
+  /** 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 AssetList {
+  items: Asset[]
+}
+
+/** `in` — the address receives, `out` — the address sends, `both` — either. */
+export type Direction = "in" | "out" | "both"
+
+/** Asset symbols (`USDT`) or contract addresses. `null` — all assets of the network, including ones added later. */
+export type AssetSelection = string[] | null
+
+export interface AddressInput {
+  /** Network slug or CAIP-2 ID. */
+  network: string
+  address: string
+  /**
+   * Your reference, e.g. a user or account ID.
+   *
+   * length: 0..200
+   */
+  label?: string
+  assets?: AssetSelection
+  direction?: Direction
+}
+
+export interface AddAddressesRequest {
+  /** items: 1..1000 */
+  addresses: AddressInput[]
+  assets?: AssetSelection
+  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: 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
+  /** Subscribed asset symbols; `null` — all assets. */
+  assets: string[] | null
+  direction: Direction
+  /** format: date-time */
+  createdAt: string
+}
+
+/** 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 {
+  id: number
+  clientId: string
+  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` — 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
+  /** 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
+}
+
+export interface Transaction {
+  network: string
+  caip2: string
+  txId: string
+  /** `pending` — not yet included in a block. */
+  status: "success" | "failed" | "pending"
+  failure: string | null
+  block: number | null
+  blockTime: number | null
+  /** 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 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
+    asset: string
+    value: string
+    status: DeliveryStatus
+    attempts: number
+    deliveredAt: string | null
+  }>
+}
+
+export interface WebhookTx {
+  /**
+   * Network slug in upper case.
+   * @example "TRON"
+   * @example "ETHEREUM"
+   */
+  network: string
+  /** @example "USDT" */
+  asset: string
+  /** Token contract address or `native`. */
+  contract: string
+  /** 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
+  /** 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 address. */
+  from?: string
+  /** TRON address. */
+  to?: string
+  /** Amount in the smallest unit. */
+  value?: string
+}
+
+export interface TestDelivery {
+  /** Your endpoint responded with 2xx. */
+  ok: boolean
+  /** Status code of your response. */
+  status?: number
+  /** Connection error. */
+  error?: string
+  durationMs: number
+}
+
+export interface TestWebhookResult {
+  delivery: TestDelivery
+  /** Value of the `x-signature` header. */
+  signature: string
+  /** Exact request body. */
+  body: string
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 reference: 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 } 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 { DeliveriesResource, type DeliveryFilter, type ListDeliveriesParams } from './resources/deliveries.js'
+export { TransactionsResource } from './resources/transactions.js'
+export { WebhooksResource } from './resources/webhooks.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'
+
+// Request and response types, generated from the OpenAPI specification
+export type * from './generated/types.js'

package/src/resources/account.ts

@@ -0,0 +1,33 @@
+import type { RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { Client } from '../generated/types.js'
+
+/** Your client: the account your API key belongs to. */
+export class AccountResource {
+  readonly #scope: Scope
+  readonly #resolveId: () => Promise<string>
+
+  /** @internal */
+  constructor(scope: Scope, resolveId: () => Promise<string>) {
+    this.#scope = scope
+    this.#resolveId = resolveId
+  }
+
+  /**
+   * Retrieves your client, including its webhook URL and status.
+   *
+   * @example
+   * ```ts
+   * const account = await monitoring.account.get()
+   * console.log(account.webhookUrl, account.status)
+   * ```
+   */
+  async get(options?: RequestOptions): Promise<Client> {
+    return this.#scope.http.request({ method: 'GET', path: await this.#scope.clientPath(), idempotent: true, options })
+  }
+
+  /** Returns your client ID — the value of the `x-client-id` header on every webhook. */
+  id(): Promise<string> {
+    return this.#resolveId()
+  }
+}

package/src/resources/addresses.ts

@@ -0,0 +1,165 @@
+import { MonitoringApiError } from '../core/errors.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'
+
+/** 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 SubscriptionDefaults {
+  /** Asset symbols (`USDT`) or contract addresses. `null` — all assets of the network, including ones added later. */
+  assets?: AssetSelection
+  /** `in` — incoming only, `out` — outgoing only, `both` — either. */
+  direction?: Direction
+}
+
+/** Parameters of {@link AddressesResource.list}. */
+export interface ListAddressesParams {
+  /** Only addresses on this network. */
+  network?: string
+  /** Page size, up to 5000. Defaults to 500. */
+  limit?: number
+  /** 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 #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /**
+   * Lists monitored addresses, one page at a time.
+   *
+   * @example
+   * ```ts
+   * const { items, next } = await monitoring.addresses.list({ network: 'tron' })
+   * ```
+   */
+  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 address of monitoring.addresses.iterate({ network: 'tron' })) {
+   *   console.log(address.address, address.assets ?? 'all assets', address.direction)
+   * }
+   * ```
+   */
+  iterate(params: Omit<ListAddressesParams, 'after'> = {}, options?: RequestOptions): AsyncGenerator<Address, void, undefined> {
+    return paginate<Address>((after) => this.list({ ...params, after }, options))
+  }
+
+  /**
+   * 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.
+   *
+   * 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 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
+   * // deposit addresses: incoming USDT only
+   * await monitoring.addresses.add([{ network: 'tron', address: 'TA8Hg…', label: 'user-42' }], {
+   *   assets: ['USDT'],
+   *   direction: 'in',
+   * })
+   * ```
+   */
+  async add(addresses: AddressInput[], defaults: SubscriptionDefaults = {}, options?: RequestOptions): Promise<AddAddressesResult> {
+    const total: AddAddressesResult = { added: 0, alreadyWatched: 0 }
+    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
+    })
+    return total
+  }
+
+  /**
+   * 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([{ network: 'tron', address: 'TA8Hg…' }], { direction: 'both' })
+   * ```
+   */
+  async update(addresses: AddressUpdate[], defaults: SubscriptionDefaults = {}, options?: RequestOptions): Promise<UpdateAddressesResult> {
+    const total: UpdateAddressesResult = { updated: 0, notWatched: 0 }
+    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
+  }
+
+  /**
+   * 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.#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
+  }
+
+  /** 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), path)
+      } catch (error) {
+        if (!(error instanceof MonitoringApiError) || offset === 0) throw error
+        throw new MonitoringApiError({
+          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

@@ -0,0 +1,56 @@
+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'
+
+/** Supported networks. */
+export class NetworksResource {
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /** Lists all networks. Transfers are monitored on networks with `enabled: true`. */
+  async list(options?: RequestOptions): Promise<Network[]> {
+    const r = await this.#scope.http.request<NetworkList>({ method: 'GET', path: '/v1/networks', idempotent: true, options })
+    return r.items
+  }
+
+  /**
+   * Retrieves a network.
+   *
+   * @param network - Network slug (`tron`, `ethereum`) or CAIP-2 ID (`eip155:1`).
+   */
+  get(network: string, options?: RequestOptions): Promise<Network> {
+    return this.#scope.http.request({ method: 'GET', path: `/v1/networks/${seg(network)}`, idempotent: true, options })
+  }
+}
+
+/** Native coins and tokens. You are notified about transfers of enabled assets of at least `minAmount`. */
+export class AssetsResource {
+  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((asset) => asset.symbol === 'USDT')
+   * ```
+   */
+  async list(params: { network?: string } = {}, options?: RequestOptions): Promise<Asset[]> {
+    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.#scope.http.request({ method: 'GET', path: `/v1/assets/${seg(assetId)}`, idempotent: true, options })
+  }
+}