@fedpulse/sdk 1.0.0

package/dist/cjs/http.cjs

@@ -0,0 +1,449 @@
+"use strict";
+/**
+ * Core HTTP client for the FedPulse SDK.
+ *
+ * Features:
+ *  - Native fetch (Node 18+) — zero runtime dependencies
+ *  - Configurable timeout via AbortController
+ *  - Automatic retry with exponential back-off + full jitter for transient errors
+ *  - In-memory LRU cache for GET requests with per-entry TTL
+ *  - Rate-limit header tracking (X-RateLimit-*)
+ *  - Standard API envelope parsing + typed error creation
+ *  - Array query-parameter serialisation (repeated keys)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+exports.buildQueryParams = buildQueryParams;
+const errors_js_1 = require("./errors.cjs");
+// ── Constants ──────────────────────────────────────────────────────────────────
+const DEFAULT_BASE_URL = 'https://api.fedpulse.dev';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_CACHE_SIZE = 256;
+const DEFAULT_CACHE_TTL_MS = 60_000;
+/** HTTP status codes that are safe to retry (transient server-side errors). */
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+/**
+ * Least-recently-used cache with per-entry TTL.
+ * Implemented with a doubly-linked list + Map for O(1) get and set.
+ *
+ * @template T  Cached value type.
+ */
+class LruCache {
+    capacity;
+    defaultTtlMs;
+    map = new Map();
+    // Sentinel nodes avoid null-checks on boundary operations.
+    head;
+    tail;
+    constructor(capacity, defaultTtlMs) {
+        this.capacity = capacity;
+        this.defaultTtlMs = defaultTtlMs;
+        this.head = { value: null, expiresAt: 0, key: '__head', prev: null, next: null };
+        this.tail = { value: null, expiresAt: 0, key: '__tail', prev: null, next: null };
+        this.head.next = this.tail;
+        this.tail.prev = this.head;
+    }
+    /**
+     * Retrieve a cached value. Returns undefined on miss or expiry.
+     */
+    get(key) {
+        const entry = this.map.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.remove(entry);
+            this.map.delete(key);
+            return undefined;
+        }
+        // Move to front (most-recently-used).
+        this.remove(entry);
+        this.insertFront(entry);
+        return entry.value;
+    }
+    /**
+     * Store a value. Returns the evicted key if capacity was exceeded.
+     */
+    set(key, value, ttlMs) {
+        // Evict stale entry for the same key first.
+        const existing = this.map.get(key);
+        if (existing !== undefined) {
+            this.remove(existing);
+        }
+        const entry = {
+            key,
+            value,
+            expiresAt: Date.now() + (ttlMs ?? this.defaultTtlMs),
+            prev: null,
+            next: null,
+        };
+        this.map.set(key, entry);
+        this.insertFront(entry);
+        // Evict LRU entry if over capacity.
+        if (this.map.size > this.capacity) {
+            // LRU entry is just before the tail sentinel.
+            const lru = this.tail.prev;
+            if (lru !== this.head) {
+                this.remove(lru);
+                this.map.delete(lru.key);
+            }
+        }
+    }
+    /** Delete a specific key from the cache. */
+    delete(key) {
+        const entry = this.map.get(key);
+        if (entry !== undefined) {
+            this.remove(entry);
+            this.map.delete(key);
+        }
+    }
+    /** Remove all entries. */
+    clear() {
+        this.map.clear();
+        this.head.next = this.tail;
+        this.tail.prev = this.head;
+    }
+    /** Number of entries currently in the cache. */
+    get size() {
+        return this.map.size;
+    }
+    insertFront(entry) {
+        entry.prev = this.head;
+        entry.next = this.head.next;
+        this.head.next.prev = entry;
+        this.head.next = entry;
+    }
+    remove(entry) {
+        entry.prev.next = entry.next;
+        entry.next.prev = entry.prev;
+    }
+}
+// ── Query string serialisation ─────────────────────────────────────────────────
+/**
+ * Serialise a plain-object params map to a URLSearchParams instance.
+ *
+ * Arrays are serialised as repeated keys: `{ naics: ['11', '21'] }` →
+ * `?naics=11&naics=21`.
+ *
+ * Undefined and null values are omitted.
+ */
+function buildQueryParams(params) {
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined && item !== null) {
+                    qs.append(key, String(item));
+                }
+            }
+        }
+        else {
+            qs.set(key, String(value));
+        }
+    }
+    return qs;
+}
+// ── HttpClient ─────────────────────────────────────────────────────────────────
+/**
+ * Low-level HTTP client used by all domain resources.
+ *
+ * You should not need to instantiate this directly — use `FedPulse` instead.
+ */
+class HttpClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    cache;
+    defaultCacheTtlMs;
+    fetchFn;
+    /** Most recent rate-limit info observed across all requests. */
+    lastRateLimit = null;
+    constructor(options) {
+        if (!options.apiKey || typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {
+            throw new errors_js_1.AuthenticationError({
+                message: 'API key is required and must be a non-empty string. ' +
+                    'Generate one at https://app.fedpulse.dev/dashboard.',
+            });
+        }
+        this.apiKey = options.apiKey.trim();
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.defaultCacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+        this.fetchFn = options.fetchFn ?? globalThis.fetch;
+        const cacheSize = options.cacheSize ?? DEFAULT_CACHE_SIZE;
+        this.cache = cacheSize > 0 ? new LruCache(cacheSize, this.defaultCacheTtlMs) : null;
+    }
+    // ── Public request methods ───────────────────────────────────────────────────
+    /**
+     * Perform a GET request. Results are cached unless `cacheTtlMs` is 0.
+     *
+     * @param path     API path (e.g. `/v1/opportunities`).
+     * @param params   Query parameters — arrays serialised as repeated keys.
+     * @param options  Per-request overrides.
+     */
+    async get(path, params = {}, options) {
+        const qs = buildQueryParams(params);
+        const qsStr = qs.toString();
+        const url = `${this.baseUrl}${path}${qsStr ? `?${qsStr}` : ''}`;
+        const ttl = options?.cacheTtlMs ?? this.defaultCacheTtlMs;
+        const shouldCache = this.cache !== null && ttl > 0;
+        if (shouldCache) {
+            const cached = this.cache.get(url);
+            if (cached !== undefined) {
+                return { ...cached, fromCache: true };
+            }
+        }
+        const result = await this.executeWithRetry('GET', url, undefined, options);
+        if (shouldCache) {
+            this.cache.set(url, result, ttl);
+        }
+        return result;
+    }
+    /**
+     * Perform a POST request (never cached).
+     *
+     * @param path   API path.
+     * @param body   JSON-serialisable request body.
+     * @param options  Per-request overrides.
+     */
+    async post(path, body, options) {
+        const url = `${this.baseUrl}${path}`;
+        return this.executeWithRetry('POST', url, body, options);
+    }
+    /**
+     * Perform a PATCH request (never cached).
+     */
+    async patch(path, body, options) {
+        const url = `${this.baseUrl}${path}`;
+        return this.executeWithRetry('PATCH', url, body, options);
+    }
+    /**
+     * Perform a DELETE request (never cached).
+     */
+    async del(path, options) {
+        const url = `${this.baseUrl}${path}`;
+        return this.executeWithRetry('DELETE', url, undefined, options);
+    }
+    /**
+     * Clear all cached responses.
+     */
+    clearCache() {
+        this.cache?.clear();
+    }
+    // ── Internal methods ─────────────────────────────────────────────────────────
+    /**
+     * Execute a request, retrying on transient failures with exponential back-off
+     * and full jitter.
+     */
+    async executeWithRetry(method, url, body, options) {
+        let lastError = null;
+        const maxAttempts = this.maxRetries + 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.executeOnce(method, url, body, options);
+            }
+            catch (err) {
+                if (!(err instanceof errors_js_1.FedPulseError)) {
+                    // Should not happen, but guard defensively.
+                    throw err;
+                }
+                lastError = err;
+                // Do not retry 4xx errors (except 429).
+                const isRetryable = err instanceof errors_js_1.NetworkError ||
+                    err instanceof errors_js_1.TimeoutError ||
+                    RETRYABLE_STATUSES.has(err.status);
+                if (!isRetryable) {
+                    // Non-retryable (4xx): throw the specific error type immediately.
+                    throw err;
+                }
+                if (attempt >= maxAttempts) {
+                    // Retryable but no more attempts available.
+                    break;
+                }
+                // Calculate delay: exponential back-off (base 500ms) with full jitter.
+                let delayMs;
+                if (err instanceof errors_js_1.RateLimitError && err.retryAfter !== undefined) {
+                    // Honour API-provided Retry-After header.
+                    const waitUntil = err.retryAfter * 1000;
+                    delayMs = Math.max(0, waitUntil - Date.now());
+                }
+                else {
+                    const baseMs = 500 * Math.pow(2, attempt - 1); // 500, 1000, 2000 …
+                    const capMs = 30_000;
+                    delayMs = Math.random() * Math.min(baseMs, capMs);
+                }
+                await sleep(delayMs);
+            }
+        }
+        // Only use RetryExhaustedError when we actually retried (maxAttempts > 1).
+        // With maxRetries=0 the caller gets the specific error type directly.
+        if (maxAttempts > 1) {
+            throw new errors_js_1.RetryExhaustedError({ lastError: lastError, attempts: maxAttempts });
+        }
+        throw lastError;
+    }
+    /**
+     * Execute a single HTTP request (no retry logic).
+     * Handles timeout, response parsing, header extraction, and error creation.
+     */
+    async executeOnce(method, url, body, options) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+            'User-Agent': '@fedpulse/sdk/1.0.0 (node)',
+            ...(options?.headers ?? {}),
+        };
+        if (body !== undefined && body !== null) {
+            headers['Content-Type'] = 'application/json';
+        }
+        let response;
+        try {
+            response = await this.fetchFn(url, {
+                method,
+                headers,
+                body: body !== undefined && body !== null ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err != null && typeof err === 'object' && 'name' in err && err.name === 'AbortError') {
+                throw new errors_js_1.TimeoutError({
+                    message: `Request timed out after ${this.timeoutMs}ms: ${method} ${url}`,
+                });
+            }
+            const cause = err instanceof Error ? err : new Error(String(err));
+            throw new errors_js_1.NetworkError({
+                message: `Network error: ${cause.message}`,
+                cause,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        // Extract headers for rate limit tracking and error context.
+        const headerMap = {
+            'x-ratelimit-limit': response.headers.get('x-ratelimit-limit'),
+            'x-ratelimit-remaining': response.headers.get('x-ratelimit-remaining'),
+            'x-ratelimit-reset': response.headers.get('x-ratelimit-reset'),
+            'retry-after': response.headers.get('retry-after'),
+        };
+        const rateLimit = parseRateLimitHeaders(headerMap);
+        if (rateLimit !== null) {
+            this.lastRateLimit = rateLimit;
+        }
+        // Parse body — always attempt JSON; fall back to text for error messages.
+        let parsedBody;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (contentType.includes('application/json')) {
+            try {
+                parsedBody = await response.json();
+            }
+            catch {
+                parsedBody = null;
+            }
+        }
+        else {
+            // Non-JSON body (e.g. download streams or plain-text errors).
+            parsedBody = null;
+        }
+        if (!response.ok) {
+            throw (0, errors_js_1.createApiError)(response.status, parsedBody, headerMap);
+        }
+        // Unwrap the standard success envelope.
+        const envelope = parsedBody;
+        if (envelope === null || typeof envelope !== 'object' || !('data' in envelope)) {
+            // Unexpected response shape — treat as server error.
+            throw (0, errors_js_1.createApiError)(500, { error: { message: 'Unexpected response format from API' } }, headerMap);
+        }
+        const meta = (envelope.meta ?? { requestId: '' });
+        return {
+            data: envelope.data,
+            pagination: envelope.pagination ?? null,
+            meta,
+            rateLimit,
+            fromCache: false,
+        };
+    }
+    /**
+     * Perform a raw fetch that returns the full Response (for streaming downloads).
+     * No retry, no envelope parsing.
+     *
+     * @param path   API path.
+     * @param params Query parameters.
+     */
+    async rawGet(path, params = {}) {
+        const qs = buildQueryParams(params);
+        const qsStr = qs.toString();
+        const url = `${this.baseUrl}${path}${qsStr ? `?${qsStr}` : ''}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchFn(url, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'User-Agent': '@fedpulse/sdk/1.0.0 (node)',
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                let body = null;
+                try {
+                    body = await response.json();
+                }
+                catch { /* ignore */ }
+                throw (0, errors_js_1.createApiError)(response.status, body, {
+                    'retry-after': response.headers.get('retry-after'),
+                    'x-ratelimit-reset': response.headers.get('x-ratelimit-reset'),
+                    'x-ratelimit-limit': response.headers.get('x-ratelimit-limit'),
+                    'x-ratelimit-remaining': response.headers.get('x-ratelimit-remaining'),
+                });
+            }
+            return response;
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.FedPulseError)
+                throw err;
+            if (err != null && typeof err === 'object' && 'name' in err && err.name === 'AbortError') {
+                throw new errors_js_1.TimeoutError({ message: `Request timed out after ${this.timeoutMs}ms` });
+            }
+            const cause = err instanceof Error ? err : new Error(String(err));
+            throw new errors_js_1.NetworkError({ message: `Network error: ${cause.message}`, cause });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+exports.HttpClient = HttpClient;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Parse X-RateLimit-* response headers into a typed object.
+ * Returns null if none of the headers are present.
+ */
+function parseRateLimitHeaders(headers) {
+    const limit = headers['x-ratelimit-limit'];
+    const remaining = headers['x-ratelimit-remaining'];
+    const reset = headers['x-ratelimit-reset'];
+    if (limit === null && remaining === null && reset === null)
+        return null;
+    return {
+        limit: limit !== null ? Number(limit) : 0,
+        remaining: remaining !== null ? Number(remaining) : 0,
+        reset: reset !== null ? Number(reset) : 0,
+    };
+}
+/**
+ * Promise-based sleep helper.
+ * @param ms  Milliseconds to wait.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/cjs/index.cjs

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * @fedpulse/sdk — Official JavaScript/TypeScript SDK for the FedPulse API.
+ *
+ * Quick start:
+ * ```ts
+ * import { FedPulse } from '@fedpulse/sdk';
+ *
+ * const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+ *
+ * const { data } = await client.opportunities.list({ q: 'cloud', naics: '541512' });
+ * console.log(data[0].title);
+ * ```
+ *
+ * Webhook verification:
+ * ```ts
+ * const payload = FedPulse.verifyWebhook({
+ *   rawBody: req.body,
+ *   signatureHeader: req.headers['x-fedpulse-signature'],
+ *   timestampHeader: req.headers['x-fedpulse-timestamp'],
+ *   secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractWebhookHeaders = exports.verifyWebhook = exports.WebhooksResource = exports.AnalyticsResource = exports.AssistanceResource = exports.IntelligenceResource = exports.EntitiesResource = exports.ExclusionsResource = exports.OpportunitiesResource = exports.buildQueryParams = exports.HttpClient = exports.RetryExhaustedError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.PermissionError = exports.AuthenticationError = exports.FedPulseError = exports.WebhookVerificationError = exports.FedPulse = void 0;
+// ── Main client ────────────────────────────────────────────────────────────────
+var client_js_1 = require("./client.cjs");
+Object.defineProperty(exports, "FedPulse", { enumerable: true, get: function () { return client_js_1.FedPulse; } });
+Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, get: function () { return client_js_1.WebhookVerificationError; } });
+// ── Error classes ──────────────────────────────────────────────────────────────
+var errors_js_1 = require("./errors.cjs");
+Object.defineProperty(exports, "FedPulseError", { enumerable: true, get: function () { return errors_js_1.FedPulseError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "PermissionError", { enumerable: true, get: function () { return errors_js_1.PermissionError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_js_1.NetworkError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+Object.defineProperty(exports, "RetryExhaustedError", { enumerable: true, get: function () { return errors_js_1.RetryExhaustedError; } });
+// ── HTTP client (advanced usage) ───────────────────────────────────────────────
+var http_js_1 = require("./http.cjs");
+Object.defineProperty(exports, "HttpClient", { enumerable: true, get: function () { return http_js_1.HttpClient; } });
+Object.defineProperty(exports, "buildQueryParams", { enumerable: true, get: function () { return http_js_1.buildQueryParams; } });
+// ── Domain resources ───────────────────────────────────────────────────────────
+var opportunities_js_1 = require("./resources/opportunities.cjs");
+Object.defineProperty(exports, "OpportunitiesResource", { enumerable: true, get: function () { return opportunities_js_1.OpportunitiesResource; } });
+var exclusions_js_1 = require("./resources/exclusions.cjs");
+Object.defineProperty(exports, "ExclusionsResource", { enumerable: true, get: function () { return exclusions_js_1.ExclusionsResource; } });
+var entities_js_1 = require("./resources/entities.cjs");
+Object.defineProperty(exports, "EntitiesResource", { enumerable: true, get: function () { return entities_js_1.EntitiesResource; } });
+var intelligence_js_1 = require("./resources/intelligence.cjs");
+Object.defineProperty(exports, "IntelligenceResource", { enumerable: true, get: function () { return intelligence_js_1.IntelligenceResource; } });
+var assistance_js_1 = require("./resources/assistance.cjs");
+Object.defineProperty(exports, "AssistanceResource", { enumerable: true, get: function () { return assistance_js_1.AssistanceResource; } });
+var analytics_js_1 = require("./resources/analytics.cjs");
+Object.defineProperty(exports, "AnalyticsResource", { enumerable: true, get: function () { return analytics_js_1.AnalyticsResource; } });
+var webhooks_js_1 = require("./resources/webhooks.cjs");
+Object.defineProperty(exports, "WebhooksResource", { enumerable: true, get: function () { return webhooks_js_1.WebhooksResource; } });
+// ── Webhook utilities ──────────────────────────────────────────────────────────
+var webhooks_verify_js_1 = require("./webhooks-verify.cjs");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhooks_verify_js_1.verifyWebhook; } });
+Object.defineProperty(exports, "extractWebhookHeaders", { enumerable: true, get: function () { return webhooks_verify_js_1.extractWebhookHeaders; } });

package/dist/cjs/resources/analytics.cjs

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Analytics resource client.
+ *
+ * Wraps all /v1/analytics endpoints (per-user API usage analytics):
+ *   - summary    GET /v1/analytics/summary
+ *   - chart      GET /v1/analytics/chart
+ *   - endpoints  GET /v1/analytics/endpoints
+ *   - logs       GET /v1/analytics/logs
+ *   - logPages   async generator over the logs endpoint
+ *
+ * All results are scoped to the authenticated user — no cross-user visibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsResource = void 0;
+class AnalyticsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get KPI summary totals for the authenticated user.
+     *
+     * Returns: requests today, this month, in range, 4xx/5xx counts and rates.
+     * Analytics data is never cached — always returns live counts.
+     *
+     * @param params  Optional key-scoping and time range.
+     *
+     * @example
+     * ```ts
+     * const summary = await client.analytics.summary({ range: '7d' });
+     * console.log('Requests last 7d:', summary.data.requestsInRange);
+     * ```
+     */
+    async summary(params = {}) {
+        validateAnalyticsParams(params);
+        return this.http.get('/v1/analytics/summary', params, { cacheTtlMs: 0 });
+    }
+    /**
+     * Get per-day request counts broken down by success / 4xx / 5xx.
+     *
+     * @param params  Optional key-scoping and time range.
+     *
+     * @example
+     * ```ts
+     * const chart = await client.analytics.chart({ range: '30d' });
+     * for (const day of chart.data.days) {
+     *   console.log(day.date, day.total);
+     * }
+     * ```
+     */
+    async chart(params = {}) {
+        validateAnalyticsParams(params);
+        return this.http.get('/v1/analytics/chart', params, { cacheTtlMs: 0 });
+    }
+    /**
+     * Get top-10 endpoints by request volume and by P95 latency.
+     *
+     * @param params  Optional key-scoping and time range.
+     *
+     * @example
+     * ```ts
+     * const endpoints = await client.analytics.endpoints({ range: '7d' });
+     * console.log('Slowest endpoint:', endpoints.data.byLatency[0]?.endpoint);
+     * ```
+     */
+    async endpoints(params = {}) {
+        validateAnalyticsParams(params);
+        return this.http.get('/v1/analytics/endpoints', params, { cacheTtlMs: 0 });
+    }
+    /**
+     * Get paginated API request logs for the authenticated user.
+     *
+     * Supports cursor-based pagination via the `cursor` parameter.
+     * Maximum `limit` is 1000.
+     *
+     * @param params  Filter and pagination parameters.
+     *
+     * @example
+     * ```ts
+     * const logs = await client.analytics.logs({ limit: 50, status: '4xx' });
+     * for (const entry of logs.data.items) {
+     *   console.log(entry.method, entry.endpoint, entry.statusCode);
+     * }
+     * ```
+     */
+    async logs(params = {}) {
+        if (params.limit !== undefined) {
+            if (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 1000) {
+                throw new Error('limit must be an integer between 1 and 1000');
+            }
+        }
+        validateAnalyticsParams(params);
+        return this.http.get('/v1/analytics/logs', params, { cacheTtlMs: 0 });
+    }
+    /**
+     * Async generator that automatically paginates through all log entries.
+     *
+     * Uses cursor-based pagination. Yields one page at a time.
+     *
+     * @param params  Same parameters as `logs()`. Do not pass `cursor`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.analytics.logPages({ range: '7d' })) {
+     *   for (const entry of page.data.items) {
+     *     console.log(entry.requestId, entry.statusCode);
+     *   }
+     * }
+     * ```
+     */
+    async *logPages(params) {
+        let cursor = undefined;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await this.logs({
+                ...params,
+                ...(cursor !== undefined ? { cursor } : {}),
+            });
+            yield result;
+            const logs = result.data;
+            cursor = logs.nextCursor ?? undefined;
+            hasMore = logs.hasNextPage && cursor !== undefined;
+        }
+    }
+}
+exports.AnalyticsResource = AnalyticsResource;
+// ── Helpers ────────────────────────────────────────────────────────────────────
+const VALID_RANGES = new Set(['24h', '7d', '30d', '90d']);
+function validateAnalyticsParams(params) {
+    if (params.range !== undefined && !VALID_RANGES.has(params.range)) {
+        throw new Error(`range must be one of: 24h, 7d, 30d, 90d. Got: "${params.range}"`);
+    }
+}