@v3finance/monitoring-sdk 0.1.0 → 0.2.0

package/src/core/http.ts

@@ -1,111 +1,112 @@
 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
-  /** Таймаут этого запроса, мс — вместо {@link ClientOptions.timeoutMs} */
+  /** Timeout for this request in milliseconds. Overrides {@link ClientOptions.timeoutMs}. */
   timeoutMs?: number
-  /** Сколько раз повторить этот запрос — вместо {@link ClientOptions.maxRetries} */
+  /** 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
   /**
-   * API-ключ: ключ клиента `ce_…` (адреса, история и транзакции своего клиента) или личный ключ `ce_user_…`
-   * (всё, что вы можете в панели, с вашими правами). Уходит в заголовке `x-api-key`.
+   * Your client ID. Optional: when omitted, it is resolved from the API key on first use and cached.
    */
-  apiKey?: string
-  /** Токен сессии из {@link MonitoringClient.signIn} — вместо `apiKey`. Уходит в `Authorization: Bearer` */
-  sessionToken?: string
-  /** Адрес API. По умолчанию `https://monitoring.v3.finance` */
+  clientId?: string
+  /** API base URL. Defaults to `https://monitoring.v3.finance`. */
   baseUrl?: string
-  /** Таймаут запроса, мс. По умолчанию 30 000 */
+  /** Request timeout in milliseconds. Defaults to `30000`. */
   timeoutMs?: number
   /**
-   * Сколько раз повторять запрос после временной ошибки. По умолчанию 2.
+   * Maximum number of retries for transient errors. Defaults to `2`.
    *
-   * Повторяются ответы 429 и 503 (запрос не был выполнен), а сбои сети и таймауты — только у запросов,
-   * которые безопасно выполнить дважды (чтение, снятие и добавление адресов, отзыв ключа). Пауза — из
-   * `Retry-After`, иначе экспоненциальная с разбросом.
+   * `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
-  /** Своя реализация `fetch` — для тестов, прокси, логирования. По умолчанию глобальный `fetch` */
+  /** 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>
 
-/** Описание одного запроса к API */
+/** @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
-  /** Статусы, которые возвращаются как данные, а не ошибка (тестовый вебхук: 502 — «не доставлен») */
+  /** Statuses returned as data rather than thrown. */
   acceptStatuses?: number[]
-  /** false — запрос без учётных данных (вход) */
-  auth?: boolean
   options?: RequestOptions | undefined
 }
 
 const DEFAULTS = { timeoutMs: 30_000, maxRetries: 2 }
 const MAX_RETRY_DELAY_MS = 60_000
 
-/** Транспорт SDK: адрес, авторизация, таймауты, повторы, разбор ошибок. Ресурсы ходят в API только через него */
+/** @internal Transport: base URL, authentication, timeouts, retries and error mapping. */
 export class HttpClient {
   readonly baseUrl: string
-  readonly #apiKey: string | undefined
-  readonly #sessionToken: string | undefined
+  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 && options.sessionToken) throw new MonitoringError('pass either apiKey or sessionToken, not both')
+    if (!options?.apiKey) throw new MonitoringError('apiKey is required')
     this.baseUrl = (options.baseUrl ?? defaultBaseUrl).replace(/\/+$/, '')
     this.#apiKey = options.apiKey
-    this.#sessionToken = options.sessionToken
     this.#timeoutMs = options.timeoutMs ?? DEFAULTS.timeoutMs
     this.#maxRetries = options.maxRetries ?? DEFAULTS.maxRetries
     const f = options.fetch ?? globalThis.fetch
-    if (typeof f !== 'function') throw new MonitoringError('fetch is not available: use Node.js 20+ or pass options.fetch')
+    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 }
   }
 
-  /** Выполняет запрос и возвращает разобранный JSON ответа */
+  /** 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 = this.#headersFor(call)
+    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, call.options?.signal)
-      } catch (e) {
-        if (call.options?.signal?.aborted) throw call.options.signal.reason
+        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), call.options?.signal)
+          await sleep(backoff(attempt), signal)
           continue
         }
-        throw e
+        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 и 503: запрос не выполнен — повтор безопасен для любого метода
+      // 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), call.options?.signal)
+        await sleep(retryAfter(res.headers) ?? backoff(attempt), signal)
         continue
       }
       throw error
@@ -118,18 +119,7 @@ export class HttpClient {
     return url.toString()
   }
 
-  #headersFor(call: Call): Record<string, string> {
-    const headers: Record<string, string> = { accept: 'application/json', 'user-agent': `@v3finance/monitoring-sdk/${SDK_VERSION}`, ...this.#headers }
-    if (call.body !== undefined) headers['content-type'] = 'application/json'
-    if (call.auth !== false) {
-      if (this.#apiKey) headers['x-api-key'] = this.#apiKey
-      else if (this.#sessionToken) headers.authorization = `Bearer ${this.#sessionToken}`
-      else throw new MonitoringError('credentials required: pass apiKey or sessionToken to MonitoringClient')
-    }
-    return headers
-  }
-
-  /** Один запрос с таймаутом на всё — и соединение, и чтение тела */
+  /** 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)
@@ -140,11 +130,11 @@ export class HttpClient {
       const res = await this.#fetch(url, { ...init, signal: controller.signal })
       const text = await res.text()
       return { status: res.status, headers: res.headers, data: text ? parseJson(text) : undefined }
-    } catch (e) {
+    } 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: ${(e as Error).message}`, { cause: e })
+      throw new MonitoringConnectionError(`request to ${new URL(url).origin} failed: ${(error as Error).message}`, { cause: error })
     } finally {
       clearTimeout(timer)
       signal?.removeEventListener('abort', onAbort)
@@ -160,12 +150,12 @@ function parseJson(text: string): unknown {
   }
 }
 
-/** Экспоненциальная пауза с разбросом: ~0,5 с, 1 с, 2 с… не больше 8 с */
+/** 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)
 }
 
-/** Пауза из заголовка Retry-After: секунды или дата */
+/** 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
@@ -189,5 +179,5 @@ function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
   })
 }
 
-/** Сегмент пути: id клиента, хеш и т. п. */
+/** @internal Encodes a path segment. */
 export const seg = (value: string | number) => encodeURIComponent(String(value))

package/src/core/pagination.ts

@@ -1,17 +1,16 @@
 /**
- * Страница списка. `next` — курсор следующей страницы; `null` — страниц больше нет.
+ * A page of results. `next` is the cursor of the next page; `null` when there are no more pages.
  *
- * @typeParam T - элемент списка
- * @typeParam Cursor - тип курсора: строка (клиенты) или число (адреса, история)
+ * @typeParam T - Item type.
  */
-export interface Page<T, Cursor = string | number> {
+export interface Page<T> {
   items: T[]
-  next: Cursor | null
+  next: number | null
 }
 
-/** Обходит все страницы по порядку, запрашивая следующую, только когда закончилась текущая */
-export async function* paginate<T, Cursor>(fetchPage: (cursor: Cursor | undefined) => Promise<Page<T, Cursor>>): AsyncGenerator<T, void, undefined> {
-  let cursor: Cursor | undefined
+/** @internal Yields every item, fetching the next page only when the current one is exhausted. */
+export async function* paginate<T>(fetchPage: (cursor: number | undefined) => Promise<Page<T>>): AsyncGenerator<T, void, undefined> {
+  let cursor: number | undefined
   for (;;) {
     const page = await fetchPage(cursor)
     yield* page.items

package/src/core/scope.ts

@@ -0,0 +1,8 @@
+import type { HttpClient } from './http.js'
+
+/** @internal What resources share: the transport and the client ID of the API key. */
+export interface Scope {
+  http: HttpClient
+  /** Path segment of the client: resolved from the API key once, then cached. */
+  clientPath: () => Promise<string>
+}