@v3finance/monitoring-sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this package are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com), and this project adheres to [Semantic Versioning](https://semver.org).
+
+## 0.2.0 — 2026-10-28
+
+### Breaking changes
+
+- `MonitoringClient` authenticates with an API key only. Your client ID is resolved from the key, so methods no
+  longer take it as a parameter.
+- Removed account management APIs: `MonitoringClient.signIn`, `auth`, `account.keys` and `clients`.
+- `clients.sendTestWebhook()` is now `webhooks.sendTest()`.
+- `AddressDefaults` is renamed to `SubscriptionDefaults`, and `AddressSubscriptionUpdate` to `AddressUpdate`.
+
+### Added
+
+- `account.get()` and `account.id()`.
+
+### Changed
+
+- Documentation and type descriptions are now in English.
+
+## 0.1.0 — 2026-10-28
+
+- Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 V3 Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+# V3 Finance Monitoring SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@v3finance/monitoring-sdk.svg)](https://www.npmjs.com/package/@v3finance/monitoring-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@v3finance/monitoring-sdk.svg)](https://www.npmjs.com/package/@v3finance/monitoring-sdk)
+[![types](https://img.shields.io/npm/types/@v3finance/monitoring-sdk.svg)](https://www.npmjs.com/package/@v3finance/monitoring-sdk)
+[![license](https://img.shields.io/npm/l/@v3finance/monitoring-sdk.svg)](./LICENSE)
+
+The official TypeScript SDK for the [V3 Finance Monitoring API](https://monitoring.v3.finance/docs).
+Monitor addresses on TRON and EVM networks and receive a signed webhook for every incoming and outgoing transfer.
+
+- **Address monitoring** with per-address subscriptions: choose the assets and the direction you are notified about.
+- **Webhooks** with signature verification and fully typed payloads.
+- **Transaction lookup** with confirmations and finality, for any transaction on a supported network.
+- **Delivery history** of every webhook sent to you.
+- **Production-ready**: automatic retries, timeouts, cancellation, pagination and batching.
+- **Fully typed**, zero dependencies, ESM and CommonJS. Runs on Node.js, Bun, Deno and Cloudflare Workers.
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Addresses](#addresses)
+- [Receiving webhooks](#receiving-webhooks)
+- [Transactions and finality](#transactions-and-finality)
+- [Delivery history](#delivery-history)
+- [Networks and assets](#networks-and-assets)
+- [Amounts](#amounts)
+- [Error handling](#error-handling)
+- [Retries, timeouts and cancellation](#retries-timeouts-and-cancellation)
+- [TypeScript](#typescript)
+- [Requirements](#requirements)
+- [Security](#security)
+- [Versioning](#versioning)
+- [Support](#support)
+
+## Installation
+
+```bash
+npm install @v3finance/monitoring-sdk
+```
+
+```bash
+pnpm add @v3finance/monitoring-sdk
+yarn add @v3finance/monitoring-sdk
+bun add @v3finance/monitoring-sdk
+```
+
+## Quick start
+
+```ts
+import { MonitoringClient } from '@v3finance/monitoring-sdk'
+
+const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY! })
+
+// Notify about incoming USDT on a deposit address
+await monitoring.addresses.add(
+  [{ network: 'tron', address: 'TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr', label: 'user-42' }],
+  { assets: ['USDT'], direction: 'in' },
+)
+```
+
+Every transfer on the address now triggers a signed webhook to your endpoint — see
+[Receiving webhooks](#receiving-webhooks).
+
+## Configuration
+
+```ts
+const monitoring = new MonitoringClient({
+  apiKey: process.env.MONITORING_API_KEY!,
+  timeoutMs: 10_000,
+  maxRetries: 3,
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | Your API key. **Required.** |
+| `clientId` | `string` | resolved from the API key | Your client ID. |
+| `baseUrl` | `string` | `https://monitoring.v3.finance` | API base URL. |
+| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds. |
+| `maxRetries` | `number` | `2` | Retries for rate limits and transient errors. |
+| `fetch` | `typeof fetch` | global `fetch` | Custom `fetch` implementation. |
+| `headers` | `Record<string, string>` | — | Additional headers sent with every request. |
+
+## Addresses
+
+An address is monitored on a single network; to watch an EVM address on several networks, add it once per network.
+Each address has a **subscription** — which assets (`assets`) and which direction (`direction`: `in`, `out` or
+`both`) you are notified about. By default it covers all assets of the network in both directions.
+
+```ts
+// Add — lists larger than 1,000 addresses are sent in batches automatically
+await monitoring.addresses.add(
+  [
+    { network: 'tron', address: 'TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr', label: 'user-42' },
+    { network: 'ethereum', address: '0x533bcdd534fc3f9651471d7b4469a0d01ca45a2a', assets: ['USDT', 'USDC'] },
+  ],
+  { direction: 'in' },
+)
+
+// Change the subscription
+await monitoring.addresses.update([{ network: 'tron', address: 'TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr' }], { direction: 'both' })
+
+// Iterate over all monitored addresses
+for await (const address of monitoring.addresses.iterate({ network: 'tron' })) {
+  console.log(address.address, address.assets ?? 'all assets', address.direction)
+}
+
+// Stop monitoring
+await monitoring.addresses.remove([{ network: 'tron', address: 'TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr' }])
+```
+
+Requests are validated as a whole: if any address is invalid for its network, nothing is changed and
+`error.details` lists the problems by index.
+
+## Receiving webhooks
+
+Every webhook is a `POST` request with a JSON body and an `x-signature` header — an HMAC-SHA256 of the raw body keyed
+with your webhook secret. `parseWebhook` verifies the signature and returns a typed payload.
+
+**Express**
+
+```ts
+import express from 'express'
+import { isTestWebhook, parseWebhook, webhookIdempotencyKey, WebhookSignatureError } from '@v3finance/monitoring-sdk'
+
+const app = express()
+
+app.post('/webhooks/monitoring', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    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)
+  } catch (error) {
+    if (error instanceof WebhookSignatureError) return res.sendStatus(401)
+    throw error
+  }
+})
+```
+
+**Next.js (App Router)** — and any runtime built on the Fetch API: Cloudflare Workers, Bun, Deno
+
+```ts
+export async function POST(request: Request) {
+  const event = await parseWebhook(await request.text(), request.headers, process.env.MONITORING_WEBHOOK_SECRET!)
+  // …
+  return new Response(null, { status: 200 })
+}
+```
+
+**Hono**
+
+```ts
+app.post('/webhooks/monitoring', async (c) => {
+  const event = await parseWebhook(await c.req.text(), c.req.raw.headers, c.env.MONITORING_WEBHOOK_SECRET)
+  // …
+  return c.body(null, 200)
+})
+```
+
+The payload:
+
+```json
+{
+  "tx": {
+    "network": "TRON",
+    "asset": "USDT",
+    "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
+    "type": "TOPUP",
+    "id": "1249cb7b7edd42072684b1db37ad495d4a5b7eefd1aff83e595e9bdb63a5fc45",
+    "block": 87445412,
+    "timestamp": 1793009472000,
+    "from": "TW9goADYcUxskhQQRifvwoRBUMHnmTh9MA",
+    "to": "TA8HgQbFjuMLWCaJeGyfrv8FErWSHz82vr",
+    "value": "100000000"
+  }
+}
+```
+
+Best practices:
+
+- **Verify against the raw body.** Parsing and re-serializing the JSON changes the bytes and breaks the signature.
+- **Respond quickly.** Return a 2xx status within 15 seconds; otherwise the webhook is retried after 10 seconds,
+  1 minute and 5 minutes.
+- **Process idempotently.** A webhook may be delivered more than once — deduplicate with `webhookIdempotencyKey(event)`.
+- **Check the direction.** `type` is `TOPUP` for both directions; compare `from` and `to` with your addresses.
+- **Wait for finality on large amounts.** Webhooks are sent as soon as a transfer is included in a block — see
+  [Transactions and finality](#transactions-and-finality).
+- **Ignore test webhooks** — `isTestWebhook(event)` is `true` for them.
+
+Send a test webhook to check your endpoint:
+
+```ts
+const { delivery, signature, body } = await monitoring.webhooks.sendTest({ asset: 'USDT' })
+console.log(delivery.ok ? 'Delivered' : `Endpoint responded with ${delivery.status ?? delivery.error}`)
+```
+
+## Transactions and finality
+
+Look up any transaction on a supported network — not only the ones you were notified about.
+
+```ts
+const tx = await monitoring.transactions.get('tron', event.tx.id)
+
+tx.status        // 'success' | 'failed' | 'pending'
+tx.confirmations // blocks since inclusion
+tx.final         // the transaction can no longer be reverted
+tx.fee           // { asset: 'TRX', value: '6773500' }
+tx.transfers     // every transfer inside the transaction
+tx.watched       // your monitored addresses involved
+tx.webhooks      // webhooks sent to you for this transaction
+```
+
+A transaction is final once its block is solidified on TRON (about 1 minute) or finalized on EVM networks (about
+13 minutes on Ethereum). Credit large amounts once `final` is `true`.
+
+## Delivery history
+
+Every webhook sent to you is recorded with its status, attempts and your endpoint's response, and kept for 90 days.
+
+```ts
+for await (const delivery of monitoring.deliveries.iterate({ status: 'failed', since: new Date(Date.now() - 86_400_000) })) {
+  console.log(delivery.txId, delivery.attempts, delivery.lastHttpStatus ?? delivery.lastError)
+}
+
+const detail = await monitoring.deliveries.get(deliveryId) // includes the exact request body
+```
+
+Filter by `status` (`delivered`, `retrying`, `failed`), `network`, `asset`, `tx`, `address`, `since` and `until`.
+
+## Networks and assets
+
+```ts
+const networks = await monitoring.networks.list()
+const assets = await monitoring.assets.list({ network: 'tron' })
+```
+
+You are notified about transfers of enabled assets of at least the asset's `minAmount`.
+
+## Amounts
+
+Amounts are strings in the asset's smallest unit (sun, wei; USDT has 6 decimals). Convert them without losing
+precision:
+
+```ts
+import { formatUnits, parseUnits } from '@v3finance/monitoring-sdk'
+
+formatUnits('100000000', 6) // '100'
+parseUnits('1.5', 6)        // '1500000'
+```
+
+## Error handling
+
+All errors extend `MonitoringError`.
+
+| Error | When |
+|---|---|
+| `MonitoringApiError` | The API responded with an error. Has `status`, `code`, `details` and `requestId`. |
+| `MonitoringConnectionError` | The request failed to reach the API. |
+| `MonitoringTimeoutError` | The request exceeded `timeoutMs`. |
+| `WebhookSignatureError` | A webhook signature does not match. |
+
+```ts
+import { MonitoringApiError } from '@v3finance/monitoring-sdk'
+
+try {
+  await monitoring.addresses.add(items)
+} catch (error) {
+  if (error instanceof MonitoringApiError && error.status === 400) {
+    for (const { index, message } of error.details) console.error(`Item ${index}: ${message}`)
+  } else {
+    throw error
+  }
+}
+```
+
+## Retries, timeouts and cancellation
+
+Rate-limited (`429`) and temporarily unavailable (`503`) requests are retried automatically with exponential backoff,
+honoring `Retry-After`. Network errors are retried only for requests that are safe to repeat. Configure this with
+`maxRetries` and `timeoutMs`, globally or per request:
+
+```ts
+const controller = new AbortController()
+
+await monitoring.addresses.list({ network: 'tron' }, { timeoutMs: 5_000, maxRetries: 0, signal: controller.signal })
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and ships its own type declarations. All request and response types are exported:
+
+```ts
+import type { Address, Delivery, Transaction, WebhookPayload } from '@v3finance/monitoring-sdk'
+```
+
+## Requirements
+
+- Node.js 20 or later, Bun, Deno or Cloudflare Workers.
+- ESM (`import`) and CommonJS (`require`) are both supported.
+
+## Security
+
+- Use the SDK on your servers only. Never expose your API key or webhook secret to browsers or mobile apps.
+- Keep credentials in environment variables or a secrets manager, not in source code.
+- Always verify webhook signatures before processing a webhook.
+
+## Versioning
+
+This package follows [Semantic Versioning](https://semver.org). Changes are listed in [CHANGELOG.md](./CHANGELOG.md).
+
+## Support
+
+- API reference: [monitoring.v3.finance/docs](https://monitoring.v3.finance/docs)
+- OpenAPI specification: [monitoring.v3.finance/openapi.json](https://monitoring.v3.finance/openapi.json)
+- For access and support, contact your V3 Finance account manager.
+
+## License
+
+[MIT](./LICENSE) © V3 Finance

package/dist/cjs/client.d.ts

@@ -0,0 +1,46 @@
+import { type ClientOptions } from './core/http.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';
+/**
+ * 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 declare class MonitoringClient {
+    #private;
+    /** 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;
+    /**
+     * @param options - API key and optional settings.
+     * @throws {@link MonitoringError} when `apiKey` is missing or `fetch` is not available.
+     */
+    constructor(options: ClientOptions);
+    /** API base URL this client sends requests to. */
+    get baseUrl(): string;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAG1D;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAA;IAC3C,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAK/B;;;OAGG;IACH,YAAY,OAAO,EAAE,aAAa,EAWjC;IAED,kDAAkD;IAClD,IAAI,OAAO,IAAI,MAAM,CAEpB;CAiBF"}

package/dist/cjs/client.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MonitoringClient = void 0;
+const errors_js_1 = require("./core/errors.js");
+const http_js_1 = require("./core/http.js");
+const account_js_1 = require("./resources/account.js");
+const addresses_js_1 = require("./resources/addresses.js");
+const catalog_js_1 = require("./resources/catalog.js");
+const deliveries_js_1 = require("./resources/deliveries.js");
+const transactions_js_1 = require("./resources/transactions.js");
+const webhooks_js_1 = require("./resources/webhooks.js");
+const version_js_1 = require("./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' })
+ * ```
+ */
+class MonitoringClient {
+    /** Your client: the account your API key belongs to. */
+    account;
+    /** Addresses you monitor and their subscriptions. */
+    addresses;
+    /** Test your webhook endpoint. */
+    webhooks;
+    /** History of webhooks sent to you. */
+    deliveries;
+    /** Any transaction by hash, with confirmations and finality. */
+    transactions;
+    /** Supported networks. */
+    networks;
+    /** Supported native coins and tokens. */
+    assets;
+    #http;
+    #clientId;
+    /**
+     * @param options - API key and optional settings.
+     * @throws {@link MonitoringError} when `apiKey` is missing or `fetch` is not available.
+     */
+    constructor(options) {
+        this.#http = new http_js_1.HttpClient(options, version_js_1.DEFAULT_BASE_URL);
+        if (options.clientId)
+            this.#clientId = Promise.resolve(options.clientId);
+        const scope = { http: this.#http, clientPath: async () => `/v1/clients/${(0, http_js_1.seg)(await this.#resolveClientId())}` };
+        this.account = new account_js_1.AccountResource(scope, () => this.#resolveClientId());
+        this.addresses = new addresses_js_1.AddressesResource(scope);
+        this.webhooks = new webhooks_js_1.WebhooksResource(scope);
+        this.deliveries = new deliveries_js_1.DeliveriesResource(scope);
+        this.transactions = new transactions_js_1.TransactionsResource(scope);
+        this.networks = new catalog_js_1.NetworksResource(scope);
+        this.assets = new catalog_js_1.AssetsResource(scope);
+    }
+    /** API base URL this client sends requests to. */
+    get baseUrl() {
+        return this.#http.baseUrl;
+    }
+    /** Client ID of the API key: from the options, or resolved once from the API and cached. */
+    #resolveClientId() {
+        this.#clientId ??= this.#http.request({ method: 'GET', path: '/v1/me', idempotent: true }).then((identity) => {
+            if (!identity.actor.clientId)
+                throw new errors_js_1.MonitoringError('this API key is not bound to a client: pass clientId in the options');
+            return identity.actor.clientId;
+        }, (error) => {
+            // a failed lookup is not cached: the next call tries again
+            this.#clientId = undefined;
+            throw error;
+        });
+        return this.#clientId;
+    }
+}
+exports.MonitoringClient = MonitoringClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;;AAAA,gDAAkD;AAClD,4CAAoE;AAGpE,uDAAwD;AACxD,2DAA4D;AAC5D,uDAAyE;AACzE,6DAA8D;AAC9D,iEAAkE;AAClE,yDAA0D;AAC1D,6CAA+C;AAE/C;;;;;;;;;;;;;GAaG;AACH;IACE,wDAAwD;IAC/C,OAAO,CAAiB;IACjC,qDAAqD;IAC5C,SAAS,CAAmB;IACrC,kCAAkC;IACzB,QAAQ,CAAkB;IACnC,uCAAuC;IAC9B,UAAU,CAAoB;IACvC,gEAAgE;IACvD,YAAY,CAAsB;IAC3C,0BAA0B;IACjB,QAAQ,CAAkB;IACnC,yCAAyC;IAChC,MAAM,CAAgB;IAEtB,KAAK,CAAY;IAC1B,SAAS,CAA6B;IAEtC;;;OAGG;IACH,YAAY,OAAsB;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,oBAAU,CAAC,OAAO,EAAE,6BAAgB,CAAC,CAAA;QACtD,IAAI,OAAO,CAAC,QAAQ;YAAE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QACxE,MAAM,KAAK,GAAU,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,eAAe,IAAA,aAAG,EAAC,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAA;QACtH,IAAI,CAAC,OAAO,GAAG,IAAI,4BAAe,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAA;QACxE,IAAI,CAAC,SAAS,GAAG,IAAI,gCAAiB,CAAC,KAAK,CAAC,CAAA;QAC7C,IAAI,CAAC,QAAQ,GAAG,IAAI,8BAAgB,CAAC,KAAK,CAAC,CAAA;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,kCAAkB,CAAC,KAAK,CAAC,CAAA;QAC/C,IAAI,CAAC,YAAY,GAAG,IAAI,sCAAoB,CAAC,KAAK,CAAC,CAAA;QACnD,IAAI,CAAC,QAAQ,GAAG,IAAI,6BAAgB,CAAC,KAAK,CAAC,CAAA;QAC3C,IAAI,CAAC,MAAM,GAAG,IAAI,2BAAc,CAAC,KAAK,CAAC,CAAA;IACzC,CAAC;IAED,kDAAkD;IAClD,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAA;IAC3B,CAAC;IAED,4FAA4F;IAC5F,gBAAgB;QACd,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAW,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACvG,CAAC,QAAQ,EAAE,EAAE;YACX,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ;gBAAE,MAAM,IAAI,2BAAe,CAAC,qEAAqE,CAAC,CAAA;YAC9H,OAAO,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAA;QAChC,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,2DAA2D;YAC3D,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;YAC1B,MAAM,KAAK,CAAA;QACb,CAAC,CACF,CAAA;QACD,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;CACF"}

package/dist/cjs/core/errors.d.ts

@@ -0,0 +1,64 @@
+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 declare class MonitoringError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The API responded with an error status (4xx or 5xx). */
+export declare 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;
+    });
+    /** `true` for transient errors — rate limits and unavailable upstream providers — that can be retried later. */
+    get retryable(): boolean;
+}
+/** The request did not get a response because of a network or connection failure. */
+export declare class MonitoringConnectionError extends MonitoringError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request did not complete within `timeoutMs`. */
+export declare class MonitoringTimeoutError extends MonitoringConnectionError {
+    constructor(timeoutMs: number);
+}
+/** The webhook signature does not match: the body was altered or is verified with the wrong secret. */
+export declare class WebhookSignatureError extends MonitoringError {
+    constructor(message?: string);
+}
+/** Builds an error from any error body the API returns. */
+export declare function apiErrorFrom(status: number, body: unknown, requestId: string | undefined): MonitoringApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/E;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED,2DAA2D;AAC3D,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAA;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IAEtB,YAAY,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,EAQ/H;IAED,gHAAgH;IAChH,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED,qFAAqF;AACrF,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAED,uDAAuD;AACvD,qBAAa,sBAAuB,SAAQ,yBAAyB;IACnE,YAAY,SAAS,EAAE,MAAM,EAG5B;CACF;AAED,uGAAuG;AACvG,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,YAAY,OAAO,SAA+B,EAGjD;CACF;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CAW7G"}

package/dist/cjs/core/errors.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSignatureError = exports.MonitoringTimeoutError = exports.MonitoringConnectionError = exports.MonitoringApiError = exports.MonitoringError = void 0;
+exports.apiErrorFrom = apiErrorFrom;
+/**
+ * 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
+ * }
+ * ```
+ */
+class MonitoringError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MonitoringError';
+    }
+}
+exports.MonitoringError = MonitoringError;
+/** The API responded with an error status (4xx or 5xx). */
+class MonitoringApiError extends MonitoringError {
+    /** HTTP status code. */
+    status;
+    /**
+     * Machine-readable error code, e.g. `invalid_request`, `unauthorized`, `forbidden`, `not_found`,
+     * `rate_limited`, `upstream_error`, `upstream_rate_limited`.
+     */
+    code;
+    /** Per-item problems of a batch request, such as invalid addresses. Empty when there are none. */
+    details;
+    /** Request ID. Include it when contacting support. */
+    requestId;
+    /** Raw response body. */
+    body;
+    constructor(init) {
+        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() {
+        return this.status === 429 || this.status === 503;
+    }
+}
+exports.MonitoringApiError = MonitoringApiError;
+/** The request did not get a response because of a network or connection failure. */
+class MonitoringConnectionError extends MonitoringError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MonitoringConnectionError';
+    }
+}
+exports.MonitoringConnectionError = MonitoringConnectionError;
+/** The request did not complete within `timeoutMs`. */
+class MonitoringTimeoutError extends MonitoringConnectionError {
+    constructor(timeoutMs) {
+        super(`request timed out after ${timeoutMs} ms`);
+        this.name = 'MonitoringTimeoutError';
+    }
+}
+exports.MonitoringTimeoutError = MonitoringTimeoutError;
+/** The webhook signature does not match: the body was altered or is verified with the wrong secret. */
+class WebhookSignatureError extends MonitoringError {
+    constructor(message = 'webhook signature mismatch') {
+        super(message);
+        this.name = 'WebhookSignatureError';
+    }
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/** Builds an error from any error body the API returns. */
+function apiErrorFrom(status, body, requestId) {
+    const b = (body ?? {});
+    const v1 = typeof b.error === 'object' && b.error !== null ? b.error : 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 : []);
+    return new MonitoringApiError({ status, code, message, details, requestId, body });
+}
+function defaultCode(status) {
+    const codes = { 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 409: 'conflict', 429: 'rate_limited' };
+    return codes[status] ?? (status >= 500 ? 'server_error' : 'http_error');
+}
+//# sourceMappingURL=errors.js.map