@aivisibilityskill/sdk 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1308 @@
+import type { components, paths } from "./schema.js";
+import { verifyWebhook, WebhookVerificationError } from "./webhooks.js";
+export type { WebhookHeaders } from "./webhooks.js";
+export { verifyWebhook, WebhookVerificationError };
+/**
+ * aivisibilityskill API client.
+ *
+ *   import { Aiv } from "@aivisibilityskill/sdk";
+ *   const aiv = new Aiv({ apiKey: process.env.AIV_KEY! });
+ *   const job = await aiv.checks.create({ questions: ["best invoicing app for freelancers"] });
+ *   const done = await aiv.jobs.wait(job.id);
+ *
+ * Checks and project creation carry an Idempotency-Key, so the client can safely retry them after
+ * a network error or a 429/5xx without ever paying twice; other writes are never retried. Errors throw AivError with the
+ * API's stable `code`. Every request and response is typed from the API's OpenAPI document.
+ */
+export type Schemas = components["schemas"];
+export type Account = Schemas["Account"];
+export type Job = Schemas["Job"];
+export type JobResponse = Schemas["JobResponse"];
+export type Answer = Schemas["Answer"];
+export type Project = Schemas["Project"];
+export type Key = Schemas["Key"];
+export type CheckRequest = Schemas["CheckRequest"];
+export type ProjectRequest = Schemas["ProjectRequest"];
+export type ProjectPatch = Schemas["ProjectPatch"];
+export type KeyRequest = Schemas["KeyRequest"];
+export type Estimate = Schemas["Estimate"];
+export type ActionResult = Schemas["ActionResult"];
+export type Opportunity = Schemas["Opportunity"];
+export type Fix = Schemas["Fix"];
+export type Webhook = Schemas["Webhook"];
+export type WebhookDelivery = Schemas["WebhookDelivery"];
+export type Event = Schemas["Event"];
+export type AuditEntry = Schemas["AuditEntry"];
+export type DataDeletion = Schemas["DataDeletion"];
+export type Usage = Schemas["Usage"];
+export type Batch = Schemas["Batch"];
+export type BatchRequest = Schemas["BatchRequest"];
+export type EngineId = NonNullable<CheckRequest["engines"]>[number];
+type Method = "get" | "post" | "patch" | "delete";
+type Op<P extends keyof paths, M extends Method> = NonNullable<paths[P][M]>;
+type Body<P extends keyof paths, M extends Method> = Op<P, M> extends {
+    requestBody?: {
+        content: {
+            "application/json": infer B;
+        };
+    };
+} ? B : never;
+type Query<P extends keyof paths, M extends Method> = Op<P, M> extends {
+    parameters: {
+        query?: infer Q;
+    };
+} ? NonNullable<Q> : never;
+export declare class AivError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly detail: string | undefined;
+    readonly requestId: string | undefined;
+    /** Extra fields from the problem response (credits, balance, retry hints…). */
+    readonly body: Record<string, unknown>;
+    constructor(status: number, code: string, detail: string | undefined, requestId: string | undefined, 
+    /** Extra fields from the problem response (credits, balance, retry hints…). */
+    body: Record<string, unknown>);
+}
+export interface AivOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: (input: Request) => Promise<Response>;
+    /** Retries for 429/502/503/504, network errors and timeouts on safe requests. Default 2. */
+    maxRetries?: number;
+    /** Per attempt. Default 120s, above the longest server-side wait (90s). */
+    timeoutMs?: number;
+}
+/** Options for writes that spend credits: pass your own key to make retries across processes safe. */
+export interface WriteOptions {
+    idempotencyKey?: string;
+}
+export interface WaitOptions {
+    /** Give up (and return the unfinished result) after this long. Default 10 minutes. */
+    timeoutMs?: number;
+}
+export declare const VERSION = "1.0.0";
+type QueryValue = string | number | boolean | readonly string[] | undefined | null;
+interface RequestOptions {
+    body?: unknown;
+    query?: Record<string, QueryValue>;
+    idempotencyKey?: string;
+    accept?: "json" | "text";
+}
+export declare class Aiv {
+    #private;
+    constructor(opts: AivOptions);
+    /** Any endpoint, for ones this version doesn't wrap yet. Retries GETs and keyed writes. */
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /** Public price list: credits per engine and mode, plans. */
+    pricing(): Promise<{
+        price_version: number;
+        credits_per_usd: number;
+        credits: {
+            [key: string]: number;
+        };
+        engines: {
+            id: string;
+            label: string;
+            surface: "app" | "serp" | "api";
+            credits: {
+                [key: string]: number;
+            };
+        }[];
+        plans: {
+            id: string;
+            label: string;
+            monthly_usd: number | null;
+            credits: number | null;
+            req_per_min: number;
+            concurrent_tasks: number;
+            projects: number;
+            history_days: number;
+            reports: string;
+        }[];
+        terms: {
+            free_credit_expiry_days: number;
+            payg_min_topup_usd: number;
+            payg_credit_expiry_days: number;
+            yearly_discount: number;
+        };
+    }>;
+    /** What a check would cost, and whether this key may run it. Free. */
+    estimate(body: Body<"/v1/estimate", "post">): Promise<{
+        credits: number;
+        answers: number;
+        reused_answers: number;
+        by_engine: {
+            [key: string]: {
+                answers: number;
+                credits: number;
+            };
+        };
+        balance: number;
+        budget_remaining_today: number | null;
+        confirmation_required: boolean;
+        affordable: boolean;
+    }>;
+    readonly account: {
+        get: () => Promise<{
+            account: {
+                id: string;
+                plan: string;
+                mode: "live" | "test";
+                balance: number;
+                reserved: number;
+                balance_alert_below: number | null;
+                limits: {
+                    requests_per_minute: number;
+                    concurrent_answers: number;
+                    projects: number;
+                    history_days: number;
+                };
+            };
+            key: components["schemas"]["Key"] & {
+                used_today: number;
+                budget_remaining_today: number | null;
+            };
+        }>;
+        update: (body: Body<"/v1/account", "patch">) => Promise<{
+            account: {
+                id: string;
+                plan: string;
+                mode: "live" | "test";
+                balance: number;
+                reserved: number;
+                balance_alert_below: number | null;
+                limits: {
+                    requests_per_minute: number;
+                    concurrent_answers: number;
+                    projects: number;
+                    history_days: number;
+                };
+            };
+            key: components["schemas"]["Key"] & {
+                used_today: number;
+                budget_remaining_today: number | null;
+            };
+        }>;
+    };
+    readonly locales: {
+        list: () => Promise<{
+            format: string;
+            default: string;
+            updated: string;
+            countries: {
+                code: string;
+                name: string;
+                engines: ("chatgpt" | "gemini" | "ai_overviews" | "ai_mode" | "deepseek" | "perplexity" | "claude" | "grok")[];
+            }[];
+            languages: {
+                code: string;
+                name: string;
+                engines: ("chatgpt" | "gemini" | "ai_overviews" | "ai_mode" | "deepseek" | "perplexity" | "claude" | "grok")[];
+            }[];
+        }>;
+        get: (locale: string) => Promise<{
+            locale: string;
+            language: {
+                code: string;
+                name: string;
+            };
+            country: {
+                code: string;
+                name: string;
+            };
+            engines: {
+                engine: "chatgpt" | "gemini" | "ai_overviews" | "ai_mode" | "deepseek" | "perplexity" | "claude" | "grok";
+                supported: boolean;
+                language_code: string | null;
+                reason: string | null;
+            }[];
+        }>;
+    };
+    readonly checks: {
+        /** Starts a check. A retry with the same idempotencyKey never charges twice. */
+        create: (body: CheckRequest, opts?: WriteOptions) => Promise<{
+            id: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            created_at: string;
+            finished_at: string | null;
+            project_id: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            sandbox: boolean;
+            price_version: number;
+            credits: components["schemas"]["JobCredits"];
+            progress: {
+                total: number;
+                done: number;
+                failed: number;
+                running: number;
+            };
+            poll_after_seconds: number | null;
+            answers: components["schemas"]["Answer"][];
+            failures: {
+                engine: string;
+                question: string;
+                sample: number;
+                code: string;
+                message: string;
+            }[];
+        } & {
+            deduplicated: boolean;
+        }>;
+    };
+    readonly 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: BatchRequest, opts?: WriteOptions) => Promise<{
+            id: string;
+            status: "running" | "stopping" | "completed" | "stopped";
+            stop_reason: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            answers: {
+                total: number;
+                started: number;
+                succeeded: number;
+                failed: number;
+                running: number;
+                not_started: number;
+            };
+            credits: {
+                estimate: number;
+                reserved: number;
+                charged: number;
+                refunded: number;
+            };
+            checks: string[];
+            created_at: string;
+            completed_at: string | null;
+            poll_after_seconds: number | null;
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            status: "running" | "stopping" | "completed" | "stopped";
+            stop_reason: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            answers: {
+                total: number;
+                started: number;
+                succeeded: number;
+                failed: number;
+                running: number;
+                not_started: number;
+            };
+            credits: {
+                estimate: number;
+                reserved: number;
+                charged: number;
+                refunded: number;
+            };
+            checks: string[];
+            created_at: string;
+            completed_at: string | null;
+            poll_after_seconds: number | null;
+        }>;
+        list: (q?: {
+            limit?: number;
+            before?: string;
+            customer?: string;
+        }) => Promise<{
+            batches: components["schemas"]["Batch"][];
+            next: string | null;
+        }>;
+        iterate: (q?: {
+            customer?: string;
+            limit?: number;
+        }) => AsyncGenerator<{
+            id: string;
+            status: "running" | "stopping" | "completed" | "stopped";
+            stop_reason: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            answers: {
+                total: number;
+                started: number;
+                succeeded: number;
+                failed: number;
+                running: number;
+                not_started: number;
+            };
+            credits: {
+                estimate: number;
+                reserved: number;
+                charged: number;
+                refunded: number;
+            };
+            checks: string[];
+            created_at: string;
+            completed_at: string | null;
+            poll_after_seconds: number | null;
+        }, any, any>;
+        /** Stops starting new checks; running ones finish and nothing more is charged. */
+        cancel: (id: string) => Promise<{
+            id: string;
+            status: "running" | "stopping" | "completed" | "stopped";
+            stop_reason: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            answers: {
+                total: number;
+                started: number;
+                succeeded: number;
+                failed: number;
+                running: number;
+                not_started: number;
+            };
+            credits: {
+                estimate: number;
+                reserved: number;
+                charged: number;
+                refunded: number;
+            };
+            checks: string[];
+            created_at: string;
+            completed_at: string | null;
+            poll_after_seconds: number | null;
+        }>;
+        /** Polls until the batch completes or stops (default timeout: 2 hours). */
+        wait: (id: string, opts?: WaitOptions) => Promise<{
+            id: string;
+            status: "running" | "stopping" | "completed" | "stopped";
+            stop_reason: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            answers: {
+                total: number;
+                started: number;
+                succeeded: number;
+                failed: number;
+                running: number;
+                not_started: number;
+            };
+            credits: {
+                estimate: number;
+                reserved: number;
+                charged: number;
+                refunded: number;
+            };
+            checks: string[];
+            created_at: string;
+            completed_at: string | null;
+            poll_after_seconds: number | null;
+        }>;
+    };
+    readonly jobs: {
+        get: (id: string, opts?: {
+            text?: boolean;
+        }) => Promise<{
+            id: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            created_at: string;
+            finished_at: string | null;
+            project_id: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            sandbox: boolean;
+            price_version: number;
+            credits: components["schemas"]["JobCredits"];
+            progress: {
+                total: number;
+                done: number;
+                failed: number;
+                running: number;
+            };
+            poll_after_seconds: number | null;
+            answers: components["schemas"]["Answer"][];
+            failures: {
+                engine: string;
+                question: string;
+                sample: number;
+                code: string;
+                message: string;
+            }[];
+        }>;
+        list: (q?: {
+            limit?: number;
+            before?: string;
+            projectId?: string;
+            customer?: string;
+        }) => Promise<{
+            jobs: {
+                id: string;
+                status: "running" | "succeeded" | "partial" | "failed";
+                created_at: string;
+                finished_at: string | null;
+                project_id: string | null;
+                customer: string | null;
+                metadata: {
+                    [key: string]: string;
+                };
+                sandbox: boolean;
+                credits: components["schemas"]["JobCredits"];
+            }[];
+            next: string | null;
+        }>;
+        /** Every job, newest first, across pages. */
+        iterate: (q?: {
+            projectId?: string;
+            customer?: string;
+            limit?: number;
+        }) => AsyncGenerator<{
+            id: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            created_at: string;
+            finished_at: string | null;
+            project_id: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            sandbox: boolean;
+            credits: components["schemas"]["JobCredits"];
+        }, any, any>;
+        /** Polls (at the pace the API suggests) until the job finishes or the timeout passes. */
+        wait: (id: string, opts?: WaitOptions) => Promise<{
+            id: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            created_at: string;
+            finished_at: string | null;
+            project_id: string | null;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            sandbox: boolean;
+            price_version: number;
+            credits: components["schemas"]["JobCredits"];
+            progress: {
+                total: number;
+                done: number;
+                failed: number;
+                running: number;
+            };
+            poll_after_seconds: number | null;
+            answers: components["schemas"]["Answer"][];
+            failures: {
+                engine: string;
+                question: string;
+                sample: number;
+                code: string;
+                message: string;
+            }[];
+        }>;
+    };
+    readonly answers: {
+        get: (id: string) => Promise<{
+            id: string;
+            engine: string;
+            engine_label: string;
+            surface: string;
+            mode: string;
+            question: string;
+            locale: string;
+            collected_at: string;
+            has_ai_answer: boolean;
+            text?: string;
+            model: string | null;
+            reading: "done" | "partial" | "pending";
+            citations: components["schemas"]["Citation"][];
+            brands: components["schemas"]["BrandMention"][];
+            facts: components["schemas"]["Fact"][];
+            sandbox: boolean;
+            reused: boolean;
+            receipt: {
+                sha256: string;
+                url: string;
+            } | null;
+        }>;
+        /** The engine's raw response, as stored when the answer was collected. */
+        receipt: (id: string) => Promise<unknown>;
+    };
+    readonly projects: {
+        create: (body: ProjectRequest, opts?: WriteOptions) => Promise<{
+            id: string;
+            name: string;
+            brand: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            };
+            competitors: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            }[];
+            questions: {
+                id: string;
+                question: string;
+            }[];
+            engines: string[];
+            locale: string;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            schedule: {
+                cadence: "off" | "daily" | "weekly";
+                mode: string;
+                samples: number;
+                next_run_at: string | null;
+                credits_per_run: number;
+                credits_per_month: number;
+            };
+            last_run: {
+                at: string | null;
+                job_id: string | null;
+                error: string | null;
+            };
+            created_at: string;
+            updated_at: string;
+        }>;
+        list: (q?: {
+            customer?: string;
+        }) => Promise<{
+            projects: components["schemas"]["Project"][];
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            name: string;
+            brand: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            };
+            competitors: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            }[];
+            questions: {
+                id: string;
+                question: string;
+            }[];
+            engines: string[];
+            locale: string;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            schedule: {
+                cadence: "off" | "daily" | "weekly";
+                mode: string;
+                samples: number;
+                next_run_at: string | null;
+                credits_per_run: number;
+                credits_per_month: number;
+            };
+            last_run: {
+                at: string | null;
+                job_id: string | null;
+                error: string | null;
+            };
+            created_at: string;
+            updated_at: string;
+        }>;
+        update: (id: string, body: ProjectPatch) => Promise<{
+            id: string;
+            name: string;
+            brand: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            };
+            competitors: {
+                name: string;
+                aliases: string[];
+                domains: string[];
+            }[];
+            questions: {
+                id: string;
+                question: string;
+            }[];
+            engines: string[];
+            locale: string;
+            customer: string | null;
+            metadata: {
+                [key: string]: string;
+            };
+            schedule: {
+                cadence: "off" | "daily" | "weekly";
+                mode: string;
+                samples: number;
+                next_run_at: string | null;
+                credits_per_run: number;
+                credits_per_month: number;
+            };
+            last_run: {
+                at: string | null;
+                job_id: string | null;
+                error: string | null;
+            };
+            created_at: string;
+            updated_at: string;
+        }>;
+        archive: (id: string) => Promise<void>;
+        visibility: (id: string, q?: AnalyticsQuery) => Promise<{
+            brand: string;
+            overall: {
+                answers: number;
+                with_ai_answer: number;
+                mentioned: components["schemas"]["Rate"];
+                mentioned_when_answered: components["schemas"]["Rate"];
+                recommended: components["schemas"]["Rate"];
+                cited: components["schemas"]["Rate"];
+                avg_rank: number | null;
+                sentiment: {
+                    positive: number;
+                    neutral: number;
+                    negative: number;
+                };
+            };
+            engines: {
+                [key: string]: {
+                    answers: number;
+                    with_ai_answer: number;
+                    mentioned: components["schemas"]["Rate"];
+                    mentioned_when_answered: components["schemas"]["Rate"];
+                    recommended: components["schemas"]["Rate"];
+                    cited: components["schemas"]["Rate"];
+                    avg_rank: number | null;
+                    sentiment: {
+                        positive: number;
+                        neutral: number;
+                        negative: number;
+                    };
+                };
+            };
+            unread: number;
+            meta: {
+                cached: boolean;
+                credits_charged: number;
+                window: {
+                    from: string;
+                    days: number;
+                };
+            };
+        }>;
+        competitors: (id: string, q?: AnalyticsQuery) => Promise<{
+            answers: number;
+            brands: {
+                name: string;
+                is_you: boolean;
+                tracked: boolean;
+                mentioned: components["schemas"]["Rate"];
+                recommended: components["schemas"]["Rate"];
+                avg_rank: number | null;
+                share_of_voice: number;
+            }[];
+            unread: number;
+            meta: {
+                cached: boolean;
+                credits_charged: number;
+                window: {
+                    from: string;
+                    days: number;
+                };
+            };
+        }>;
+        sources: (id: string, q?: AnalyticsQuery) => Promise<{
+            answers: number;
+            domains: {
+                domain: string;
+                type: string;
+                cited: components["schemas"]["Rate"];
+                citations: number;
+                is_yours: boolean;
+                top_urls: {
+                    url: string;
+                    citations: number;
+                }[];
+            }[];
+            by_type: {
+                [key: string]: {
+                    answers: number;
+                    citations: number;
+                };
+            };
+            meta: {
+                cached: boolean;
+                credits_charged: number;
+                window: {
+                    from: string;
+                    days: number;
+                };
+            };
+        }>;
+        facts: (id: string, q?: AnalyticsQuery) => Promise<{
+            facts: {
+                type: string;
+                value: string;
+                answers: number;
+                engines: string[];
+                quote: string;
+                last_seen: string;
+                price: {
+                    amount: number;
+                    currency: string | null;
+                    period: string | null;
+                    per_user: boolean;
+                } | null;
+            }[];
+            meta: {
+                cached: boolean;
+                credits_charged: number;
+                window: {
+                    from: string;
+                    days: number;
+                };
+            };
+        }>;
+        history: (id: string, q?: AnalyticsQuery & {
+            bucket?: "week" | "day";
+        }) => Promise<{
+            points: {
+                period: string;
+                mentioned: components["schemas"]["Rate"];
+            }[];
+            meta: {
+                cached: boolean;
+                credits_charged: number;
+                window: {
+                    from: string;
+                    days: number;
+                };
+            };
+        }>;
+        /** Paid action: robots.txt, llms.txt, sitemaps and key pages, as AI crawlers see them. */
+        siteCheck: (id: string, body?: Body<"/v1/projects/{id}/site-check", "post">) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+        /** Paid action: what ranks on Google for a question and what those pages say. */
+        research: (id: string, body: Body<"/v1/projects/{id}/research", "post">) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+        /** Paid action: ranks what to fix first from the project's answers and checks. */
+        findOpportunities: (id: string, body?: Body<"/v1/projects/{id}/opportunities", "post">) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+        opportunities: (id: string, q?: Query<"/v1/projects/{id}/opportunities", "get">) => Promise<{
+            opportunities: components["schemas"]["Opportunity"][];
+        }>;
+    };
+    readonly opportunities: {
+        get: (id: string) => Promise<{
+            [key: string]: unknown;
+        }>;
+        update: (id: string, body: Body<"/v1/opportunities/{id}", "patch">) => Promise<{
+            [key: string]: unknown;
+        }>;
+        /** Paid action: a step-by-step fix brief for one opportunity. */
+        brief: (id: string, body?: Body<"/v1/opportunities/{id}/brief", "post">) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+        /** Records a fix you shipped; it's verified on the site and later in AI answers. */
+        recordFix: (id: string, body: Body<"/v1/opportunities/{id}/fixes", "post">) => Promise<{
+            [key: string]: unknown;
+        }>;
+    };
+    readonly fixes: {
+        get: (id: string) => Promise<{
+            [key: string]: unknown;
+        }>;
+        verify: (id: string, body?: Body<"/v1/fixes/{id}/verify", "post">) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+    };
+    readonly actions: {
+        get: (id: string) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+        /** Polls a paid action (site check, research, brief…) until it's done. */
+        wait: (id: string, opts?: WaitOptions) => Promise<{
+            job_id: string;
+            kind: string;
+            status: "running" | "succeeded" | "partial" | "failed";
+            sandbox: boolean;
+            deduplicated: boolean;
+            credits: {
+                quoted: number;
+                charged: number | null;
+                refunded: number | null;
+            };
+            poll_after_seconds: number | null;
+            error: {
+                code: string;
+                message: string;
+            } | null;
+            result: {
+                [key: string]: unknown;
+            } | null;
+        }>;
+    };
+    readonly keys: {
+        list: (q?: {
+            limit?: number;
+            before?: string;
+            customer?: string;
+        }) => Promise<{
+            keys: components["schemas"]["Key"][];
+            next: string | null;
+        }>;
+        iterate: (q?: {
+            customer?: string;
+            limit?: number;
+        }) => AsyncGenerator<{
+            id: string;
+            name: string;
+            mode: "live" | "test";
+            kind: "rest" | "mcp";
+            scope: "full" | "read";
+            display: string;
+            daily_budget: number | null;
+            daily_budget_follows_plan: boolean;
+            confirm_above: number | null;
+            customer: string | null;
+            allowed_ips: string[] | null;
+            status: "active" | "revoked" | "expired";
+            created_at: string;
+            last_used_at: string | null;
+            expires_at: string | null;
+            revoked_at: string | null;
+        }, any, any>;
+        /** The response's `secret` is shown once. */
+        create: (body: KeyRequest) => Promise<{
+            id: string;
+            name: string;
+            mode: "live" | "test";
+            kind: "rest" | "mcp";
+            scope: "full" | "read";
+            display: string;
+            daily_budget: number | null;
+            daily_budget_follows_plan: boolean;
+            confirm_above: number | null;
+            customer: string | null;
+            allowed_ips: string[] | null;
+            status: "active" | "revoked" | "expired";
+            created_at: string;
+            last_used_at: string | null;
+            expires_at: string | null;
+            revoked_at: string | null;
+        } & {
+            secret: string;
+        }>;
+        update: (id: string, body: Schemas["KeyPatch"]) => Promise<{
+            id: string;
+            name: string;
+            mode: "live" | "test";
+            kind: "rest" | "mcp";
+            scope: "full" | "read";
+            display: string;
+            daily_budget: number | null;
+            daily_budget_follows_plan: boolean;
+            confirm_above: number | null;
+            customer: string | null;
+            allowed_ips: string[] | null;
+            status: "active" | "revoked" | "expired";
+            created_at: string;
+            last_used_at: string | null;
+            expires_at: string | null;
+            revoked_at: string | null;
+        }>;
+        revoke: (id: string) => Promise<void>;
+    };
+    readonly usage: {
+        get: (q?: UsageQuery) => Promise<{
+            from: string;
+            to: string;
+            group_by: ("day" | "month" | "customer" | "project" | "key" | "kind" | "engine")[];
+            customer: string | null;
+            project_id: string | null;
+            totals: {
+                credits: number;
+                pending: number;
+                refunded: number;
+                answers: number;
+                actions: number;
+                analytics: number;
+                failed: number;
+            };
+            rows: components["schemas"]["UsageRow"][];
+        }>;
+        /** The same report as CSV text, ready for a spreadsheet or an invoice. */
+        csv: (q?: UsageQuery) => Promise<string>;
+    };
+    readonly webhooks: {
+        list: () => Promise<{
+            webhooks: components["schemas"]["Webhook"][];
+        }>;
+        /** The response's `secret` (whsec_…) is shown once: store it to verify deliveries. */
+        create: (body: Schemas["WebhookRequest"]) => Promise<{
+            id: string;
+            url: string;
+            description: string | null;
+            events: string[];
+            customer: string | null;
+            status: "enabled" | "disabled";
+            disabled_reason: "failing" | "manual" | null;
+            disabled_at: string | null;
+            failing_since: string | null;
+            last_success_at: string | null;
+            last_failure_at: string | null;
+            previous_secret_expires_at: string | null;
+            created_at: string;
+            updated_at: string;
+        } & {
+            secret: string;
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            url: string;
+            description: string | null;
+            events: string[];
+            customer: string | null;
+            status: "enabled" | "disabled";
+            disabled_reason: "failing" | "manual" | null;
+            disabled_at: string | null;
+            failing_since: string | null;
+            last_success_at: string | null;
+            last_failure_at: string | null;
+            previous_secret_expires_at: string | null;
+            created_at: string;
+            updated_at: string;
+        }>;
+        update: (id: string, body: Schemas["WebhookPatch"]) => Promise<{
+            id: string;
+            url: string;
+            description: string | null;
+            events: string[];
+            customer: string | null;
+            status: "enabled" | "disabled";
+            disabled_reason: "failing" | "manual" | null;
+            disabled_at: string | null;
+            failing_since: string | null;
+            last_success_at: string | null;
+            last_failure_at: string | null;
+            previous_secret_expires_at: string | null;
+            created_at: string;
+            updated_at: string;
+        }>;
+        delete: (id: string) => Promise<void>;
+        /** A new secret; the old one keeps working for 24 hours. */
+        rotateSecret: (id: string, body?: Body<"/v1/webhooks/{id}/rotate-secret", "post">) => Promise<{
+            id: string;
+            url: string;
+            description: string | null;
+            events: string[];
+            customer: string | null;
+            status: "enabled" | "disabled";
+            disabled_reason: "failing" | "manual" | null;
+            disabled_at: string | null;
+            failing_since: string | null;
+            last_success_at: string | null;
+            last_failure_at: string | null;
+            previous_secret_expires_at: string | null;
+            created_at: string;
+            updated_at: string;
+        } & {
+            secret: string;
+        }>;
+        /** Sends a `ping` event to this endpoint only. */
+        test: (id: string, body?: Body<"/v1/webhooks/{id}/test", "post">) => Promise<{
+            id: string;
+            event_id: string;
+            event_type: string;
+            status: "pending" | "succeeded" | "failed" | "skipped";
+            attempts: number;
+            max_attempts: number;
+            next_attempt_at: string | null;
+            last_attempt_at: string | null;
+            last_status: number | null;
+            last_error: string | null;
+            last_latency_ms: number | null;
+            succeeded_at: string | null;
+            created_at: string;
+        } & {
+            attempt_log: {
+                attempt: number;
+                at: string;
+                status: number | null;
+                error: string | null;
+                latency_ms: number | null;
+                response: string | null;
+            }[];
+            event: components["schemas"]["Event"];
+        }>;
+        /** Re-sends everything the endpoint missed since a time (ISO date), and re-enables it. */
+        recover: (id: string, body: Body<"/v1/webhooks/{id}/recover", "post">) => Promise<{
+            recovered: number;
+        }>;
+        deliveries: {
+            list: (id: string, q?: {
+                status?: Query<"/v1/webhooks/{id}/deliveries", "get">["status"];
+                limit?: number;
+                before?: string;
+            }) => Promise<{
+                deliveries: components["schemas"]["WebhookDelivery"][];
+                next: string | null;
+            }>;
+            get: (id: string, deliveryId: string) => Promise<{
+                id: string;
+                event_id: string;
+                event_type: string;
+                status: "pending" | "succeeded" | "failed" | "skipped";
+                attempts: number;
+                max_attempts: number;
+                next_attempt_at: string | null;
+                last_attempt_at: string | null;
+                last_status: number | null;
+                last_error: string | null;
+                last_latency_ms: number | null;
+                succeeded_at: string | null;
+                created_at: string;
+            } & {
+                attempt_log: {
+                    attempt: number;
+                    at: string;
+                    status: number | null;
+                    error: string | null;
+                    latency_ms: number | null;
+                    response: string | null;
+                }[];
+                event: components["schemas"]["Event"];
+            }>;
+            resend: (id: string, deliveryId: string) => Promise<{
+                id: string;
+                event_id: string;
+                event_type: string;
+                status: "pending" | "succeeded" | "failed" | "skipped";
+                attempts: number;
+                max_attempts: number;
+                next_attempt_at: string | null;
+                last_attempt_at: string | null;
+                last_status: number | null;
+                last_error: string | null;
+                last_latency_ms: number | null;
+                succeeded_at: string | null;
+                created_at: string;
+            }>;
+        };
+    };
+    readonly events: {
+        list: (q?: Query<"/v1/events", "get">) => Promise<{
+            events: components["schemas"]["Event"][];
+            next: string | null;
+        }>;
+        get: (id: string) => Promise<{
+            id: string;
+            type: string;
+            timestamp: string;
+            sandbox: boolean;
+            data: {
+                [key: string]: unknown;
+            };
+        }>;
+        /** Every event, newest first (the last 30 days). */
+        iterate: (q?: Omit<Query<"/v1/events", "get">, "before" | "after">) => AsyncGenerator<{
+            id: string;
+            type: string;
+            timestamp: string;
+            sandbox: boolean;
+            data: {
+                [key: string]: unknown;
+            };
+        }, any, any>;
+    };
+    readonly auditLog: {
+        list: (q?: Query<"/v1/audit-log", "get">) => Promise<{
+            entries: components["schemas"]["AuditEntry"][];
+            next: number | null;
+        }>;
+        iterate: (q?: Omit<Query<"/v1/audit-log", "get">, "before">) => AsyncGenerator<{
+            id: number;
+            at: string;
+            actor: string;
+            actor_key_id: string | null;
+            ip: string | null;
+            action: string;
+            target_type: string;
+            target_id: string | null;
+            customer: string | null;
+            details: {
+                [key: string]: unknown;
+            } | null;
+        }, any, any>;
+    };
+    readonly customers: {
+        /**
+         * Deletes everything stored for one of your customers (irreversible). Runs in the
+         * background: poll `dataDeletions.get(id)` or `dataDeletions.wait(id)`.
+         */
+        deleteData: (customer: string) => Promise<{
+            id: string;
+            customer: string;
+            status: "pending" | "running" | "completed" | "failed";
+            counts: {
+                [key: string]: number;
+            } | null;
+            created_at: string;
+            completed_at: string | null;
+        }>;
+    };
+    readonly dataDeletions: {
+        get: (id: string) => Promise<{
+            id: string;
+            customer: string;
+            status: "pending" | "running" | "completed" | "failed";
+            counts: {
+                [key: string]: number;
+            } | null;
+            created_at: string;
+            completed_at: string | null;
+        }>;
+        wait: (id: string, opts?: WaitOptions & {
+            intervalMs?: number;
+        }) => Promise<{
+            id: string;
+            customer: string;
+            status: "pending" | "running" | "completed" | "failed";
+            counts: {
+                [key: string]: number;
+            } | null;
+            created_at: string;
+            completed_at: string | null;
+        }>;
+    };
+    /** Checks a webhook delivery's signature and returns the parsed event. Throws if it's not ours. */
+    static verifyWebhook: typeof verifyWebhook;
+}
+export interface AnalyticsQuery {
+    questionId?: string;
+    engines?: EngineId[];
+    days?: number;
+}
+export interface UsageQuery {
+    from?: string;
+    to?: string;
+    groupBy?: Query<"/v1/usage", "get">["group_by"];
+    customer?: string;
+    projectId?: string;
+}