@aivisibilityskill/sdk 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,327 @@
+import { verifyWebhook, WebhookVerificationError } from "./webhooks.js";
+export { verifyWebhook, WebhookVerificationError };
+export class AivError extends Error {
+    status;
+    code;
+    detail;
+    requestId;
+    body;
+    constructor(status, code, detail, requestId, 
+    /** Extra fields from the problem response (credits, balance, retry hints…). */
+    body) {
+        super(`${status} ${code}${detail ? `: ${detail}` : ""}`);
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+        this.requestId = requestId;
+        this.body = body;
+        this.name = "AivError";
+    }
+}
+const RETRYABLE = new Set([429, 502, 503, 504]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const enc = encodeURIComponent;
+export const VERSION = "1.0.0";
+/** A cursor-paged list: `for await (const job of aiv.jobs.iterate())`. */
+async function* pages(fetchPage, items) {
+    let before;
+    for (;;) {
+        const page = await fetchPage(before);
+        for (const item of items(page))
+            yield item;
+        if (!page.next)
+            return;
+        before = page.next;
+    }
+}
+export class Aiv {
+    #key;
+    #base;
+    #fetch;
+    #retries;
+    #timeout;
+    constructor(opts) {
+        if (!opts || typeof opts.apiKey !== "string" || !/^aiv_(live|test)_/.test(opts.apiKey))
+            throw new Error("apiKey must start with aiv_live_ or aiv_test_");
+        this.#key = opts.apiKey;
+        this.#base = (opts.baseUrl ?? "https://api.aivisibilityskill.com").replace(/\/+$/, "");
+        this.#fetch = opts.fetch ?? ((req) => fetch(req));
+        this.#retries = Math.max(0, opts.maxRetries ?? 2);
+        this.#timeout = opts.timeoutMs ?? 120_000;
+    }
+    /** Any endpoint, for ones this version doesn't wrap yet. Retries GETs and keyed writes. */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.#base + path);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v === undefined || v === null)
+                continue;
+            url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+        }
+        // GETs are safe to retry; writes only when an idempotency key protects them.
+        const retryable = method === "GET" || opts.idempotencyKey !== undefined;
+        for (let attempt = 0;; attempt++) {
+            const headers = {
+                Authorization: `Bearer ${this.#key}`,
+                Accept: opts.accept === "text" ? "text/csv" : "application/json",
+            };
+            if (opts.body !== undefined)
+                headers["Content-Type"] = "application/json";
+            if (opts.idempotencyKey)
+                headers["Idempotency-Key"] = opts.idempotencyKey;
+            let res;
+            try {
+                res = await this.#fetch(new Request(url, {
+                    method,
+                    headers,
+                    body: opts.body === undefined ? null : JSON.stringify(opts.body),
+                    signal: AbortSignal.timeout(this.#timeout),
+                }));
+            }
+            catch (err) {
+                if (retryable && attempt < this.#retries) {
+                    await sleep(500 * 2 ** attempt);
+                    continue;
+                }
+                throw err;
+            }
+            if (res.ok) {
+                if (res.status === 204)
+                    return undefined;
+                return (opts.accept === "text" ? await res.text() : await res.json());
+            }
+            if (retryable && RETRYABLE.has(res.status) && attempt < this.#retries) {
+                await res.body?.cancel();
+                const after = Number(res.headers.get("Retry-After"));
+                await sleep(Number.isFinite(after) && after > 0 ? Math.min(after, 60) * 1000 : 1000 * 2 ** attempt);
+                continue;
+            }
+            const parsed = await res.json().catch(() => null);
+            const body = parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : {};
+            throw new AivError(res.status, typeof body.code === "string" ? body.code : "http_error", typeof body.detail === "string" ? body.detail : undefined, typeof body.request_id === "string"
+                ? body.request_id
+                : (res.headers.get("X-Request-Id") ?? undefined), body);
+        }
+    }
+    /** Public price list: credits per engine and mode, plans. */
+    pricing() {
+        return this.request("GET", "/v1/pricing");
+    }
+    /** What a check would cost, and whether this key may run it. Free. */
+    estimate(body) {
+        return this.request("POST", "/v1/estimate", { body });
+    }
+    account = {
+        get: () => this.request("GET", "/v1/account"),
+        update: (body) => this.request("PATCH", "/v1/account", { body }),
+    };
+    locales = {
+        list: () => this.request("GET", "/v1/locales"),
+        get: (locale) => this.request("GET", `/v1/locales/${enc(locale)}`),
+    };
+    checks = {
+        /** Starts a check. A retry with the same idempotencyKey never charges twice. */
+        create: (body, opts = {}) => this.request("POST", "/v1/checks", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? crypto.randomUUID(),
+        }),
+    };
+    batches = {
+        /**
+         * Thousands of answers in one request; they run as checks of up to 200 as your plan's
+         * concurrency allows. Retrying with the same idempotencyKey never starts a second batch.
+         */
+        create: (body, opts = {}) => this.request("POST", "/v1/batches", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? crypto.randomUUID(),
+        }),
+        get: (id) => this.request("GET", `/v1/batches/${enc(id)}`),
+        list: (q = {}) => this.request("GET", "/v1/batches", { query: q }),
+        iterate: (q = {}) => pages((before) => this.batches.list({ ...q, ...(before ? { before } : {}) }), (p) => p.batches),
+        /** Stops starting new checks; running ones finish and nothing more is charged. */
+        cancel: (id) => this.request("POST", `/v1/batches/${enc(id)}/cancel`),
+        /** Polls until the batch completes or stops (default timeout: 2 hours). */
+        wait: async (id, opts = {}) => {
+            const deadline = Date.now() + (opts.timeoutMs ?? 2 * 3600_000);
+            for (;;) {
+                const b = await this.batches.get(id);
+                if (b.poll_after_seconds === null || Date.now() >= deadline)
+                    return b;
+                await sleep(Math.min(b.poll_after_seconds * 1000, Math.max(0, deadline - Date.now())));
+            }
+        },
+    };
+    jobs = {
+        get: (id, opts = {}) => this.request("GET", `/v1/jobs/${enc(id)}`, {
+            query: { text: opts.text === false ? "false" : undefined },
+        }),
+        list: (q = {}) => this.request("GET", "/v1/jobs", {
+            query: { limit: q.limit, before: q.before, project_id: q.projectId, customer: q.customer },
+        }),
+        /** Every job, newest first, across pages. */
+        iterate: (q = {}) => pages((before) => this.jobs.list({ ...q, ...(before ? { before } : {}) }), (p) => p.jobs),
+        /** Polls (at the pace the API suggests) until the job finishes or the timeout passes. */
+        wait: async (id, opts = {}) => {
+            const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60_000);
+            for (;;) {
+                const job = await this.jobs.get(id);
+                if (job.finished_at || job.poll_after_seconds === null)
+                    return job;
+                if (Date.now() >= deadline)
+                    return job;
+                await sleep(Math.min(job.poll_after_seconds * 1000, Math.max(0, deadline - Date.now())));
+            }
+        },
+    };
+    answers = {
+        get: (id) => this.request("GET", `/v1/answers/${enc(id)}`),
+        /** The engine's raw response, as stored when the answer was collected. */
+        receipt: (id) => this.request("GET", `/v1/answers/${enc(id)}/receipt`),
+    };
+    projects = {
+        create: (body, opts = {}) => this.request("POST", "/v1/projects", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? crypto.randomUUID(),
+        }),
+        list: (q = {}) => this.request("GET", "/v1/projects", { query: q }),
+        get: (id) => this.request("GET", `/v1/projects/${enc(id)}`),
+        update: (id, body) => this.request("PATCH", `/v1/projects/${enc(id)}`, { body }),
+        archive: (id) => this.request("DELETE", `/v1/projects/${enc(id)}`),
+        visibility: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/visibility`, {
+            query: analyticsQuery(q),
+        }),
+        competitors: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/competitors`, {
+            query: analyticsQuery(q),
+        }),
+        sources: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/sources`, {
+            query: analyticsQuery(q),
+        }),
+        facts: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/facts`, {
+            query: analyticsQuery(q),
+        }),
+        history: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/history`, {
+            query: { ...analyticsQuery(q), bucket: q.bucket },
+        }),
+        /** Paid action: robots.txt, llms.txt, sitemaps and key pages, as AI crawlers see them. */
+        siteCheck: (id, body = {}) => this.request("POST", `/v1/projects/${enc(id)}/site-check`, { body }),
+        /** Paid action: what ranks on Google for a question and what those pages say. */
+        research: (id, body) => this.request("POST", `/v1/projects/${enc(id)}/research`, { body }),
+        /** Paid action: ranks what to fix first from the project's answers and checks. */
+        findOpportunities: (id, body = {}) => this.request("POST", `/v1/projects/${enc(id)}/opportunities`, { body }),
+        opportunities: (id, q = {}) => this.request("GET", `/v1/projects/${enc(id)}/opportunities`, { query: q }),
+    };
+    opportunities = {
+        get: (id) => this.request("GET", `/v1/opportunities/${enc(id)}`),
+        update: (id, body) => this.request("PATCH", `/v1/opportunities/${enc(id)}`, { body }),
+        /** Paid action: a step-by-step fix brief for one opportunity. */
+        brief: (id, body = {}) => this.request("POST", `/v1/opportunities/${enc(id)}/brief`, { body }),
+        /** Records a fix you shipped; it's verified on the site and later in AI answers. */
+        recordFix: (id, body) => this.request("POST", `/v1/opportunities/${enc(id)}/fixes`, { body }),
+    };
+    fixes = {
+        get: (id) => this.request("GET", `/v1/fixes/${enc(id)}`),
+        verify: (id, body = {}) => this.request("POST", `/v1/fixes/${enc(id)}/verify`, {
+            body,
+        }),
+    };
+    actions = {
+        get: (id) => this.request("GET", `/v1/actions/${enc(id)}`),
+        /** Polls a paid action (site check, research, brief…) until it's done. */
+        wait: async (id, opts = {}) => {
+            const deadline = Date.now() + (opts.timeoutMs ?? 10 * 60_000);
+            for (;;) {
+                const action = await this.actions.get(id);
+                if (action.poll_after_seconds === null || Date.now() >= deadline)
+                    return action;
+                await sleep(Math.min(action.poll_after_seconds * 1000, Math.max(0, deadline - Date.now())));
+            }
+        },
+    };
+    keys = {
+        list: (q = {}) => this.request("GET", "/v1/keys", { query: q }),
+        iterate: (q = {}) => pages((before) => this.keys.list({ ...q, ...(before ? { before } : {}) }), (p) => p.keys),
+        /** The response's `secret` is shown once. */
+        create: (body) => this.request("POST", "/v1/keys", { body }),
+        update: (id, body) => this.request("PATCH", `/v1/keys/${enc(id)}`, { body }),
+        revoke: (id) => this.request("DELETE", `/v1/keys/${enc(id)}`),
+    };
+    usage = {
+        get: (q = {}) => this.request("GET", "/v1/usage", { query: usageQuery(q) }),
+        /** The same report as CSV text, ready for a spreadsheet or an invoice. */
+        csv: (q = {}) => this.request("GET", "/v1/usage", {
+            query: { ...usageQuery(q), format: "csv" },
+            accept: "text",
+        }),
+    };
+    webhooks = {
+        list: () => this.request("GET", "/v1/webhooks"),
+        /** The response's `secret` (whsec_…) is shown once: store it to verify deliveries. */
+        create: (body) => this.request("POST", "/v1/webhooks", { body }),
+        get: (id) => this.request("GET", `/v1/webhooks/${enc(id)}`),
+        update: (id, body) => this.request("PATCH", `/v1/webhooks/${enc(id)}`, { body }),
+        delete: (id) => this.request("DELETE", `/v1/webhooks/${enc(id)}`),
+        /** A new secret; the old one keeps working for 24 hours. */
+        rotateSecret: (id, body = {}) => this.request("POST", `/v1/webhooks/${enc(id)}/rotate-secret`, { body }),
+        /** Sends a `ping` event to this endpoint only. */
+        test: (id, body = {}) => this.request("POST", `/v1/webhooks/${enc(id)}/test`, {
+            body,
+        }),
+        /** Re-sends everything the endpoint missed since a time (ISO date), and re-enables it. */
+        recover: (id, body) => this.request("POST", `/v1/webhooks/${enc(id)}/recover`, { body }),
+        deliveries: {
+            list: (id, q = {}) => this.request("GET", `/v1/webhooks/${enc(id)}/deliveries`, { query: q }),
+            get: (id, deliveryId) => this.request("GET", `/v1/webhooks/${enc(id)}/deliveries/${enc(deliveryId)}`),
+            resend: (id, deliveryId) => this.request("POST", `/v1/webhooks/${enc(id)}/deliveries/${enc(deliveryId)}/resend`),
+        },
+    };
+    events = {
+        list: (q = {}) => this.request("GET", "/v1/events", {
+            query: q,
+        }),
+        get: (id) => this.request("GET", `/v1/events/${enc(id)}`),
+        /** Every event, newest first (the last 30 days). */
+        iterate: (q = {}) => pages((before) => this.events.list({ ...q, ...(before ? { before } : {}) }), (p) => p.events),
+    };
+    auditLog = {
+        list: (q = {}) => this.request("GET", "/v1/audit-log", {
+            query: q,
+        }),
+        iterate: (q = {}) => pages((before) => this.auditLog.list({ ...q, ...(before !== undefined ? { before } : {}) }), (p) => p.entries),
+    };
+    customers = {
+        /**
+         * Deletes everything stored for one of your customers (irreversible). Runs in the
+         * background: poll `dataDeletions.get(id)` or `dataDeletions.wait(id)`.
+         */
+        deleteData: (customer) => this.request("POST", `/v1/customers/${enc(customer)}/delete-data`, {
+            body: { confirm: true },
+        }),
+    };
+    dataDeletions = {
+        get: (id) => this.request("GET", `/v1/data-deletions/${enc(id)}`),
+        wait: async (id, opts = {}) => {
+            const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60_000);
+            for (;;) {
+                const d = await this.dataDeletions.get(id);
+                if (d.status === "completed" || d.status === "failed" || Date.now() >= deadline)
+                    return d;
+                await sleep(Math.min(opts.intervalMs ?? 30_000, Math.max(0, deadline - Date.now())));
+            }
+        },
+    };
+    /** Checks a webhook delivery's signature and returns the parsed event. Throws if it's not ours. */
+    static verifyWebhook = verifyWebhook;
+}
+function analyticsQuery(q) {
+    return { question_id: q.questionId, engines: q.engines, days: q.days };
+}
+function usageQuery(q) {
+    return {
+        from: q.from,
+        to: q.to,
+        group_by: q.groupBy,
+        customer: q.customer,
+        project_id: q.projectId,
+    };
+}