@v3finance/monitoring-sdk 0.0.0-stage → 0.1.0

package/src/resources/catalog.ts

@@ -0,0 +1,47 @@
+import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
+import type { Asset, Network } from '../generated/types.js'
+
+/** Сети: TRON и EVM-сети с идентификаторами CAIP-2 */
+export class NetworksResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /** Все сети. `enabled: false` — сеть описана, но не читается: вебхуков по ней нет */
+  async list(options?: RequestOptions): Promise<Network[]> {
+    const r = await this.#http.request<{ items: Network[] }>({ method: 'GET', path: '/v1/networks', idempotent: true, options })
+    return r.items
+  }
+
+  /** Сеть по slug (`tron`) или CAIP-2 (`eip155:1`) */
+  get(network: string, options?: RequestOptions): Promise<Network> {
+    return this.#http.request({ method: 'GET', path: `/v1/networks/${seg(network)}`, idempotent: true, options })
+  }
+}
+
+/** Активы: нативные монеты и токены. Вебхуки приходят о переводах включённых активов не меньше порога `minAmount` */
+export class AssetsResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /**
+   * Активы — все или одной сети.
+   *
+   * @example
+   * ```ts
+   * const usdt = (await monitoring.assets.list({ network: 'tron' })).find((a) => a.symbol === 'USDT')
+   * formatUnits(webhook.tx.value, usdt!.decimals)
+   * ```
+   */
+  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 })
+    return r.items
+  }
+
+  get(assetId: number, options?: RequestOptions): Promise<Asset> {
+    return this.#http.request({ method: 'GET', path: `/v1/assets/${seg(assetId)}`, idempotent: true, options })
+  }
+}

package/src/resources/clients.ts

@@ -0,0 +1,135 @@
+import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
+import { paginate, type Page } from '../core/pagination.js'
+import type { ApiKey, Client, IssueKeyRequest, IssuedKey, Member, TestWebhookRequest, TestWebhookResult } from '../generated/types.js'
+
+export interface ListClientsParams {
+  /** Размер страницы, до 1000; по умолчанию 100 */
+  limit?: number
+  /** Курсор: `next` прошлой страницы */
+  after?: string
+}
+
+/** Что изменить у клиента; не переданное не меняется */
+export interface UpdateClientParams {
+  /** Название; `null` — убрать */
+  name?: string | null
+  /** URL вебхука: только https, без логина и пароля */
+  webhookUrl?: string
+}
+
+export interface RotateSecretParams {
+  /** Свой секрет (от 16 символов); без него — сгенерируется */
+  secretKey?: string
+}
+
+export interface RotateSecretResult {
+  /** Новый секрет подписи вебхуков — показывается один раз, сохраните его */
+  secretKey: string
+}
+
+/** Ключи клиента: доступ к адресам, истории и транзакциям этого клиента. Управляют owner и admin клиента */
+export class ClientKeysResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /** Ключи клиента (без самих ключей — только начало) */
+  async list(clientId: string, options?: RequestOptions): Promise<ApiKey[]> {
+    const r = await this.#http.request<{ items: ApiKey[] }>({ method: 'GET', path: `/v1/clients/${seg(clientId)}/keys`, idempotent: true, options })
+    return r.items
+  }
+
+  /**
+   * Выпускает ключ клиента. Полный ключ — в `key`, показывается один раз.
+   *
+   * @example
+   * ```ts
+   * const { key } = await monitoring.clients.keys.create(clientId, { name: 'backend', expiresInDays: 365 })
+   * ```
+   */
+  create(clientId: string, params: IssueKeyRequest = {}, options?: RequestOptions): Promise<IssuedKey> {
+    return this.#http.request({ method: 'POST', path: `/v1/clients/${seg(clientId)}/keys`, body: params, idempotent: false, options })
+  }
+
+  /** Отзывает ключ — он перестаёт работать сразу */
+  async revoke(clientId: string, keyId: string, options?: RequestOptions): Promise<void> {
+    await this.#http.request({ method: 'DELETE', path: `/v1/clients/${seg(clientId)}/keys/${seg(keyId)}`, idempotent: true, options })
+  }
+}
+
+/**
+ * Ваш клиент: URL вебхука, секрет подписи, ключи, участники, тестовый вебхук.
+ *
+ * Права: смотреть — любой участник и ключ клиента; менять — owner и admin клиента по сессии или личному ключу.
+ */
+export class ClientsResource {
+  readonly #http: HttpClient
+  /** Ключи клиента */
+  readonly keys: ClientKeysResource
+
+  constructor(http: HttpClient) {
+    this.#http = http
+    this.keys = new ClientKeysResource(http)
+  }
+
+  /** Страница ваших клиентов: где вы участник; для ключа клиента — он сам */
+  list(params: ListClientsParams = {}, options?: RequestOptions): Promise<Page<Client, string>> {
+    return this.#http.request({ method: 'GET', path: '/v1/clients', query: { ...params }, idempotent: true, options })
+  }
+
+  /** Все ваши клиенты — страница за страницей */
+  iterate(params: Omit<ListClientsParams, 'after'> = {}, options?: RequestOptions): AsyncGenerator<Client, void, undefined> {
+    return paginate<Client, string>((after) => this.list({ ...params, after }, options))
+  }
+
+  get(clientId: string, options?: RequestOptions): Promise<Client> {
+    return this.#http.request({ method: 'GET', path: `/v1/clients/${seg(clientId)}`, idempotent: true, options })
+  }
+
+  /**
+   * Меняет название или URL вебхука.
+   *
+   * @example
+   * ```ts
+   * await monitoring.clients.update(clientId, { webhookUrl: 'https://example.com/webhooks/monitoring' })
+   * ```
+   */
+  update(clientId: string, params: UpdateClientParams, options?: RequestOptions): Promise<Client> {
+    return this.#http.request({ method: 'PATCH', path: `/v1/clients/${seg(clientId)}`, body: params, idempotent: true, options })
+  }
+
+  /** Новый секрет подписи вебхуков. Старый перестаёт действовать сразу — обновите его у себя до следующего вебхука */
+  rotateSecret(clientId: string, params: RotateSecretParams = {}, options?: RequestOptions): Promise<RotateSecretResult> {
+    return this.#http.request({ method: 'POST', path: `/v1/clients/${seg(clientId)}/secret`, body: params, idempotent: false, options })
+  }
+
+  /**
+   * Отправляет тестовый вебхук на URL клиента и возвращает результат: доставлен ли, ваш ответ, подпись и точное
+   * тело. Тестовый вебхук помечен `"test": true` и заголовком `x-webhook-test: 1` — не зачисляйте его.
+   * Не больше 10 в минуту.
+   *
+   * @example
+   * ```ts
+   * const r = await monitoring.clients.sendTestWebhook(clientId, { asset: 'USDT' })
+   * if (!r.delivery.ok) console.log('ваш сервер ответил', r.delivery.status ?? r.delivery.error)
+   * ```
+   */
+  sendTestWebhook(clientId: string, params: TestWebhookRequest = {}, options?: RequestOptions): Promise<TestWebhookResult> {
+    return this.#http.request({
+      method: 'POST',
+      path: `/v1/clients/${seg(clientId)}/webhooks/test`,
+      body: params,
+      idempotent: false,
+      // 502 — «не доставлен»: это результат проверки, а не ошибка запроса
+      acceptStatuses: [502],
+      options,
+    })
+  }
+
+  /** Участники клиента и их роли */
+  async members(clientId: string, options?: RequestOptions): Promise<Member[]> {
+    const r = await this.#http.request<{ items: Member[] }>({ method: 'GET', path: `/v1/clients/${seg(clientId)}/members`, idempotent: true, options })
+    return r.items
+  }
+}

package/src/resources/deliveries.ts

@@ -0,0 +1,69 @@
+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'
+
+/** Фильтры истории; все необязательны и сочетаются */
+export interface DeliveryFilter {
+  /** `delivered` — вы ответили 2xx, `retrying` — будет повтор, `failed` — повторы исчерпаны */
+  status?: DeliveryStatus
+  /** Сеть: slug или CAIP-2 */
+  network?: string
+  /** Символ актива */
+  asset?: string
+  /** Хеш транзакции */
+  tx?: string
+  /** Отправитель или получатель */
+  address?: string
+  /** Первая попытка не раньше (дата или время) */
+  since?: Date | string
+  /** Первая попытка раньше (не включая) */
+  until?: Date | string
+}
+
+export interface ListDeliveriesParams extends DeliveryFilter {
+  /** Размер страницы, до 500; по умолчанию 100 */
+  limit?: number
+  /** Курсор: `next` прошлой страницы */
+  before?: number
+}
+
+const iso = (v: Date | string | undefined) => (v instanceof Date ? v.toISOString() : v)
+
+/**
+ * История вебхуков клиента: что, когда и куда отправлено, сколько было попыток и что вы ответили.
+ * Повторы одного вебхука — одна запись. Хранится 90 дней.
+ */
+export class DeliveriesResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /**
+   * Страница истории, новые сверху.
+   *
+   * @example
+   * ```ts
+   * const { items } = await monitoring.deliveries.list(clientId, { 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({
+      method: 'GET',
+      path: `/v1/clients/${seg(clientId)}/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))
+  }
+
+  /** Одна запись с 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 })
+  }
+}

package/src/resources/transactions.ts

@@ -0,0 +1,33 @@
+import { seg, type HttpClient, type RequestOptions } from '../core/http.js'
+import type { Transaction } from '../generated/types.js'
+
+/** Любая транзакция сети по хешу — не только те, о которых пришёл вебхук */
+export class TransactionsResource {
+  readonly #http: HttpClient
+  constructor(http: HttpClient) {
+    this.#http = http
+  }
+
+  /**
+   * Статус, блок, подтверждения, финальность, комиссия и все переводы внутри транзакции; для ваших адресов —
+   * направление и вебхуки, которые мы по ней отправили.
+   *
+   * `final: true` — транзакцию уже не отменить: в TRON блок солидифицирован (около минуты), в EVM —
+   * финализирован (Ethereum — около 13 минут). Крупные суммы зачисляйте после `final`.
+   *
+   * Не больше 60 запросов в минуту на ключ; при превышении SDK подождёт и повторит.
+   *
+   * @param network - slug (`tron`, `ethereum`) или CAIP-2
+   * @param hash - EVM — `0x` + 64 hex; TRON — 64 hex (можно с `0x`)
+   * @throws {@link MonitoringApiError} 404 — такой транзакции в сети нет
+   *
+   * @example
+   * ```ts
+   * const tx = await monitoring.transactions.get('tron', webhook.tx.id)
+   * if (tx.status === 'success' && tx.final) credit(webhook)
+   * ```
+   */
+  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 })
+  }
+}

package/src/units.ts

@@ -0,0 +1,56 @@
+/**
+ * Суммы в API и вебхуках — строки в минимальных единицах (sun, wei; у USDT 6 знаков после запятой): uint256 не
+ * помещается в `number`. Эти функции переводят их в привычный вид и обратно без потери точности.
+ * Знаки после запятой актива — `decimals` из `monitoring.assets.list()`.
+ */
+
+const INTEGER = /^-?\d+$/
+const DECIMAL = /^(\d+)(?:\.(\d+))?$/
+
+/**
+ * Минимальные единицы → строка в монетах.
+ *
+ * @example
+ * ```ts
+ * 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)}`)
+  const negative = raw.startsWith('-')
+  const digits = (negative ? raw.slice(1) : raw).replace(/^0+(?=\d)/, '')
+  if (decimals === 0) return (negative && digits !== '0' ? '-' : '') + digits
+  const padded = digits.padStart(decimals + 1, '0')
+  const whole = padded.slice(0, -decimals)
+  const fraction = padded.slice(-decimals).replace(/0+$/, '')
+  const sign = negative && (whole !== '0' || fraction) ? '-' : ''
+  return `${sign}${whole}${fraction ? `.${fraction}` : ''}`
+}
+
+/**
+ * Строка в монетах → минимальные единицы.
+ *
+ * @throws RangeError — больше знаков после запятой, чем у актива, или не число
+ *
+ * @example
+ * ```ts
+ * 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)}`)
+  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}`)
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/** Версия SDK: уходит в заголовке `user-agent`. Тест сверяет её с package.json */
+export const SDK_VERSION = '0.1.0'
+
+/** Адрес API по умолчанию */
+export const DEFAULT_BASE_URL = 'https://monitoring.v3.finance'

package/src/webhooks.ts

@@ -0,0 +1,133 @@
+/**
+ * Приём вебхуков: проверка подписи и разбор тела. Работает без клиента API и без сети — нужен только секрет
+ * подписи клиента. Использует WebCrypto: Node.js 20+, Bun, Deno, Cloudflare Workers.
+ */
+
+import { MonitoringError, WebhookSignatureError } from './core/errors.js'
+import type { WebhookPayload } from './generated/types.js'
+
+/** Заголовки вебхука */
+export const WEBHOOK_HEADERS = {
+  /** HMAC-SHA256 сырого тела секретом клиента, hex в нижнем регистре */
+  signature: 'x-signature',
+  /** id клиента */
+  clientId: 'x-client-id',
+  /** `1` у тестового вебхука — такой не зачислять */
+  test: 'x-webhook-test',
+} as const
+
+/**
+ * Тело вебхука ровно как пришло — сырые байты или строка. Не `JSON.parse` + `JSON.stringify`: подпись считается
+ * по исходным байтам, и любое переформатирование её ломает.
+ */
+export type WebhookBody = string | Uint8Array | ArrayBuffer
+
+/**
+ * Откуда взять подпись: значение заголовка `x-signature` или все заголовки запроса — Fetch `Headers`
+ * (Hono, Next.js, Workers) или объект Node.js (`req.headers` в Express, Fastify).
+ */
+export type SignatureSource = string | null | undefined | Headers | Record<string, string | string[] | undefined>
+
+const encoder = new TextEncoder()
+
+function bytesOf(body: WebhookBody): Uint8Array<ArrayBuffer> {
+  if (typeof body === 'string') return encoder.encode(body)
+  // копия: WebCrypto не принимает view над SharedArrayBuffer (Buffer в Node.js — тоже Uint8Array)
+  return body instanceof Uint8Array ? new Uint8Array(body) : new Uint8Array(body)
+}
+
+function signatureOf(source: SignatureSource): string | undefined {
+  if (source === null || source === undefined) return undefined
+  if (typeof source === 'string') return source
+  if (typeof (source as Headers).get === 'function') return (source as Headers).get(WEBHOOK_HEADERS.signature) ?? undefined
+  const value = (source as Record<string, string | string[] | undefined>)[WEBHOOK_HEADERS.signature]
+  return Array.isArray(value) ? value[0] : value
+}
+
+/** Сравнение без утечки по времени: время не зависит от того, где строки расходятся */
+function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+  return diff === 0
+}
+
+/**
+ * Подпись тела секретом клиента — как её считает сервис. Нужна в тестах вашего обработчика вебхуков.
+ *
+ * @example
+ * ```ts
+ * const body = JSON.stringify({ tx: { …, id: 'test' } })
+ * await fetch('http://localhost:3000/webhooks', { method: 'POST', body, headers: { 'x-signature': await signWebhookBody(body, secret) } })
+ * ```
+ */
+export async function signWebhookBody(body: WebhookBody, secret: string): Promise<string> {
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, bytesOf(body)))
+  return Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Проверяет подпись вебхука: `true` — тело пришло от сервиса и не изменено.
+ *
+ * @param body - сырое тело запроса
+ * @param signature - заголовок `x-signature` или все заголовки запроса
+ * @param secret - секрет подписи клиента
+ */
+export async function verifyWebhookSignature(body: WebhookBody, signature: SignatureSource, secret: string): Promise<boolean> {
+  const given = signatureOf(signature)?.trim().toLowerCase()
+  if (!given) return false
+  return safeEqual(await signWebhookBody(body, secret), given)
+}
+
+/**
+ * Проверяет подпись и возвращает разобранный вебхук.
+ *
+ * Дальше — по правилам приёма: тестовый вебхук ({@link isTestWebhook}) не зачислять; один и тот же вебхук может
+ * прийти повторно — обрабатывайте идемпотентно по {@link webhookIdempotencyKey}; ответьте 2xx в течение 15 секунд.
+ * Вебхук уходит, как только перевод попал в блок, — для крупных сумм дождитесь финальности
+ * (`monitoring.transactions.get(...).final`).
+ *
+ * @throws {@link WebhookSignatureError} подпись не совпала — ответьте 401 и ничего не зачисляйте
+ *
+ * @example Express — нужен сырой body
+ * ```ts
+ * app.post('/webhooks/monitoring', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   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)
+ * })
+ * ```
+ *
+ * @example Hono, Next.js route handler, Cloudflare Workers
+ * ```ts
+ * const event = await parseWebhook(await request.text(), request.headers, env.MONITORING_WEBHOOK_SECRET)
+ * ```
+ */
+export async function parseWebhook(body: WebhookBody, signature: SignatureSource, secret: string): Promise<WebhookPayload> {
+  if (!(await verifyWebhookSignature(body, signature, secret))) throw new WebhookSignatureError()
+  let payload: unknown
+  try {
+    payload = JSON.parse(typeof body === 'string' ? body : new TextDecoder().decode(bytesOf(body)))
+  } catch (e) {
+    throw new MonitoringError('webhook body is not valid JSON', { cause: e })
+  }
+  const tx = (payload as { tx?: { id?: unknown } } | null)?.tx
+  if (typeof tx !== 'object' || tx === null || typeof tx.id !== 'string') throw new MonitoringError('webhook body has no tx')
+  return payload as WebhookPayload
+}
+
+/** Тестовый вебхук (из панели или `clients.sendTestWebhook`) — такой не зачислять */
+export function isTestWebhook(event: WebhookPayload): boolean {
+  return event.test === true
+}
+
+/**
+ * Ключ идемпотентности вебхука: сеть, транзакция и номер лога. Один перевод — один ключ, даже если вебхук пришёл
+ * несколько раз. В одной транзакции EVM может быть несколько переводов токенов — у них разный `logIndex`.
+ *
+ * @example `"TRON:1249cb…a5fc45:"`, `"ETHEREUM:0x3fbc…1d57:7"`
+ */
+export function webhookIdempotencyKey(event: WebhookPayload): string {
+  return `${event.tx.network}:${event.tx.id}:${event.tx.logIndex ?? ''}`
+}