@v3finance/monitoring-sdk 0.0.0-stage → 0.2.0

package/dist/esm/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/esm/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/esm/core/errors.js

@@ -0,0 +1,86 @@
+/**
+ * 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, options) {
+        super(message, options);
+        this.name = 'MonitoringError';
+    }
+}
+/** The API responded with an error status (4xx or 5xx). */
+export 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;
+    }
+}
+/** The request did not get a response because of a network or connection failure. */
+export class MonitoringConnectionError extends MonitoringError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MonitoringConnectionError';
+    }
+}
+/** The request did not complete within `timeoutMs`. */
+export class MonitoringTimeoutError extends MonitoringConnectionError {
+    constructor(timeoutMs) {
+        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, 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

package/dist/esm/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACrD,wBAAwB;IACf,MAAM,CAAQ;IACvB;;;OAGG;IACM,IAAI,CAAQ;IACrB,kGAAkG;IACzF,OAAO,CAAe;IAC/B,sDAAsD;IAC7C,SAAS,CAAoB;IACtC,yBAAyB;IAChB,IAAI,CAAS;IAEtB,YAAY,IAAoH;QAC9H,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,UAAU,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAA;QAC5D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAA;QACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;IAED,gHAAgH;IAChH,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAA;IACnD,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IAC5D,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAA;IACzC,CAAC;CACF;AAED,uDAAuD;AACvD,MAAM,OAAO,sBAAuB,SAAQ,yBAAyB;IACnE,YAAY,SAAiB;QAC3B,KAAK,CAAC,2BAA2B,SAAS,KAAK,CAAC,CAAA;QAChD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAA;IACtC,CAAC;CACF;AAED,uGAAuG;AACvG,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACxD,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAa,EAAE,SAA6B;IACvF,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAA;IACjD,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,KAAiC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC7G,MAAM,OAAO,GACX,CAAC,OAAO,EAAE,EAAE,OAAO,KAAK,QAAQ,IAAI,EAAE,CAAC,OAAO,CAAC;QAC/C,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,CAAC;QACxC,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC;QAC5C,QAAQ,MAAM,EAAE,CAAA;IAClB,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,IAAI,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IACrI,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAkB,CAAA;IACtH,OAAO,IAAI,kBAAkB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AACpF,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,KAAK,GAA2B,EAAE,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,cAAc,EAAE,CAAA;IAC/J,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;AACzE,CAAC"}

package/dist/esm/core/http.d.ts

@@ -0,0 +1,58 @@
+/** 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;
+}
+/** @internal Transport: base URL, authentication, timeouts, retries and error mapping. */
+export declare class HttpClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options: ClientOptions, defaultBaseUrl: string);
+    /** Sends a request and returns the parsed JSON response. */
+    request<T>(call: Call): Promise<T>;
+}
+/** @internal Encodes a path segment. */
+export declare const seg: (value: string | number) => string;
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/esm/core/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/core/http.ts"],"names":[],"mappings":"AAGA,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0GAA0G;IAC1G,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;AAEzE,sCAAsC;AACtC,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wFAAwF;IACxF,UAAU,EAAE,OAAO,CAAA;IACnB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,OAAO,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CACrC;AAKD,0FAA0F;AAC1F,qBAAa,UAAU;;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAOxB,YAAY,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,EAUzD;IAED,4DAA4D;IACtD,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAmCvC;CA6BF;AAuCD,wCAAwC;AACxC,eAAO,MAAM,GAAG,UAAW,MAAM,GAAG,MAAM,WAAsC,CAAA"}

package/dist/esm/core/http.js

@@ -0,0 +1,138 @@
+import { SDK_VERSION } from '../version.js';
+import { apiErrorFrom, MonitoringConnectionError, MonitoringError, MonitoringTimeoutError } from './errors.js';
+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 {
+    baseUrl;
+    #apiKey;
+    #timeoutMs;
+    #maxRetries;
+    #fetch;
+    #headers;
+    constructor(options, defaultBaseUrl) {
+        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(call) {
+        const url = this.#url(call.path, call.query);
+        const headers = {
+            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;
+            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;
+            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, query) {
+        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, init, timeoutMs, signal) {
+        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 = 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.message}`, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+function parseJson(text) {
+    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) {
+    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) {
+    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, signal) {
+    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) => encodeURIComponent(String(value));
+//# sourceMappingURL=http.js.map

package/dist/esm/core/http.js.map

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

package/dist/esm/core/pagination.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A page of results. `next` is the cursor of the next page; `null` when there are no more pages.
+ *
+ * @typeParam T - Item type.
+ */
+export interface Page<T> {
+    items: T[];
+    next: number | null;
+}
+/** @internal Yields every item, fetching the next page only when the current one is exhausted. */
+export declare function paginate<T>(fetchPage: (cursor: number | undefined) => Promise<Page<T>>): AsyncGenerator<T, void, undefined>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/esm/core/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/core/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,EAAE,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED,kGAAkG;AAClG,wBAAuB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAQlI"}

package/dist/esm/core/pagination.js

@@ -0,0 +1,12 @@
+/** @internal Yields every item, fetching the next page only when the current one is exhausted. */
+export async function* paginate(fetchPage) {
+    let cursor;
+    for (;;) {
+        const page = await fetchPage(cursor);
+        yield* page.items;
+        if (page.next === null || page.next === undefined)
+            return;
+        cursor = page.next;
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/esm/core/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/core/pagination.ts"],"names":[],"mappings":"AAUA,kGAAkG;AAClG,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAAI,SAA2D;IAC5F,IAAI,MAA0B,CAAA;IAC9B,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAA;QACpC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAA;QACjB,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAM;QACzD,MAAM,GAAG,IAAI,CAAC,IAAI,CAAA;IACpB,CAAC;AACH,CAAC"}

package/dist/esm/core/scope.d.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>;
+}
+//# sourceMappingURL=scope.d.ts.map

package/dist/esm/core/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/core/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,sFAAsF;AACtF,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,UAAU,CAAA;IAChB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAClC"}

package/dist/esm/core/scope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scope.js.map

package/dist/esm/core/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../../src/core/scope.ts"],"names":[],"mappings":""}