@v3finance/monitoring-sdk 0.0.0-stage → 0.2.0

package/dist/esm/webhooks.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 type { WebhookPayload } from './generated/types.js';
+/** Headers sent with every webhook. */
+export declare const WEBHOOK_HEADERS: {
+    /** HMAC-SHA256 of the raw body keyed with your webhook secret, hex-encoded. */
+    readonly signature: 'x-signature';
+    /** Your client ID. */
+    readonly clientId: 'x-client-id';
+    /** `1` for test webhooks. */
+    readonly test: 'x-webhook-test';
+};
+/**
+ * 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>;
+/**
+ * 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 declare function signWebhookBody(body: WebhookBody, secret: string): Promise<string>;
+/**
+ * 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 declare function verifyWebhookSignature(body: WebhookBody, signature: SignatureSource, secret: string): Promise<boolean>;
+/**
+ * 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 declare function parseWebhook(body: WebhookBody, signature: SignatureSource, secret: string): Promise<WebhookPayload>;
+/** `true` for test webhooks. Do not credit them. */
+export declare function isTestWebhook(event: WebhookPayload): boolean;
+/**
+ * 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 declare function webhookIdempotencyKey(event: WebhookPayload): string;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/esm/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/webhooks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,uCAAuC;AACvC,eAAO,MAAM,eAAe;IAC1B,+EAA+E;aAC/E,SAAS,EAAE,aAAa;IACxB,sBAAsB;aACtB,QAAQ,EAAE,aAAa;IACvB,6BAA6B;aAC7B,IAAI,EAAE,gBAAgB;CACd,CAAA;AAEV;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,CAAA;AAE3D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;AA0BjH;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxF;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI5H;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAWzH;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEnE"}

package/dist/esm/webhooks.js

@@ -0,0 +1,125 @@
+/**
+ * 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';
+/** 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',
+};
+const encoder = new TextEncoder();
+function bytesOf(body) {
+    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) {
+    if (source === null || source === undefined)
+        return undefined;
+    if (typeof source === 'string')
+        return source;
+    if (typeof source.get === 'function')
+        return source.get(WEBHOOK_HEADERS.signature) ?? undefined;
+    const value = source[WEBHOOK_HEADERS.signature];
+    return Array.isArray(value) ? value[0] : value;
+}
+/** Constant-time comparison. */
+function safeEqual(a, b) {
+    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, secret) {
+    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, signature, secret) {
+    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, signature, secret) {
+    if (!(await verifyWebhookSignature(body, signature, secret)))
+        throw new WebhookSignatureError();
+    let payload;
+    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?.tx;
+    if (typeof tx !== 'object' || tx === null || typeof tx.id !== 'string')
+        throw new MonitoringError('webhook body has no tx');
+    return payload;
+}
+/** `true` for test webhooks. Do not credit them. */
+export function isTestWebhook(event) {
+    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) {
+    return `${event.tx.network}:${event.tx.id}:${event.tx.logIndex ?? ''}`;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/esm/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@v3finance/monitoring-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Official TypeScript SDK for the V3 Finance Monitoring API — monitor TRON and EVM addresses and receive signed webhooks for every transfer.",
+  "keywords": [
+    "v3finance",
+    "monitoring",
+    "webhooks",
+    "tron",
+    "ethereum",
+    "evm",
+    "usdt",
+    "usdc",
+    "trc20",
+    "erc20",
+    "blockchain",
+    "payments",
+    "crypto",
+    "sdk",
+    "typescript"
+  ],
+  "homepage": "https://monitoring.v3.finance/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/v3-finance/monitoring-sdk.git"
+  },
+  "license": "MIT",
+  "author": "V3 Finance",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "spec:update": "node scripts/fetch-spec.ts",
+    "generate": "node scripts/generate.ts",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run",
+    "build": "node scripts/build.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  }
+}

package/src/client.ts

@@ -0,0 +1,83 @@
+import { MonitoringError } from './core/errors.js'
+import { HttpClient, seg, type ClientOptions } from './core/http.js'
+import type { Scope } from './core/scope.js'
+import type { Identity } from './generated/types.js'
+import { AccountResource } from './resources/account.js'
+import { AddressesResource } from './resources/addresses.js'
+import { AssetsResource, NetworksResource } from './resources/catalog.js'
+import { DeliveriesResource } from './resources/deliveries.js'
+import { TransactionsResource } from './resources/transactions.js'
+import { WebhooksResource } from './resources/webhooks.js'
+import { DEFAULT_BASE_URL } from './version.js'
+
+/**
+ * Client for the V3 Finance Monitoring API.
+ *
+ * Use it on the server only: an API key in a browser is visible to anyone.
+ *
+ * @example
+ * ```ts
+ * import { MonitoringClient } from '@v3finance/monitoring-sdk'
+ *
+ * const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY! })
+ *
+ * await monitoring.addresses.add([{ network: 'tron', address: 'TA8Hg…' }], { assets: ['USDT'], direction: 'in' })
+ * ```
+ */
+export class MonitoringClient {
+  /** Your client: the account your API key belongs to. */
+  readonly account: AccountResource
+  /** Addresses you monitor and their subscriptions. */
+  readonly addresses: AddressesResource
+  /** Test your webhook endpoint. */
+  readonly webhooks: WebhooksResource
+  /** History of webhooks sent to you. */
+  readonly deliveries: DeliveriesResource
+  /** Any transaction by hash, with confirmations and finality. */
+  readonly transactions: TransactionsResource
+  /** Supported networks. */
+  readonly networks: NetworksResource
+  /** Supported native coins and tokens. */
+  readonly assets: AssetsResource
+
+  readonly #http: HttpClient
+  #clientId: Promise<string> | undefined
+
+  /**
+   * @param options - API key and optional settings.
+   * @throws {@link MonitoringError} when `apiKey` is missing or `fetch` is not available.
+   */
+  constructor(options: ClientOptions) {
+    this.#http = new HttpClient(options, DEFAULT_BASE_URL)
+    if (options.clientId) this.#clientId = Promise.resolve(options.clientId)
+    const scope: Scope = { http: this.#http, clientPath: async () => `/v1/clients/${seg(await this.#resolveClientId())}` }
+    this.account = new AccountResource(scope, () => this.#resolveClientId())
+    this.addresses = new AddressesResource(scope)
+    this.webhooks = new WebhooksResource(scope)
+    this.deliveries = new DeliveriesResource(scope)
+    this.transactions = new TransactionsResource(scope)
+    this.networks = new NetworksResource(scope)
+    this.assets = new AssetsResource(scope)
+  }
+
+  /** API base URL this client sends requests to. */
+  get baseUrl(): string {
+    return this.#http.baseUrl
+  }
+
+  /** Client ID of the API key: from the options, or resolved once from the API and cached. */
+  #resolveClientId(): Promise<string> {
+    this.#clientId ??= this.#http.request<Identity>({ method: 'GET', path: '/v1/me', idempotent: true }).then(
+      (identity) => {
+        if (!identity.actor.clientId) throw new MonitoringError('this API key is not bound to a client: pass clientId in the options')
+        return identity.actor.clientId
+      },
+      (error: unknown) => {
+        // a failed lookup is not cached: the next call tries again
+        this.#clientId = undefined
+        throw error
+      },
+    )
+    return this.#clientId
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,99 @@
+import type { ApiErrorBody } from '../generated/types.js'
+
+/** A per-item problem of a batch request: the item's index in your request and the reason. */
+export type ErrorDetail = NonNullable<ApiErrorBody['error']['details']>[number]
+
+/**
+ * Base class of every error thrown by the SDK.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await monitoring.addresses.add(items)
+ * } catch (error) {
+ *   if (error instanceof MonitoringApiError && error.status === 400) console.log(error.details)
+ *   else throw error
+ * }
+ * ```
+ */
+export class MonitoringError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'MonitoringError'
+  }
+}
+
+/** The API responded with an error status (4xx or 5xx). */
+export class MonitoringApiError extends MonitoringError {
+  /** HTTP status code. */
+  readonly status: number
+  /**
+   * Machine-readable error code, e.g. `invalid_request`, `unauthorized`, `forbidden`, `not_found`,
+   * `rate_limited`, `upstream_error`, `upstream_rate_limited`.
+   */
+  readonly code: string
+  /** Per-item problems of a batch request, such as invalid addresses. Empty when there are none. */
+  readonly details: ErrorDetail[]
+  /** Request ID. Include it when contacting support. */
+  readonly requestId: string | undefined
+  /** Raw response body. */
+  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
+  }
+
+  /** `true` for transient errors — rate limits and unavailable upstream providers — that can be retried later. */
+  get retryable(): boolean {
+    return this.status === 429 || this.status === 503
+  }
+}
+
+/** The request did not get a response because of a network or connection failure. */
+export class MonitoringConnectionError extends MonitoringError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'MonitoringConnectionError'
+  }
+}
+
+/** The request did not complete within `timeoutMs`. */
+export class MonitoringTimeoutError extends MonitoringConnectionError {
+  constructor(timeoutMs: number) {
+    super(`request timed out after ${timeoutMs} ms`)
+    this.name = 'MonitoringTimeoutError'
+  }
+}
+
+/** The webhook signature does not match: the body was altered or is verified with the wrong secret. */
+export class WebhookSignatureError extends MonitoringError {
+  constructor(message = 'webhook signature mismatch') {
+    super(message)
+    this.name = 'WebhookSignatureError'
+  }
+}
+
+/** Builds an error from any error body the API returns. */
+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,183 @@
+import { SDK_VERSION } from '../version.js'
+import { apiErrorFrom, MonitoringConnectionError, MonitoringError, MonitoringTimeoutError } from './errors.js'
+
+/** Per-request options, accepted as the last argument of every method. */
+export interface RequestOptions {
+  /** Cancels the request, including pending retries. */
+  signal?: AbortSignal
+  /** Timeout for this request in milliseconds. Overrides {@link ClientOptions.timeoutMs}. */
+  timeoutMs?: number
+  /** Maximum number of retries for this request. Overrides {@link ClientOptions.maxRetries}. */
+  maxRetries?: number
+}
+
+/** Options of {@link MonitoringClient}. */
+export interface ClientOptions {
+  /** Your API key. Sent in the `x-api-key` header. */
+  apiKey: string
+  /**
+   * Your client ID. Optional: when omitted, it is resolved from the API key on first use and cached.
+   */
+  clientId?: string
+  /** API base URL. Defaults to `https://monitoring.v3.finance`. */
+  baseUrl?: string
+  /** Request timeout in milliseconds. Defaults to `30000`. */
+  timeoutMs?: number
+  /**
+   * Maximum number of retries for transient errors. Defaults to `2`.
+   *
+   * `429` and `503` responses are retried for every request, honoring `Retry-After`. Network errors and timeouts are
+   * retried only for requests that are safe to repeat. Backoff is exponential with jitter.
+   */
+  maxRetries?: number
+  /** Custom `fetch` implementation, e.g. for proxies or instrumentation. Defaults to the global `fetch`. */
+  fetch?: typeof fetch
+  /** Additional headers sent with every request. */
+  headers?: Record<string, string>
+}
+
+type Query = Record<string, string | number | boolean | null | undefined>
+
+/** @internal A request to the API. */
+export interface Call {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  query?: Query
+  body?: unknown
+  /** The request can be repeated after a network failure without changing the outcome. */
+  idempotent: boolean
+  /** Statuses returned as data rather than thrown. */
+  acceptStatuses?: number[]
+  options?: RequestOptions | undefined
+}
+
+const DEFAULTS = { timeoutMs: 30_000, maxRetries: 2 }
+const MAX_RETRY_DELAY_MS = 60_000
+
+/** @internal Transport: base URL, authentication, timeouts, retries and error mapping. */
+export class HttpClient {
+  readonly baseUrl: string
+  readonly #apiKey: string
+  readonly #timeoutMs: number
+  readonly #maxRetries: number
+  readonly #fetch: typeof fetch
+  readonly #headers: Record<string, string>
+
+  constructor(options: ClientOptions, defaultBaseUrl: string) {
+    if (!options?.apiKey) throw new MonitoringError('apiKey is required')
+    this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/+$/, '')
+    this.#apiKey = options.apiKey
+    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 later, or pass options.fetch')
+    this.#fetch = f
+    this.#headers = { ...options.headers }
+  }
+
+  /** Sends a request and returns the parsed JSON response. */
+  async request<T>(call: Call): Promise<T> {
+    const url = this.#url(call.path, call.query)
+    const headers: Record<string, string> = {
+      accept: 'application/json',
+      'user-agent': `@v3finance/monitoring-sdk/${SDK_VERSION}`,
+      ...this.#headers,
+      'x-api-key': this.#apiKey,
+    }
+    if (call.body !== undefined) headers['content-type'] = 'application/json'
+    const body = call.body === undefined ? undefined : JSON.stringify(call.body)
+    const maxRetries = call.options?.maxRetries ?? this.#maxRetries
+    const timeoutMs = call.options?.timeoutMs ?? this.#timeoutMs
+    const signal = call.options?.signal
+
+    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, signal)
+      } catch (error) {
+        if (signal?.aborted) throw signal.reason
+        if (call.idempotent && attempt < maxRetries) {
+          await sleep(backoff(attempt), signal)
+          continue
+        }
+        throw error
+      }
+      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 and 503 mean the request was not processed, so retrying is safe for any method
+      if (error.retryable && attempt < maxRetries) {
+        await sleep(retryAfter(res.headers) ?? backoff(attempt), 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()
+  }
+
+  /** One attempt, with a single timeout covering both the connection and the response body. */
+  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 (error) {
+      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: ${(error as Error).message}`, { cause: error })
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+    }
+  }
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return text
+  }
+}
+
+/** Exponential backoff with jitter: ~0.5 s, 1 s, 2 s… capped at 8 s. */
+function backoff(attempt: number): number {
+  return Math.min(8_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2)
+}
+
+/** Delay from a `Retry-After` header: seconds or an HTTP date. */
+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 })
+  })
+}
+
+/** @internal Encodes a path segment. */
+export const seg = (value: string | number) => encodeURIComponent(String(value))