@v3finance/monitoring-sdk 0.1.0 → 0.2.0

package/dist/esm/webhooks.d.ts

@@ -1,56 +1,60 @@
 /**
- * Приём вебхуков: проверка подписи и разбор тела. Работает без клиента API и без сети — нужен только секрет
- * подписи клиента. Использует WebCrypto: Node.js 20+, Bun, Deno, Cloudflare Workers.
+ * 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 сырого тела секретом клиента, hex в нижнем регистре */
+    /** HMAC-SHA256 of the raw body keyed with your webhook secret, hex-encoded. */
     readonly signature: 'x-signature';
-    /** id клиента */
+    /** Your client ID. */
     readonly clientId: 'x-client-id';
-    /** `1` у тестового вебхука — такой не зачислять */
+    /** `1` for test webhooks. */
     readonly test: 'x-webhook-test';
 };
 /**
- * Тело вебхука ровно как пришло — сырые байты или строка. Не `JSON.parse` + `JSON.stringify`: подпись считается
- * по исходным байтам, и любое переформатирование её ломает.
+ * 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;
 /**
- * Откуда взять подпись: значение заголовка `x-signature` или все заголовки запроса — Fetch `Headers`
- * (Hono, Next.js, Workers) или объект Node.js (`req.headers` в Express, Fastify).
+ * 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: { …, id: 'test' } })
- * await fetch('http://localhost:3000/webhooks', { method: 'POST', body, headers: { 'x-signature': await signWebhookBody(body, secret) } })
+ * 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>;
 /**
- * Проверяет подпись вебхука: `true` — тело пришло от сервиса и не изменено.
+ * Verifies a webhook signature. Returns `true` when the body was sent by the API and was not modified.
  *
- * @param body - сырое тело запроса
- * @param signature - заголовок `x-signature` или все заголовки запроса
- * @param secret - секрет подписи клиента
+ * @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.
  *
- * Дальше — по правилам приёма: тестовый вебхук ({@link isTestWebhook}) не зачислять; один и тот же вебхук может
- * прийти повторно — обрабатывайте идемпотентно по {@link webhookIdempotencyKey}; ответьте 2xx в течение 15 секунд.
- * Вебхук уходит, как только перевод попал в блок, — для крупных сумм дождитесь финальности
- * (`monitoring.transactions.get(...).final`).
+ * 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} подпись не совпала — ответьте 401 и ничего не зачисляйте
+ * @throws {@link WebhookSignatureError} when the signature does not match. Respond with `401` and do not process it.
  *
- * @example Express — нужен сырой body
+ * @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!)
@@ -59,17 +63,18 @@ export declare function verifyWebhookSignature(body: WebhookBody, signature: Sig
  * })
  * ```
  *
- * @example Hono, Next.js route handler, Cloudflare Workers
+ * @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>;
-/** Тестовый вебхук (из панели или `clients.sendTestWebhook`) — такой не зачислять */
+/** `true` for test webhooks. Do not credit them. */
 export declare function isTestWebhook(event: WebhookPayload): boolean;
 /**
- * Ключ идемпотентности вебхука: сеть, транзакция и номер лога. Один перевод — один ключ, даже если вебхук пришёл
- * несколько раз. В одной транзакции EVM может быть несколько переводов токенов — у них разный `logIndex`.
+ * 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"`
  */

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

@@ -1 +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,wBAAwB;AACxB,eAAO,MAAM,eAAe;IAC1B,sEAAsE;aACtE,SAAS,EAAE,aAAa;IACxB,iBAAiB;aACjB,QAAQ,EAAE,aAAa;IACvB,mDAAmD;aACnD,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;;;;;;;;GAQG;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,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEnE"}
+{"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

@@ -1,22 +1,22 @@
 /**
- * Приём вебхуков: проверка подписи и разбор тела. Работает без клиента API и без сети — нужен только секрет
- * подписи клиента. Использует WebCrypto: Node.js 20+, Bun, Deno, Cloudflare Workers.
+ * 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 сырого тела секретом клиента, hex в нижнем регистре */
+    /** HMAC-SHA256 of the raw body keyed with your webhook secret, hex-encoded. */
     signature: 'x-signature',
-    /** id клиента */
+    /** Your client ID. */
     clientId: 'x-client-id',
-    /** `1` у тестового вебхука — такой не зачислять */
+    /** `1` for test webhooks. */
     test: 'x-webhook-test',
 };
 const encoder = new TextEncoder();
 function bytesOf(body) {
     if (typeof body === 'string')
         return encoder.encode(body);
-    // копия: WebCrypto не принимает view над SharedArrayBuffer (Buffer в Node.js — тоже Uint8Array)
+    // 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) {
@@ -29,7 +29,7 @@ function signatureOf(source) {
     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;
@@ -39,12 +39,16 @@ function safeEqual(a, b) {
     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: { …, id: 'test' } })
- * await fetch('http://localhost:3000/webhooks', { method: 'POST', body, headers: { 'x-signature': await signWebhookBody(body, secret) } })
+ * 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) {
@@ -53,11 +57,11 @@ export async function signWebhookBody(body, secret) {
     return Array.from(mac, (b) => b.toString(16).padStart(2, '0')).join('');
 }
 /**
- * Проверяет подпись вебхука: `true` — тело пришло от сервиса и не изменено.
+ * Verifies a webhook signature. Returns `true` when the body was sent by the API and was not modified.
  *
- * @param body - сырое тело запроса
- * @param signature - заголовок `x-signature` или все заголовки запроса
- * @param secret - секрет подписи клиента
+ * @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();
@@ -66,16 +70,16 @@ export async function verifyWebhookSignature(body, signature, secret) {
     return safeEqual(await signWebhookBody(body, secret), given);
 }
 /**
- * Проверяет подпись и возвращает разобранный вебхук.
+ * Verifies the signature and returns the parsed webhook.
  *
- * Дальше — по правилам приёма: тестовый вебхук ({@link isTestWebhook}) не зачислять; один и тот же вебхук может
- * прийти повторно — обрабатывайте идемпотентно по {@link webhookIdempotencyKey}; ответьте 2xx в течение 15 секунд.
- * Вебхук уходит, как только перевод попал в блок, — для крупных сумм дождитесь финальности
- * (`monitoring.transactions.get(...).final`).
+ * 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} подпись не совпала — ответьте 401 и ничего не зачисляйте
+ * @throws {@link WebhookSignatureError} when the signature does not match. Respond with `401` and do not process it.
  *
- * @example Express — нужен сырой body
+ * @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!)
@@ -84,7 +88,7 @@ export async function verifyWebhookSignature(body, signature, secret) {
  * })
  * ```
  *
- * @example Hono, Next.js route handler, Cloudflare Workers
+ * @example Next.js route handlers, Hono, Cloudflare Workers
  * ```ts
  * const event = await parseWebhook(await request.text(), request.headers, env.MONITORING_WEBHOOK_SECRET)
  * ```
@@ -96,21 +100,22 @@ export async function parseWebhook(body, signature, secret) {
     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 });
+    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;
 }
-/** Тестовый вебхук (из панели или `clients.sendTestWebhook`) — такой не зачислять */
+/** `true` for test webhooks. Do not credit them. */
 export function isTestWebhook(event) {
     return event.test === true;
 }
 /**
- * Ключ идемпотентности вебхука: сеть, транзакция и номер лога. Один перевод — один ключ, даже если вебхук пришёл
- * несколько раз. В одной транзакции EVM может быть несколько переводов токенов — у них разный `logIndex`.
+ * 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"`
  */

package/dist/esm/webhooks.js.map

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

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@v3finance/monitoring-sdk",
-  "version": "0.1.0",
-  "description": "Official TypeScript SDK for the V3 Finance address monitoring API: TRON and EVM addresses, signed webhooks, delivery history, transaction finality",
+  "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",
-    "webhooks",
     "blockchain",
-    "monitoring",
     "payments",
+    "crypto",
     "sdk",
-    "v3finance"
+    "typescript"
   ],
   "homepage": "https://monitoring.v3.finance/docs",
   "repository": {

package/src/client.ts

@@ -1,94 +1,83 @@
-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 { 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 { ClientsResource } from './resources/clients.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'
 
 /**
- * Клиент API мониторинга адресов V3 Finance: адреса и подписки, история вебхуков, транзакции, ваш клиент и ключи.
- * Только для сервера: ключ в браузере увидит любой.
+ * Client for the V3 Finance Monitoring API.
  *
- * @example С ключом клиента — для бэкенда
+ * 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(clientId, [{ network: 'tron', address: 'T…' }], { assets: ['USDT'], direction: 'in' })
- * ```
+ * const monitoring = new MonitoringClient({ apiKey: process.env.MONITORING_API_KEY! })
  *
- * @example По паролю — для скриптов, которым нужны права пользователя
- * ```ts
- * const { client } = await MonitoringClient.signIn({ email, password })
- * const { key } = await client.account.keys.create({ name: 'ci' })
+ * 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
-  /** Выход и смена пароля (для клиента, вошедшего по паролю) */
-  readonly auth: AuthResource
-  /** Сети */
-  readonly networks: NetworksResource
-  /** Нативные монеты и токены */
-  readonly assets: AssetsResource
-  /** Ваш клиент: URL вебхука, секрет, ключи, участники, тестовый вебхук */
-  readonly clients: ClientsResource
-  /** Адреса на мониторинге и подписка */
+  /** 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 - ключ (`apiKey`) или токен сессии (`sessionToken`), адрес API, таймаут, повторы
-   * @throws {@link MonitoringError} переданы и ключ, и токен; нет `fetch`
+   * @param options - API key and optional settings.
+   * @throws {@link MonitoringError} when `apiKey` is missing or `fetch` is not available.
    */
-  constructor(options: ClientOptions = {}) {
+  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)
+    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, с которым работает клиент */
+  /** API base URL this client sends requests to. */
   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 }) }
+  /** 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

@@ -1,18 +1,18 @@
 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]
 
 /**
- * Базовый класс всех ошибок SDK. Ловите его, чтобы перехватить любую ошибку SDK.
+ * Base class of every error thrown by the 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
+ *   await monitoring.addresses.add(items)
+ * } catch (error) {
+ *   if (error instanceof MonitoringApiError && error.status === 400) console.log(error.details)
+ *   else throw error
  * }
  * ```
  */
@@ -23,20 +23,20 @@ export class MonitoringError extends Error {
   }
 }
 
-/** API ответил ошибкой: HTTP 4xx или 5xx */
+/** The API responded with an error status (4xx or 5xx). */
 export class MonitoringApiError extends MonitoringError {
-  /** HTTP-статус ответа */
+  /** HTTP status code. */
   readonly status: number
   /**
-   * Машинный код ошибки: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `conflict`,
-   * `rate_limited`, `upstream_error`, `upstream_rate_limited`, `unavailable`…
+   * 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[]
-  /** Идентификатор запроса (`cf-ray`) — укажите его, если обращаетесь в поддержку */
+  /** 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 }) {
@@ -49,13 +49,13 @@ export class MonitoringApiError extends MonitoringError {
     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)
@@ -63,7 +63,7 @@ export class MonitoringConnectionError extends MonitoringError {
   }
 }
 
-/** Запрос не уложился в таймаут (`timeoutMs`) */
+/** The request did not complete within `timeoutMs`. */
 export class MonitoringTimeoutError extends MonitoringConnectionError {
   constructor(timeoutMs: number) {
     super(`request timed out after ${timeoutMs} ms`)
@@ -71,7 +71,7 @@ export class MonitoringTimeoutError extends MonitoringConnectionError {
   }
 }
 
-/** Подпись вебхука не прошла проверку: тело подделано, изменено по дороге или проверяется не тем секретом */
+/** 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)
@@ -79,7 +79,7 @@ export class WebhookSignatureError extends MonitoringError {
   }
 }
 
-/** Тело ошибки в любом из форматов API: `/v1`, старые пути (`{ok: false}`), вход (`{code, message}`) */
+/** 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