@aivisibilityskill/sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aivisibilityskill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @aivisibilityskill/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official TypeScript client for the [aivisibilityskill](https://aivisibilityskill.com) API. Ask ChatGPT, Gemini, Google AI Overviews and AI Mode, Perplexity, Claude and Grok about any brand, in any country, and get back what they said, who they cited and what to fix.
+
+- Fully typed from the API's OpenAPI document.
+- Safe retries: every check carries an idempotency key, so a retry is never charged twice.
+- Webhook signature verification included.
+- No dependencies. Works in Node 20+, Deno, Bun and Cloudflare Workers (call it from your server: the API is for server-side use).
+
+```sh
+npm install @aivisibilityskill/sdk
+```
+
+## Quick start
+
+```ts
+import { Aiv } from "@aivisibilityskill/sdk";
+
+const aiv = new Aiv({ apiKey: process.env.AIV_KEY! }); // aiv_live_… or aiv_test_… (free sample data)
+
+const job = await aiv.checks.create({
+  questions: ["best invoicing app for freelancers"],
+  engines: ["chatgpt", "gemini", "ai_overview", "perplexity"],
+  locale: "en-US",
+});
+const done = await aiv.jobs.wait(job.id);
+for (const answer of done.answers ?? []) {
+  console.log(
+    answer.engine,
+    answer.brands?.map((b) => b.name),
+  );
+}
+```
+
+Get a key at [app.aivisibilityskill.com](https://app.aivisibilityskill.com). Test keys (`aiv_test_…`) are free and return sample answers, so you can build without spending credits.
+
+## Building for your own customers
+
+Tag work with your customer's id, lock keys to one customer, and bill from the usage report:
+
+```ts
+await aiv.checks.create({ questions, customer: "cus_8421", metadata: { workspace: "acme" } });
+
+const key = await aiv.keys.create({
+  name: "acme",
+  customer: "cus_8421",
+  allowed_ips: ["203.0.113.0/24"],
+});
+
+const csv = await aiv.usage.csv({ from: "2026-11-01", to: "2026-11-30", groupBy: "customer" });
+
+// Everything stored for a customer, deleted (runs in the background):
+const deletion = await aiv.customers.deleteData("cus_8421");
+await aiv.dataDeletions.wait(deletion.id);
+```
+
+## Thousands of answers at once
+
+```ts
+const batch = await aiv.batches.create({
+  questions: myTwoThousandQuestions,
+  engines: ["chatgpt", "ai_overviews"],
+  mode: "batch", // cheapest
+  max_age_hours: 24, // reuse answers from the last day at half price
+});
+const done = await aiv.batches.wait(batch.id); // or listen for the batch.completed webhook
+for (const jobId of done.checks) {
+  const job = await aiv.jobs.get(jobId);
+}
+```
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from "@aivisibilityskill/sdk";
+
+// Pass the raw body (before JSON parsing) and the request headers.
+const event = await verifyWebhook(rawBody, request.headers, process.env.AIV_WEBHOOK_SECRET!);
+if (event.type === "check.completed") {
+  const job = await aiv.jobs.get(event.data.id as string);
+}
+```
+
+During a secret rotation, pass both secrets: `verifyWebhook(body, headers, [newSecret, oldSecret])`. Deliveries older than 5 minutes are refused as replays.
+
+## Lists
+
+Lists are paged. `iterate()` follows the pages for you:
+
+```ts
+for await (const job of aiv.jobs.iterate({ customer: "cus_8421" })) { … }
+for await (const event of aiv.events.iterate({ type: "check.failed" })) { … }
+for await (const entry of aiv.auditLog.iterate()) { … }
+```
+
+## Errors
+
+Every failure throws `AivError` with the HTTP `status`, a stable `code` (`insufficient_credits`, `budget_exceeded`, `rate_limited`, …), a readable `detail` and the `requestId` to quote to support.
+
+```ts
+import { AivError } from "@aivisibilityskill/sdk";
+try {
+  await aiv.checks.create({ questions });
+} catch (err) {
+  if (err instanceof AivError && err.code === "insufficient_credits") { … }
+}
+```
+
+GET requests and checks are retried on 429, 502, 503, 504 and network errors (twice by default, honouring `Retry-After`). Set `maxRetries` and `timeoutMs` in the constructor.
+
+## Everything else
+
+`aiv.projects` (tracking, schedules, visibility, competitors, sources, facts, history), `aiv.opportunities` and `aiv.fixes` (what to fix and proof it worked), `aiv.actions`, `aiv.webhooks`, `aiv.events`, `aiv.keys`, `aiv.account`, `aiv.locales`, `aiv.pricing()` and `aiv.estimate()`. For anything not wrapped yet: `aiv.request("GET", "/v1/…")`.
+
+API reference: [api.aivisibilityskill.com/docs](https://api.aivisibilityskill.com/docs). Support: support@aivisibilityskill.com.
+
+MIT licensed.