@v3finance/monitoring-sdk 0.0.0-stage → 0.1.0

package/src/client.ts

@@ -0,0 +1,94 @@
+import { HttpClient, type ClientOptions, type RequestOptions } from './core/http.js'
+import type { User } from './generated/types.js'
+import { AccountResource, AuthResource, type SignInResult } from './resources/account.js'
+import { AddressesResource } from './resources/addresses.js'
+import { AssetsResource, NetworksResource } from './resources/catalog.js'
+import { ClientsResource } from './resources/clients.js'
+import { DeliveriesResource } from './resources/deliveries.js'
+import { TransactionsResource } from './resources/transactions.js'
+import { DEFAULT_BASE_URL } from './version.js'
+
+/**
+ * Клиент API мониторинга адресов V3 Finance: адреса и подписки, история вебхуков, транзакции, ваш клиент и ключи.
+ * Только для сервера: ключ в браузере увидит любой.
+ *
+ * @example С ключом клиента — для бэкенда
+ * ```ts
+ * import { MonitoringClient } from '@v3finance/monitoring-sdk'
+ *
+ * const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY })
+ * await monitoring.addresses.add(clientId, [{ network: 'tron', address: 'T…' }], { assets: ['USDT'], direction: 'in' })
+ * ```
+ *
+ * @example По паролю — для скриптов, которым нужны права пользователя
+ * ```ts
+ * const { client } = await MonitoringClient.signIn({ email, password })
+ * const { key } = await client.account.keys.create({ name: 'ci' })
+ * ```
+ */
+export class MonitoringClient {
+  /** Кто вы и ваши личные ключи */
+  readonly account: AccountResource
+  /** Выход и смена пароля (для клиента, вошедшего по паролю) */
+  readonly auth: AuthResource
+  /** Сети */
+  readonly networks: NetworksResource
+  /** Нативные монеты и токены */
+  readonly assets: AssetsResource
+  /** Ваш клиент: URL вебхука, секрет, ключи, участники, тестовый вебхук */
+  readonly clients: ClientsResource
+  /** Адреса на мониторинге и подписка */
+  readonly addresses: AddressesResource
+  /** История вебхуков */
+  readonly deliveries: DeliveriesResource
+  /** Транзакция по хешу: статус, подтверждения, финальность */
+  readonly transactions: TransactionsResource
+
+  readonly #http: HttpClient
+
+  /**
+   * @param options - ключ (`apiKey`) или токен сессии (`sessionToken`), адрес API, таймаут, повторы
+   * @throws {@link MonitoringError} переданы и ключ, и токен; нет `fetch`
+   */
+  constructor(options: ClientOptions = {}) {
+    this.#http = new HttpClient(options, DEFAULT_BASE_URL)
+    this.account = new AccountResource(this.#http)
+    this.auth = new AuthResource(this.#http)
+    this.networks = new NetworksResource(this.#http)
+    this.assets = new AssetsResource(this.#http)
+    this.clients = new ClientsResource(this.#http)
+    this.addresses = new AddressesResource(this.#http)
+    this.deliveries = new DeliveriesResource(this.#http)
+    this.transactions = new TransactionsResource(this.#http)
+  }
+
+  /** Адрес API, с которым работает клиент */
+  get baseUrl(): string {
+    return this.#http.baseUrl
+  }
+
+  /**
+   * Вход по email и паролю: возвращает клиента с токеном сессии. Регистрации нет — пользователей заводит
+   * администратор сервиса. Не больше 3 попыток за 10 секунд с одного IP.
+   *
+   * @param options - настройки клиента, кроме учётных данных
+   * @throws {@link MonitoringApiError} 401 — неверный email или пароль
+   */
+  static async signIn(
+    credentials: { email: string; password: string },
+    options: Omit<ClientOptions, 'apiKey' | 'sessionToken'> = {},
+    requestOptions?: RequestOptions,
+  ): Promise<SignInResult & { client: MonitoringClient }> {
+    const http = new HttpClient(options, DEFAULT_BASE_URL)
+    const r = await http.request<{ token: string; user: User }>({
+      method: 'POST',
+      path: '/api/auth/sign-in/email',
+      body: credentials,
+      idempotent: false,
+      auth: false,
+      // повтор при отказе 429 только сожжёт попытки входа
+      options: { maxRetries: 0, ...requestOptions },
+    })
+    return { token: r.token, user: r.user, client: new MonitoringClient({ ...options, sessionToken: r.token }) }
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,99 @@
+import type { ApiErrorBody } from '../generated/types.js'
+
+/** Ошибка по элементу запроса: номер элемента в переданном массиве и причина */
+export type ErrorDetail = NonNullable<ApiErrorBody['error']['details']>[number]
+
+/**
+ * Базовый класс всех ошибок SDK. Ловите его, чтобы перехватить любую ошибку SDK.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await monitoring.addresses.add(clientId, items)
+ * } catch (e) {
+ *   if (e instanceof MonitoringApiError && e.status === 400) console.log(e.details)
+ *   else throw e
+ * }
+ * ```
+ */
+export class MonitoringError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'MonitoringError'
+  }
+}
+
+/** API ответил ошибкой: HTTP 4xx или 5xx */
+export class MonitoringApiError extends MonitoringError {
+  /** HTTP-статус ответа */
+  readonly status: number
+  /**
+   * Машинный код ошибки: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`,
+   * `rate_limited`, `upstream_error`, `upstream_rate_limited`, `unavailable`…
+   */
+  readonly code: string
+  /** Ошибки по элементам запроса (например, какой адрес из переданных не подошёл); пустой массив, если их нет */
+  readonly details: ErrorDetail[]
+  /** Идентификатор запроса (`cf-ray`) — укажите его, если обращаетесь в поддержку */
+  readonly requestId: string | undefined
+  /** Тело ответа как есть */
+  readonly body: unknown
+
+  constructor(init: { status: number; code: string; message: string; details?: ErrorDetail[]; requestId?: string; body?: unknown }) {
+    super(`${init.message} (HTTP ${init.status}, ${init.code})`)
+    this.name = 'MonitoringApiError'
+    this.status = init.status
+    this.code = init.code
+    this.details = init.details ?? []
+    this.requestId = init.requestId
+    this.body = init.body
+  }
+
+  /** Временная ошибка — лимит частоты или недоступный провайдер: запрос можно повторить позже */
+  get retryable(): boolean {
+    return this.status === 429 || this.status === 503
+  }
+}
+
+/** Ответа нет: сбой сети или соединения */
+export class MonitoringConnectionError extends MonitoringError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'MonitoringConnectionError'
+  }
+}
+
+/** Запрос не уложился в таймаут (`timeoutMs`) */
+export class MonitoringTimeoutError extends MonitoringConnectionError {
+  constructor(timeoutMs: number) {
+    super(`request timed out after ${timeoutMs} ms`)
+    this.name = 'MonitoringTimeoutError'
+  }
+}
+
+/** Подпись вебхука не прошла проверку: тело подделано, изменено по дороге или проверяется не тем секретом */
+export class WebhookSignatureError extends MonitoringError {
+  constructor(message = 'webhook signature mismatch') {
+    super(message)
+    this.name = 'WebhookSignatureError'
+  }
+}
+
+/** Тело ошибки в любом из форматов API: `/v1`, старые пути (`{ok: false}`), вход (`{code, message}`) */
+export function apiErrorFrom(status: number, body: unknown, requestId: string | undefined): MonitoringApiError {
+  const b = (body ?? {}) as Record<string, unknown>
+  const v1 = typeof b.error === 'object' && b.error !== null ? (b.error as Record<string, unknown>) : undefined
+  const message =
+    (typeof v1?.message === 'string' && v1.message) ||
+    (typeof b.error === 'string' && b.error) ||
+    (typeof b.message === 'string' && b.message) ||
+    `HTTP ${status}`
+  const code = (typeof v1?.code === 'string' && v1.code) || (typeof b.code === 'string' && b.code.toLowerCase()) || defaultCode(status)
+  const details = (Array.isArray(v1?.details) ? v1.details : Array.isArray(b.details) ? b.details : []) as ErrorDetail[]
+  return new MonitoringApiError({ status, code, message, details, requestId, body })
+}
+
+function defaultCode(status: number): string {
+  const codes: Record<number, string> = { 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 409: 'conflict', 429: 'rate_limited' }
+  return codes[status] ?? (status >= 500 ? 'server_error' : 'http_error')
+}

package/src/core/http.ts

@@ -0,0 +1,193 @@
+import { SDK_VERSION } from '../version.js'
+import { apiErrorFrom, MonitoringConnectionError, MonitoringError, MonitoringTimeoutError } from './errors.js'
+
+/** Настройки одного запроса — последний необязательный аргумент любого метода */
+export interface RequestOptions {
+  /** Отмена запроса; повторы тоже прекращаются */
+  signal?: AbortSignal
+  /** Таймаут этого запроса, мс — вместо {@link ClientOptions.timeoutMs} */
+  timeoutMs?: number
+  /** Сколько раз повторить этот запрос — вместо {@link ClientOptions.maxRetries} */
+  maxRetries?: number
+}
+
+/** Настройки клиента */
+export interface ClientOptions {
+  /**
+   * API-ключ: ключ клиента `ce_…` (адреса, история и транзакции своего клиента) или личный ключ `ce_user_…`
+   * (всё, что вы можете в панели, с вашими правами). Уходит в заголовке `x-api-key`.
+   */
+  apiKey?: string
+  /** Токен сессии из {@link MonitoringClient.signIn} — вместо `apiKey`. Уходит в `Authorization: Bearer` */
+  sessionToken?: string
+  /** Адрес API. По умолчанию `https://monitoring.v3.finance` */
+  baseUrl?: string
+  /** Таймаут запроса, мс. По умолчанию 30 000 */
+  timeoutMs?: number
+  /**
+   * Сколько раз повторять запрос после временной ошибки. По умолчанию 2.
+   *
+   * Повторяются ответы 429 и 503 (запрос не был выполнен), а сбои сети и таймауты — только у запросов,
+   * которые безопасно выполнить дважды (чтение, снятие и добавление адресов, отзыв ключа). Пауза — из
+   * `Retry-After`, иначе экспоненциальная с разбросом.
+   */
+  maxRetries?: number
+  /** Своя реализация `fetch` — для тестов, прокси, логирования. По умолчанию глобальный `fetch` */
+  fetch?: typeof fetch
+  /** Дополнительные заголовки каждого запроса */
+  headers?: Record<string, string>
+}
+
+type Query = Record<string, string | number | boolean | null | undefined>
+
+/** Описание одного запроса к API */
+export interface Call {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  query?: Query
+  body?: unknown
+  /** Можно ли повторить после сбоя сети: повтор не изменит результат */
+  idempotent: boolean
+  /** Статусы, которые возвращаются как данные, а не ошибка (тестовый вебхук: 502 — «не доставлен») */
+  acceptStatuses?: number[]
+  /** false — запрос без учётных данных (вход) */
+  auth?: boolean
+  options?: RequestOptions | undefined
+}
+
+const DEFAULTS = { timeoutMs: 30_000, maxRetries: 2 }
+const MAX_RETRY_DELAY_MS = 60_000
+
+/** Транспорт SDK: адрес, авторизация, таймауты, повторы, разбор ошибок. Ресурсы ходят в API только через него */
+export class HttpClient {
+  readonly baseUrl: string
+  readonly #apiKey: string | undefined
+  readonly #sessionToken: string | undefined
+  readonly #timeoutMs: number
+  readonly #maxRetries: number
+  readonly #fetch: typeof fetch
+  readonly #headers: Record<string, string>
+
+  constructor(options: ClientOptions, defaultBaseUrl: string) {
+    if (options.apiKey && options.sessionToken) throw new MonitoringError('pass either apiKey or sessionToken, not both')
+    this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/+$/, '')
+    this.#apiKey = options.apiKey
+    this.#sessionToken = options.sessionToken
+    this.#timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs
+    this.#maxRetries = options.maxRetries ?? DEFAULTS.maxRetries
+    const f = options.fetch ?? globalThis.fetch
+    if (typeof f !== 'function') throw new MonitoringError('fetch is not available: use Node.js 20+ or pass options.fetch')
+    this.#fetch = f
+    this.#headers = { ...options.headers }
+  }
+
+  /** Выполняет запрос и возвращает разобранный JSON ответа */
+  async request<T>(call: Call): Promise<T> {
+    const url = this.#url(call.path, call.query)
+    const headers = this.#headersFor(call)
+    const body = call.body === undefined ? undefined : JSON.stringify(call.body)
+    const maxRetries = call.options?.maxRetries ?? this.#maxRetries
+    const timeoutMs = call.options?.timeoutMs ?? this.#timeoutMs
+
+    for (let attempt = 0; ; attempt++) {
+      let res: { status: number; headers: Headers; data: unknown }
+      try {
+        res = await this.#send(url, { method: call.method, headers, body }, timeoutMs, call.options?.signal)
+      } catch (e) {
+        if (call.options?.signal?.aborted) throw call.options.signal.reason
+        if (call.idempotent && attempt < maxRetries) {
+          await sleep(backoff(attempt), call.options?.signal)
+          continue
+        }
+        throw e
+      }
+      if ((res.status >= 200 && res.status < 300) || call.acceptStatuses?.includes(res.status)) return res.data as T
+      const error = apiErrorFrom(res.status, res.data, res.headers.get('cf-ray') ?? undefined)
+      // 429 и 503: запрос не выполнен — повтор безопасен для любого метода
+      if (error.retryable && attempt < maxRetries) {
+        await sleep(retryAfter(res.headers) ?? backoff(attempt), call.options?.signal)
+        continue
+      }
+      throw error
+    }
+  }
+
+  #url(path: string, query?: Query): string {
+    const url = new URL(this.baseUrl + path)
+    for (const [k, v] of Object.entries(query ?? {})) if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v))
+    return url.toString()
+  }
+
+  #headersFor(call: Call): Record<string, string> {
+    const headers: Record<string, string> = { accept: 'application/json', 'user-agent': `@v3finance/monitoring-sdk/${SDK_VERSION}`, ...this.#headers }
+    if (call.body !== undefined) headers['content-type'] = 'application/json'
+    if (call.auth !== false) {
+      if (this.#apiKey) headers['x-api-key'] = this.#apiKey
+      else if (this.#sessionToken) headers.authorization = `Bearer ${this.#sessionToken}`
+      else throw new MonitoringError('credentials required: pass apiKey or sessionToken to MonitoringClient')
+    }
+    return headers
+  }
+
+  /** Один запрос с таймаутом на всё — и соединение, и чтение тела */
+  async #send(url: string, init: RequestInit, timeoutMs: number, signal: AbortSignal | undefined) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(new MonitoringTimeoutError(timeoutMs)), timeoutMs)
+    const onAbort = () => controller.abort(signal!.reason)
+    if (signal?.aborted) onAbort()
+    signal?.addEventListener('abort', onAbort, { once: true })
+    try {
+      const res = await this.#fetch(url, { ...init, signal: controller.signal })
+      const text = await res.text()
+      return { status: res.status, headers: res.headers, data: text ? parseJson(text) : undefined }
+    } catch (e) {
+      const reason: unknown = controller.signal.reason
+      if (reason instanceof MonitoringTimeoutError) throw reason
+      if (signal?.aborted) throw signal.reason
+      throw new MonitoringConnectionError(`request to ${new URL(url).origin} failed: ${(e as Error).message}`, { cause: e })
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+  }
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/** Экспоненциальная пауза с разбросом: ~0,5 с, 1 с, 2 с… не больше 8 с */
+function backoff(attempt: number): number {
+  return Math.min(8_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2)
+}
+
+/** Пауза из заголовка Retry-After: секунды или дата */
+function retryAfter(headers: Headers): number | undefined {
+  const raw = headers.get('retry-after')
+  if (!raw) return undefined
+  const seconds = Number(raw)
+  const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(raw) - Date.now()
+  return Number.isFinite(ms) ? Math.min(Math.max(ms, 0), MAX_RETRY_DELAY_MS) : undefined
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason)
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(signal!.reason)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/** Сегмент пути: id клиента, хеш и т. п. */
+export const seg = (value: string | number) => encodeURIComponent(String(value))

package/src/core/pagination.ts

@@ -0,0 +1,21 @@
+/**
+ * Страница списка. `next` — курсор следующей страницы; `null` — страниц больше нет.
+ *
+ * @typeParam T - элемент списка
+ * @typeParam Cursor - тип курсора: строка (клиенты) или число (адреса, история)
+ */
+export interface Page<T, Cursor = string | number> {
+  items: T[]
+  next: Cursor | null
+}
+
+/** Обходит все страницы по порядку, запрашивая следующую, только когда закончилась текущая */
+export async function* paginate<T, Cursor>(fetchPage: (cursor: Cursor | undefined) => Promise<Page<T, Cursor>>): AsyncGenerator<T, void, undefined> {
+  let cursor: Cursor | undefined
+  for (;;) {
+    const page = await fetchPage(cursor)
+    yield* page.items
+    if (page.next === null || page.next === undefined) return
+    cursor = page.next
+  }
+}