@bisibility/sdk 0.1.0 → 0.1.1

package/dist/client.js

@@ -1,6 +1,12 @@
 import { BisibilityApiError, BisibilityConfigurationError, BisibilityNetworkError, BisibilityResponseError, } from "./errors.js";
+import { iterateCursorPagination } from "./pagination.js";
+import { SDK_VERSION } from "./version.js";
 const DEFAULT_BASE_URL = "https://bisibility.com/api/v1";
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_TIMEOUT = 30_000;
+const CLIENT_ID = `bisibility-sdk-ts/${SDK_VERSION}`;
 const RELATIVE_BASE_ORIGIN = "https://bisibility.local";
+const IDEMPOTENT_METHODS = new Set(["DELETE", "GET", "HEAD", "PUT"]);
 function isAbsoluteUrl(value) {
     return /^[a-z][a-z\d+\-.]*:/i.test(value);
 }
@@ -69,7 +75,7 @@ function problemFromJson(value) {
     return problem;
 }
 function composedSignal(signal, timeout) {
-    if (timeout === undefined) {
+    if (timeout === null || timeout === undefined) {
         return signal;
     }
     if (!Number.isFinite(timeout) || timeout <= 0) {
@@ -92,6 +98,53 @@ function composedSignal(signal, timeout) {
     }
     return controller.signal;
 }
+function validatedMaxRetries(value) {
+    const maxRetries = value ?? DEFAULT_MAX_RETRIES;
+    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+        throw new BisibilityConfigurationError("maxRetries must be a non-negative integer.");
+    }
+    return maxRetries;
+}
+function validatedTimeout(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new BisibilityConfigurationError("timeout must be a positive finite number or null.");
+    }
+    return value;
+}
+function retryBackoffMs(attempt) {
+    return Math.min(500 * 2 ** attempt, 8_000);
+}
+function sleep(milliseconds, signal) {
+    if (signal?.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+async function sleepForRetry(milliseconds, signal, method, url) {
+    try {
+        await sleep(milliseconds, signal);
+    }
+    catch (cause) {
+        throw new BisibilityNetworkError("Network error while calling the Bisibility API.", {
+            cause,
+            method,
+            url,
+        });
+    }
+}
 function mergeHeaders(first, second) {
     const headers = new Headers(first);
     if (second) {
@@ -105,14 +158,18 @@ export class BisibilityClient {
     #apiKey;
     #defaultHeaders;
     #fetchImpl;
+    #maxRetries;
     #projectId;
+    #timeout;
     baseUrl;
     constructor(config = {}) {
         this.#apiKey = config.apiKey;
         this.baseUrl = normalizeBaseUrl(config.baseUrl);
         this.#defaultHeaders = config.headers;
         this.#fetchImpl = config.fetch;
+        this.#maxRetries = validatedMaxRetries(config.maxRetries);
         this.#projectId = config.projectId;
+        this.#timeout = validatedTimeout(config.timeout);
     }
     getHealth(options) {
         return this.request("GET", "/health", { ...options, auth: false });
@@ -154,6 +211,16 @@ export class BisibilityClient {
             },
         });
     }
+    searchLocations(input, options) {
+        return this.request("GET", "/locations/search", {
+            ...options,
+            query: {
+                country: input.country,
+                limit: input.limit,
+                q: input.q,
+            },
+        });
+    }
     getMe(options) {
         return this.request("GET", "/me", options);
     }
@@ -166,11 +233,7 @@ export class BisibilityClient {
     createMyToken(input, options) {
         return this.request("POST", "/me/tokens", {
             ...options,
-            body: {
-                expires_in_days: input.expiresInDays,
-                name: input.name,
-                scope: input.scope,
-            },
+            body: input,
         });
     }
     revokeMyToken(tokenId, options) {
@@ -182,12 +245,7 @@ export class BisibilityClient {
     createProject(input, options) {
         return this.request("POST", "/projects", {
             ...options,
-            body: {
-                defaults: input.defaults,
-                domain: input.domain,
-                name: input.name,
-                tracking_scope: input.trackingScope,
-            },
+            body: input,
         });
     }
     getProject(projectId, options) {
@@ -215,6 +273,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateApiKeys(options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listApiKeys(pageOptions, requestOptions), options);
+    }
     createApiKey(input, options) {
         return this.request("POST", "/api-keys", { ...options, body: input });
     }
@@ -231,6 +292,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateProjectApiKeys(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listProjectApiKeys(projectId, pageOptions, requestOptions), options);
+    }
     createProjectApiKey(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/api-keys`, { ...options, body: input });
     }
@@ -244,6 +308,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateWebhooks(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listWebhooks(projectId, pageOptions, requestOptions), options);
+    }
     createWebhook(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/webhooks`, {
             ...options,
@@ -275,12 +342,12 @@ export class BisibilityClient {
             },
         });
     }
+    iterateKeywords(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listKeywords(projectId, pageOptions, requestOptions), options);
+    }
     addKeywords(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/keywords`, { ...options, body: input });
     }
-    createKeywords(projectId, input, options) {
-        return this.addKeywords(projectId, input, options);
-    }
     getKeyword(keywordId, options) {
         return this.request("GET", `/keywords/${encodedPathSegment(keywordId)}`, options);
     }
@@ -294,11 +361,72 @@ export class BisibilityClient {
         return this.updateKeyword(keywordId, { target_url: targetUrl }, options);
     }
     deleteKeyword(keywordId, options) {
-        return this.request("DELETE", `/keywords/${encodedPathSegment(keywordId)}`, options);
+        return this.requestOrUndefined("DELETE", `/keywords/${encodedPathSegment(keywordId)}`, options);
     }
     bulkUpdateKeywords(input, options) {
         return this.request("POST", "/keywords/bulk", { ...options, body: input });
     }
+    listRankedKeywordSuggestions(projectId, options, requestOptions) {
+        const filters = options ?? {};
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/ranked-keyword-suggestions`, {
+            ...requestOptions,
+            query: {
+                connection_id: filters.connectionId,
+                fresh: filters.fresh,
+                limit: filters.limit,
+                offset: filters.offset,
+            },
+        });
+    }
+    /**
+     * Research keywords from one seed. This operation requires API write scope because a cache
+     * miss can spend the project's provider budget. Use `estimateOnly` for a free dry run.
+     */
+    researchKeywords(projectId, options, requestOptions) {
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/keyword-research`, {
+            ...requestOptions,
+            query: {
+                connection_id: options.connectionId,
+                estimate_only: options.estimateOnly,
+                fresh: options.fresh,
+                include_clickstream: options.includeClickstream,
+                max_cost_cents: options.maxCostCents,
+                mode: options.mode,
+                result_limit: options.resultLimit,
+                seed: options.seed,
+            },
+        });
+    }
+    /**
+     * Hydrate keyword metrics. This operation requires API write scope because cache misses can
+     * spend the project's provider budget. Use `estimate_only` for a free dry run.
+     */
+    getKeywordMetrics(projectId, input, options) {
+        return this.request("POST", `/projects/${encodedPathSegment(projectId)}/keyword-metrics`, { ...options, body: input });
+    }
+    exportRankHistory(projectId, options = {}, requestOptions) {
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/exports/rank-history`, {
+            ...requestOptions,
+            parseAs: options.format === "csv" ? "text" : "json",
+            query: {
+                cursor: "cursor" in options ? options.cursor : undefined,
+                format: options.format,
+                granularity: options.granularity,
+                keyword_id: options.keywordIds,
+                limit: "limit" in options ? options.limit : undefined,
+                range: options.range,
+            },
+        });
+    }
+    iterateRankHistoryExport(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.exportRankHistory(projectId, { ...options, ...pageOptions, format: "json" }, requestOptions), options);
+    }
+    listSitemapMonitors(projectId, options) {
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/sitemap-monitors`, options);
+    }
+    updateSitemapMonitor(projectId, monitorId, input, options) {
+        return this.request("PATCH", `/projects/${encodedPathSegment(projectId)}/sitemap-monitors/${encodedPathSegment(monitorId)}`, { ...options, body: input });
+    }
     listRankChecks(keywordId, options, requestOptions) {
         const filters = options ?? {};
         return this.request("GET", `/keywords/${encodedPathSegment(keywordId)}/rank-checks`, {
@@ -312,6 +440,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateRankChecks(keywordId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listRankChecks(keywordId, pageOptions, requestOptions), options);
+    }
     runRankCheck(keywordId, input, options) {
         const { async: runAsync, ...requestOptions } = options ?? {};
         const body = input && Object.keys(input).length ? input : undefined;
@@ -341,6 +472,36 @@ export class BisibilityClient {
             },
         });
     }
+    iterateSignals(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listSignals(projectId, pageOptions, requestOptions), options);
+    }
+    listTrafficSnapshots(projectId, options, requestOptions) {
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/analytics/traffic-snapshots`, {
+            ...requestOptions,
+            query: {
+                end_date: options.endDate,
+                limit: options.limit,
+                offset: options.offset,
+                path: options.paths,
+                start_date: options.startDate,
+            },
+        });
+    }
+    listSearchPerformanceQueryStats(projectId, options, requestOptions) {
+        return this.request("GET", `/projects/${encodedPathSegment(projectId)}/analytics/query-stats`, {
+            ...requestOptions,
+            query: {
+                connection_id: options.connectionId,
+                end_date: options.endDate,
+                limit: options.limit,
+                query: options.query,
+                start_date: options.startDate,
+            },
+        });
+    }
+    syncProjectTraffic(projectId, options) {
+        return this.request("POST", `/projects/${encodedPathSegment(projectId)}/analytics/sync`, options);
+    }
     listAlertRules(projectId, options, requestOptions) {
         const pagination = options ?? {};
         return this.request("GET", `/projects/${encodedPathSegment(projectId)}/alert-rules`, {
@@ -351,6 +512,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateAlertRules(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listAlertRules(projectId, pageOptions, requestOptions), options);
+    }
     createAlertRule(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/alert-rules`, { ...options, body: input });
     }
@@ -373,6 +537,15 @@ export class BisibilityClient {
             },
         });
     }
+    iterateTriggeredAlerts(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listTriggeredAlerts(projectId, pageOptions, requestOptions), options);
+    }
+    muteTriggeredAlert(projectId, alertId, options) {
+        return this.request("POST", `/projects/${encodedPathSegment(projectId)}/triggered-alerts/${encodedPathSegment(alertId)}/mute`, options);
+    }
+    markProjectAlertsRead(projectId, options) {
+        return this.request("POST", `/projects/${encodedPathSegment(projectId)}/triggered-alerts/mark-read`, options);
+    }
     listTeamMembers(projectId, options, requestOptions) {
         const pagination = options ?? {};
         return this.request("GET", `/projects/${encodedPathSegment(projectId)}/team/members`, {
@@ -383,6 +556,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateTeamMembers(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listTeamMembers(projectId, pageOptions, requestOptions), options);
+    }
     listTeamInvites(projectId, options, requestOptions) {
         const pagination = options ?? {};
         return this.request("GET", `/projects/${encodedPathSegment(projectId)}/team/invites`, {
@@ -393,6 +569,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateTeamInvites(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listTeamInvites(projectId, pageOptions, requestOptions), options);
+    }
     createTeamInvite(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/team/invites`, { ...options, body: input });
     }
@@ -402,6 +581,15 @@ export class BisibilityClient {
     revokeTeamInviteById(inviteId, options) {
         return this.request("DELETE", `/team/invites/${encodedPathSegment(inviteId)}`, options);
     }
+    resendTeamInvite(projectId, inviteId, options) {
+        return this.request("POST", `/projects/${encodedPathSegment(projectId)}/team/invites/${encodedPathSegment(inviteId)}/resend`, options);
+    }
+    updateTeamMemberRole(projectId, memberId, input, options) {
+        return this.request("PATCH", `/projects/${encodedPathSegment(projectId)}/team/members/${encodedPathSegment(memberId)}`, { ...options, body: input });
+    }
+    removeTeamMember(projectId, memberId, options) {
+        return this.request("DELETE", `/projects/${encodedPathSegment(projectId)}/team/members/${encodedPathSegment(memberId)}`, options);
+    }
     listProviders(projectId, options, requestOptions) {
         const pagination = options ?? {};
         return this.request("GET", `/projects/${encodedPathSegment(projectId)}/providers`, {
@@ -412,6 +600,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateProviders(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listProviders(projectId, pageOptions, requestOptions), options);
+    }
     connectProvider(projectId, providerId, input = {}, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/providers/${encodedPathSegment(providerId)}/connect`, { ...options, body: bodyOrUndefined(input) });
     }
@@ -449,6 +640,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateSavedViews(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listSavedViews(projectId, pageOptions, requestOptions), options);
+    }
     createSavedView(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/saved-views`, { ...options, body: input });
     }
@@ -468,6 +662,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateCompetitors(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listCompetitors(projectId, pageOptions, requestOptions), options);
+    }
     addCompetitor(projectId, input, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/competitors`, { ...options, body: input });
     }
@@ -493,6 +690,9 @@ export class BisibilityClient {
             },
         });
     }
+    iterateMigrationTokens(projectId, options = {}, requestOptions) {
+        return iterateCursorPagination((pageOptions) => this.listMigrationTokens(projectId, pageOptions, requestOptions), options);
+    }
     mintMigrationToken(projectId, input = {}, options) {
         return this.request("POST", `/projects/${encodedPathSegment(projectId)}/migration-tokens`, { ...options, body: bodyOrUndefined(input) });
     }
@@ -502,21 +702,69 @@ export class BisibilityClient {
     revokeMigrationTokenById(tokenId, options) {
         return this.request("DELETE", `/migration-tokens/${encodedPathSegment(tokenId)}`, options);
     }
+    getCloudImportCompatibility(options) {
+        return this.request("GET", "/cloud/import/compatibility", {
+            ...options,
+            auth: false,
+        });
+    }
+    importCloudExport(input, options) {
+        return this.request("POST", "/cloud/import", {
+            ...options,
+            body: input,
+        });
+    }
+    createCloudImportSession(input, options) {
+        return this.request("POST", "/cloud/import/sessions", {
+            ...options,
+            body: input,
+        });
+    }
+    uploadCloudImportChunk(sessionId, index, input, options) {
+        const { contentEncoding, headers, ...requestOptions } = options ?? {};
+        const mergedHeaders = new Headers(headers);
+        if (contentEncoding !== undefined) {
+            mergedHeaders.set("Content-Encoding", contentEncoding);
+        }
+        return this.request("PUT", `/cloud/import/sessions/${encodedPathSegment(sessionId)}/chunks/${encodedPathSegment(String(index))}`, { ...requestOptions, body: input, headers: mergedHeaders });
+    }
+    finalizeCloudImportSession(sessionId, options) {
+        return this.request("POST", `/cloud/import/sessions/${encodedPathSegment(sessionId)}/finalize`, options);
+    }
     buildUrl(path, query) {
         const absolute = isAbsoluteUrl(this.baseUrl);
         const base = `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
         const url = new URL(base, absolute ? undefined : RELATIVE_BASE_ORIGIN);
         if (query) {
             for (const [key, rawValue] of Object.entries(query)) {
-                const value = queryValue(rawValue);
-                if (value !== undefined) {
-                    url.searchParams.set(key, value);
+                const rawValues = Array.isArray(rawValue)
+                    ? rawValue
+                    : [rawValue];
+                for (const rawItem of rawValues) {
+                    const value = queryValue(rawItem);
+                    if (value !== undefined) {
+                        url.searchParams.append(key, value);
+                    }
                 }
             }
         }
         return absolute ? url.toString() : `${url.pathname}${url.search}`;
     }
     async request(method, path, options = {}) {
+        const statusRef = { status: 0 };
+        const result = await this.requestOrUndefined(method, path, options, statusRef);
+        if (result === undefined) {
+            throw new BisibilityResponseError("Bisibility API returned an empty response body.", {
+                body: "",
+                cause: undefined,
+                method,
+                status: statusRef.status,
+                url: this.buildUrl(path, options.query),
+            });
+        }
+        return result;
+    }
+    async requestOrUndefined(method, path, options = {}, statusRef) {
         const fetchImpl = this.#fetchImpl ?? globalThis.fetch;
         const url = this.buildUrl(path, options.query);
         if (!fetchImpl) {
@@ -535,35 +783,71 @@ export class BisibilityClient {
         if (options.idempotencyKey) {
             headers.set("Idempotency-Key", options.idempotencyKey);
         }
-        const init = { headers, method, redirect: "error" };
-        const signal = composedSignal(options.signal, options.timeout);
-        if (signal) {
-            init.signal = signal;
+        headers.set("X-Bisibility-Client", CLIENT_ID);
+        if (!headers.has("User-Agent")) {
+            try {
+                headers.set("User-Agent", CLIENT_ID);
+            }
+            catch {
+                // Browsers may forbid setting User-Agent. X-Bisibility-Client remains authoritative.
+            }
         }
+        const baseInit = { headers, method, redirect: "error" };
         if (options.body !== undefined) {
             if (!headers.has("Content-Type")) {
                 headers.set("Content-Type", "application/json");
             }
-            init.body = JSON.stringify(options.body);
-        }
-        let response;
-        try {
-            response = await fetchImpl(url, init);
-        }
-        catch (error) {
-            throw new BisibilityNetworkError("Network error while calling the Bisibility API.", {
-                cause: error,
-                method,
-                url,
-            });
+            baseInit.body = JSON.stringify(options.body);
         }
-        if (!response.ok) {
-            throw await this.errorFromResponse(response, method, url);
-        }
-        if (options.parseAs === "text") {
-            return response.text();
+        const timeout = options.timeout !== undefined
+            ? validatedTimeout(options.timeout)
+            : this.#timeout !== undefined
+                ? this.#timeout
+                : options.signal
+                    ? null
+                    : DEFAULT_TIMEOUT;
+        const retryable = IDEMPOTENT_METHODS.has(method.toUpperCase()) || headers.has("Idempotency-Key");
+        for (let attempt = 0;; attempt += 1) {
+            const init = { ...baseInit };
+            const signal = composedSignal(options.signal, timeout);
+            if (signal) {
+                init.signal = signal;
+            }
+            let response;
+            try {
+                response = await fetchImpl(url, init);
+            }
+            catch (cause) {
+                if (!retryable || attempt >= this.#maxRetries || options.signal?.aborted) {
+                    throw new BisibilityNetworkError("Network error while calling the Bisibility API.", {
+                        cause,
+                        method,
+                        url,
+                    });
+                }
+                await sleepForRetry(retryBackoffMs(attempt), options.signal, method, url);
+                continue;
+            }
+            if (!response.ok) {
+                const error = await this.errorFromResponse(response, method, url);
+                if (retryable &&
+                    attempt < this.#maxRetries &&
+                    (error.status === 429 || error.status === 503)) {
+                    await sleepForRetry(error.retryAfterSeconds === null
+                        ? retryBackoffMs(attempt)
+                        : error.retryAfterSeconds * 1_000, options.signal, method, url);
+                    continue;
+                }
+                throw error;
+            }
+            if (statusRef) {
+                statusRef.status = response.status;
+            }
+            if (options.parseAs === "text") {
+                return response.text();
+            }
+            return this.jsonFromResponse(response, method, url);
         }
-        return this.jsonFromResponse(response, method, url);
     }
     async jsonFromResponse(response, method, url) {
         const body = await response.text();