@v3finance/monitoring-sdk 0.0.0-stage → 0.2.0

package/src/resources/deliveries.ts

@@ -0,0 +1,82 @@
+import { seg, type RequestOptions } from '../core/http.js'
+import { paginate } from '../core/pagination.js'
+import type { Scope } from '../core/scope.js'
+import type { Delivery, DeliveryDetail, DeliveryPage, DeliveryStatus } from '../generated/types.js'
+
+/** Filters for webhook deliveries. All are optional and can be combined. */
+export interface DeliveryFilter {
+  /** `delivered`, `retrying` or `failed`. */
+  status?: DeliveryStatus
+  /** Network slug or CAIP-2 ID. */
+  network?: string
+  /** Asset symbol. */
+  asset?: string
+  /** Transaction hash. */
+  tx?: string
+  /** Sender or recipient address. */
+  address?: string
+  /** First attempt at or after this time. */
+  since?: Date | string
+  /** First attempt before this time. */
+  until?: Date | string
+}
+
+/** Parameters of {@link DeliveriesResource.list}. */
+export interface ListDeliveriesParams extends DeliveryFilter {
+  /** Page size, up to 500. Defaults to 100. */
+  limit?: number
+  /** Cursor: `next` of the previous page. */
+  before?: number
+}
+
+const iso = (value: Date | string | undefined) => (value instanceof Date ? value.toISOString() : value)
+
+/**
+ * Every webhook sent to you: status, attempts and your endpoint's response. Retries of the same webhook are one
+ * delivery with an attempt count. Deliveries are kept for 90 days.
+ */
+export class DeliveriesResource {
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /**
+   * Lists deliveries, newest first, one page at a time.
+   *
+   * @example
+   * ```ts
+   * const { items } = await monitoring.deliveries.list({ status: 'failed', since: new Date(Date.now() - 86_400_000) })
+   * ```
+   */
+  async list(params: ListDeliveriesParams = {}, options?: RequestOptions): Promise<DeliveryPage> {
+    return this.#scope.http.request({
+      method: 'GET',
+      path: `${await this.#scope.clientPath()}/deliveries`,
+      query: { ...params, since: iso(params.since), until: iso(params.until) },
+      idempotent: true,
+      options,
+    })
+  }
+
+  /**
+   * Iterates over all deliveries matching the filter, newest first.
+   *
+   * @example
+   * ```ts
+   * for await (const delivery of monitoring.deliveries.iterate({ status: 'failed' })) {
+   *   console.log(delivery.txId, delivery.attempts, delivery.lastHttpStatus ?? delivery.lastError)
+   * }
+   * ```
+   */
+  iterate(filter: DeliveryFilter & { limit?: number } = {}, options?: RequestOptions): AsyncGenerator<Delivery, void, undefined> {
+    return paginate<Delivery>((before) => this.list({ ...filter, before }, options))
+  }
+
+  /** Retrieves a delivery with the URL of the last attempt and the exact request body. */
+  async get(deliveryId: number, options?: RequestOptions): Promise<DeliveryDetail> {
+    return this.#scope.http.request({ method: 'GET', path: `${await this.#scope.clientPath()}/deliveries/${seg(deliveryId)}`, idempotent: true, options })
+  }
+}

package/src/resources/transactions.ts

@@ -0,0 +1,34 @@
+import { seg, type RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { Transaction } from '../generated/types.js'
+
+/** Any transaction on a supported network, by hash. */
+export class TransactionsResource {
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /**
+   * Retrieves a transaction — not only the ones you were notified about: status, confirmations, finality, fee and
+   * every transfer inside it, plus your monitored addresses and the webhooks sent to you for it.
+   *
+   * `final: true` means the transaction can no longer be reverted: on TRON the block is solidified (about 1 minute),
+   * on EVM networks it is finalized (about 13 minutes on Ethereum). Credit large amounts once the transaction is final.
+   *
+   * @param network - Network slug (`tron`, `ethereum`) or CAIP-2 ID.
+   * @param hash - EVM: `0x` followed by 64 hex characters. TRON: 64 hex characters.
+   * @throws {@link MonitoringApiError} `404` when the transaction does not exist on the network.
+   *
+   * @example
+   * ```ts
+   * const tx = await monitoring.transactions.get('tron', event.tx.id)
+   * if (tx.status === 'success' && tx.final) await credit(event.tx)
+   * ```
+   */
+  get(network: string, hash: string, options?: RequestOptions): Promise<Transaction> {
+    return this.#scope.http.request({ method: 'GET', path: `/v1/networks/${seg(network)}/transactions/${seg(hash)}`, idempotent: true, options })
+  }
+}

package/src/resources/webhooks.ts

@@ -0,0 +1,36 @@
+import type { RequestOptions } from '../core/http.js'
+import type { Scope } from '../core/scope.js'
+import type { TestWebhookRequest, TestWebhookResult } from '../generated/types.js'
+
+/** Test your webhook endpoint. To receive webhooks, see {@link parseWebhook}. */
+export class WebhooksResource {
+  readonly #scope: Scope
+
+  /** @internal */
+  constructor(scope: Scope) {
+    this.#scope = scope
+  }
+
+  /**
+   * Sends a signed test webhook to your webhook URL and returns the outcome, the signature and the exact body sent.
+   * Test webhooks have `"test": true` in the body and the `x-webhook-test: 1` header — do not credit them.
+   * Limited to 10 per minute.
+   *
+   * @example
+   * ```ts
+   * const { delivery } = await monitoring.webhooks.sendTest({ asset: 'USDT' })
+   * if (!delivery.ok) console.error('Endpoint responded with', delivery.status ?? delivery.error)
+   * ```
+   */
+  async sendTest(params: TestWebhookRequest = {}, options?: RequestOptions): Promise<TestWebhookResult> {
+    return this.#scope.http.request({
+      method: 'POST',
+      path: `${await this.#scope.clientPath()}/webhooks/test`,
+      body: params,
+      idempotent: false,
+      // 502 means "your endpoint did not accept it": an outcome, not a failed request
+      acceptStatuses: [502],
+      options,
+    })
+  }
+}

package/src/units.ts

@@ -0,0 +1,56 @@
+/**
+ * Amounts in the API and in webhooks are decimal strings in the asset's smallest unit (sun, wei; USDT has 6 decimals),
+ * because uint256 values do not fit in a `number`. These helpers convert them without losing precision. The decimals
+ * of every asset are returned by `monitoring.assets.list()`.
+ */
+
+const INTEGER = /^-?\d+$/
+const DECIMAL = /^(\d+)(?:\.(\d+))?$/
+
+/**
+ * Converts an amount in the smallest unit to a decimal string.
+ *
+ * @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: expected an integer amount in the smallest unit, 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}` : ''}`
+}
+
+/**
+ * Converts a decimal string to an amount in the smallest unit.
+ *
+ * @throws RangeError when the amount is not a non-negative decimal or has more decimal places than the asset.
+ *
+ * @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: expected a non-negative decimal, 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: expected an integer from 0 to 255, got ${decimals}`)
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/** SDK version, sent in the `user-agent` header. */
+export const SDK_VERSION = '0.2.0'
+
+/** Default API base URL. */
+export const DEFAULT_BASE_URL = 'https://monitoring.v3.finance'

package/src/webhooks.ts

@@ -0,0 +1,138 @@
+/**
+ * Receiving webhooks: signature verification and parsing. No API key or network access is needed — only your
+ * webhook secret. Uses Web Crypto, so it runs on Node.js 20+, Bun, Deno and Cloudflare Workers.
+ */
+
+import { MonitoringError, WebhookSignatureError } from './core/errors.js'
+import type { WebhookPayload } from './generated/types.js'
+
+/** Headers sent with every webhook. */
+export const WEBHOOK_HEADERS = {
+  /** HMAC-SHA256 of the raw body keyed with your webhook secret, hex-encoded. */
+  signature: 'x-signature',
+  /** Your client ID. */
+  clientId: 'x-client-id',
+  /** `1` for test webhooks. */
+  test: 'x-webhook-test',
+} as const
+
+/**
+ * The raw request body, exactly as received. Do not parse and re-serialize the JSON: the signature is computed over
+ * the original bytes.
+ */
+export type WebhookBody = string | Uint8Array | ArrayBuffer
+
+/**
+ * Where to read the signature from: the value of the `x-signature` header, or all request headers — a Fetch
+ * `Headers` object (Next.js, Hono, Cloudflare Workers) or a Node.js headers object (`req.headers` in 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)
+  // copy: Web Crypto does not accept views over a SharedArrayBuffer (a Node.js Buffer is a Uint8Array too)
+  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
+}
+
+/** Constant-time comparison. */
+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
+}
+
+/**
+ * Computes the signature of a body the way the API does. Useful for testing your webhook handler.
+ *
+ * @example
+ * ```ts
+ * const body = JSON.stringify({ tx: { network: 'TRON', asset: 'USDT', … } })
+ * await fetch('http://localhost:3000/webhooks/monitoring', {
+ *   method: 'POST',
+ *   body,
+ *   headers: { 'content-type': 'application/json', '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('')
+}
+
+/**
+ * Verifies a webhook signature. Returns `true` when the body was sent by the API and was not modified.
+ *
+ * @param body - Raw request body.
+ * @param signature - The `x-signature` header, or all request headers.
+ * @param secret - Your webhook 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)
+}
+
+/**
+ * Verifies the signature and returns the parsed webhook.
+ *
+ * Respond with a 2xx status within 15 seconds. Process webhooks idempotently by {@link webhookIdempotencyKey} — the
+ * same webhook may arrive more than once — and do not credit test webhooks ({@link isTestWebhook}). Webhooks are sent
+ * as soon as a transfer is included in a block; before crediting large amounts, check that the transaction is final
+ * with `monitoring.transactions.get()`.
+ *
+ * @throws {@link WebhookSignatureError} when the signature does not match. Respond with `401` and do not process it.
+ *
+ * @example Express (use the raw 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 Next.js route handlers, Hono, 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 (error) {
+    throw new MonitoringError('webhook body is not valid JSON', { cause: error })
+  }
+  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
+}
+
+/** `true` for test webhooks. Do not credit them. */
+export function isTestWebhook(event: WebhookPayload): boolean {
+  return event.test === true
+}
+
+/**
+ * Idempotency key of a webhook: network, transaction hash and log index. A transfer always has the same key, however
+ * many times its webhook is delivered. An EVM transaction can contain several token transfers; they differ by
+ * `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 ?? ''}`
+}