@aivisibilityskill/sdk 0.0.0-stage → 1.0.0

package/dist/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,24 @@
+import type { components } from "./schema.js";
+/**
+ * Verifies a webhook delivery (Standard Webhooks: https://www.standardwebhooks.com).
+ *
+ *   // Express: app.post("/hooks", express.text({ type: "*\/*" }), async (req, res) => { … })
+ *   const event = await verifyWebhook(rawBody, req.headers, process.env.AIV_WEBHOOK_SECRET!);
+ *   if (event.type === "check.completed") …
+ *
+ * Pass the body exactly as received (a string, before any JSON parsing) and the request's
+ * headers. During a secret rotation, pass both secrets. Throws WebhookVerificationError for a
+ * bad signature, a missing header, or a timestamp more than 5 minutes off (a replay).
+ */
+type Event = components["schemas"]["Event"];
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+};
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+export declare function verifyWebhook(body: string | Uint8Array | ArrayBuffer, headers: WebhookHeaders, secret: string | readonly string[], opts?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<Event>;
+export {};

package/dist/webhooks.js

@@ -0,0 +1,91 @@
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+const TOLERANCE_SECONDS = 300;
+const encoder = new TextEncoder();
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name);
+    const record = headers;
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+    const value = key === undefined ? undefined : record[key];
+    return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+}
+function fromBase64(text) {
+    const binary = atob(text);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+async function verifiesWith(secret, signed, signatures) {
+    const raw = secret.startsWith("whsec_") ? secret.slice(6) : secret;
+    let bytes;
+    try {
+        bytes = fromBase64(raw);
+    }
+    catch {
+        bytes = new Uint8Array();
+    }
+    // An empty or tiny key would let anyone forge a signature.
+    if (bytes.length < 16) {
+        throw new WebhookVerificationError("That webhook secret isn't valid (expected whsec_…).");
+    }
+    let key;
+    try {
+        key = await crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+    }
+    catch {
+        throw new WebhookVerificationError("That webhook secret isn't valid (expected whsec_…).");
+    }
+    for (const part of signatures) {
+        const [version, value] = part.split(",");
+        if (version !== "v1" || !value)
+            continue;
+        let given;
+        try {
+            given = fromBase64(value);
+        }
+        catch {
+            continue;
+        }
+        // WebCrypto compares in constant time.
+        if (await crypto.subtle.verify("HMAC", key, given, signed))
+            return true;
+    }
+    return false;
+}
+export async function verifyWebhook(body, headers, secret, opts = {}) {
+    const text = typeof body === "string"
+        ? body
+        : new TextDecoder().decode(body instanceof Uint8Array ? body : new Uint8Array(body));
+    const id = header(headers, "webhook-id");
+    const timestamp = header(headers, "webhook-timestamp");
+    const signature = header(headers, "webhook-signature");
+    if (!id || !timestamp || !signature) {
+        throw new WebhookVerificationError("Missing webhook-id, webhook-timestamp or webhook-signature header.");
+    }
+    if (!/^\d+$/.test(timestamp))
+        throw new WebhookVerificationError("Bad webhook-timestamp.");
+    const now = (opts.now ?? Date.now()) / 1000;
+    if (Math.abs(now - Number(timestamp)) > (opts.toleranceSeconds ?? TOLERANCE_SECONDS)) {
+        throw new WebhookVerificationError("Timestamp too old or in the future (possible replay).");
+    }
+    const signed = encoder.encode(`${id}.${timestamp}.${text}`);
+    const parts = signature.split(" ").filter(Boolean);
+    const secrets = typeof secret === "string" ? [secret] : secret;
+    for (const s of secrets) {
+        if (await verifiesWith(s, signed, parts)) {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new WebhookVerificationError("The body isn't JSON.");
+            }
+        }
+    }
+    throw new WebhookVerificationError("No signature matches this secret.");
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@aivisibilityskill/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Official TypeScript client for the aivisibilityskill API: see how ChatGPT, Gemini, AI Overviews, Perplexity, Claude and Grok answer about any brand.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://aivisibilityskill.com/sdk",
+  "bugs": {
+    "email": "support@aivisibilityskill.com"
+  },
+  "keywords": [
+    "ai visibility",
+    "geo",
+    "generative engine optimization",
+    "chatgpt",
+    "ai overviews",
+    "llm",
+    "sdk",
+    "api"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "openapi-typescript": "7.13.0",
+    "tsx": "4.23.15"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "generate": "tsx scripts/generate.ts",
+    "check-generated": "tsx scripts/generate.ts --check"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js"
 }