geovouch 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ApiRefusal, RecordActionBody } from "geovouch-schema/api";
+export type { ActionKind, ApiRefusal, EngineScore, Gap, GapsResponse, LiftResponse, ProjectRef, ProjectsResponse, Readiness, RecordActionBody, RecordActionResponse, ScoreboardResponse } from "geovouch-schema/api";
 export type GeoVouchOptions = {
     apiKey: string;
     /** Override for self-hosted or preview deployments. */
@@ -11,7 +13,11 @@ export type GeoVouchOptions = {
 export declare class GeoVouchError extends Error {
     readonly status: number;
     readonly body: unknown;
-    constructor(status: number, message: string, body: unknown);
+    /** The machine-readable refusal, when the server sent one — switch on this, not on `message`. */
+    readonly refused?: ApiRefusal["refused"];
+    constructor(status: number, message: string, body: unknown, 
+    /** The machine-readable refusal, when the server sent one — switch on this, not on `message`. */
+    refused?: ApiRefusal["refused"]);
 }
 export declare class GeoVouch {
     #private;
@@ -24,20 +30,106 @@ export declare class GeoVouch {
             name: string;
             scanEnabled: boolean;
         }[];
-        keyScope: string;
+        keyScope: "project" | "organization";
     }>;
     /** Where you stand, per engine. Never averaged across engines — they diverge by ~46x, so one
      *  blended score is the mean of four different instruments. */
-    scoreboard(): Promise<ScoreboardResponse>;
+    scoreboard(): Promise<{
+        project: {
+            id: string;
+            slug: string;
+            name: string;
+        };
+        readiness: {
+            actionable: boolean;
+            reasons: string[];
+        };
+        engines: ({
+            engine: "gemini" | "chatgpt-search" | "perplexity" | "google-ai-overview";
+            status: "unmeasured";
+            observations: number;
+        } | {
+            engine: "gemini" | "chatgpt-search" | "perplexity" | "google-ai-overview";
+            status: "measured";
+            observations: number;
+            shareOfVoicePct: number | null;
+            presenceRatePct: number;
+            sourcedRatePct: number | null;
+            confidence95: {
+                shareOfVoicePct: {
+                    low: number;
+                    high: number;
+                } | null;
+                presenceRatePct: {
+                    low: number;
+                    high: number;
+                } | null;
+            };
+            lowConfidence: boolean;
+            rivalsNamed: number;
+            topRivals: {
+                label: string;
+                count: number;
+            }[];
+        })[];
+    }>;
     /** The buyer questions you are losing, split by whether the evidence can carry a decision.
      *  `actionable` cleared precision, the 50% boundary and an anytime-valid familywise threshold;
      *  `researchOnly` did not, and acting on it is acting on a draw. */
-    gaps(): Promise<GapsResponse>;
+    gaps(): Promise<{
+        project: {
+            id: string;
+            slug: string;
+            name: string;
+        };
+        readiness: {
+            actionable: boolean;
+            reasons: string[];
+        };
+        actionable: {
+            [x: string]: unknown;
+            question: string;
+            actionable: boolean;
+            missedEngines: string[];
+            wonEngines: string[];
+            competitors: {
+                label: string;
+                count: number;
+            }[];
+            coverage: number;
+            observations: number;
+            provenMissedEngines: string[];
+            researchReasons: string[];
+        }[];
+        researchOnly: {
+            [x: string]: unknown;
+            question: string;
+            actionable: boolean;
+            missedEngines: string[];
+            wonEngines: string[];
+            competitors: {
+                label: string;
+                count: number;
+            }[];
+            coverage: number;
+            observations: number;
+            provenMissedEngines: string[];
+            researchReasons: string[];
+        }[];
+    }>;
     /** What to write for one actionable question. */
-    brief(question: string): Promise<Record<string, unknown>>;
+    brief(question: string): Promise<{
+        [x: string]: unknown;
+        project: {
+            id: string;
+            slug: string;
+            name: string;
+        };
+    }>;
     /** Ranked next-best-actions. An EMPTY list means measured-and-nothing-to-do; it never means the
      *  gate was shut — that arrives as a `collect_more_data` action naming the blocker. */
     recommend(): Promise<{
+        [x: string]: unknown;
         actions: unknown[];
     }>;
     /** TELL US WHAT YOU DID. This is the verb that closes the loop: we never publish on your behalf, so
@@ -45,91 +137,47 @@ export declare class GeoVouch {
      *
      *  `publishedAt` is when the work went LIVE, not when you are reporting it — it is the before/after
      *  pivot, and reporting Friday about a Tuesday page would count three days of "after" as before. */
-    recordAction(input: {
-        question: string;
-        kind: ActionKind;
-        url?: string;
+    recordAction(input: Omit<RecordActionBody, "publishedAt"> & {
         publishedAt: Date | string;
-        note?: string;
     }): Promise<{
-        action: unknown;
+        project: {
+            id: string;
+            slug: string;
+            name: string;
+        };
+        action: {
+            [x: string]: unknown;
+            id: string;
+            question: string;
+            kind: "answer_page" | "page_strengthened" | "structured_data" | "docs_page" | "community_answer" | "third_party_listicle" | "backlink";
+            url: string | null;
+            publishedAt: Date;
+        };
         next: string;
     }>;
     /** Did it work? Control-adjusted, per engine, against a holdout arm nothing ever targets.
      *  `unmeasured` means a window is missing or there is no control — it is not a zero. */
-    lift(): Promise<LiftResponse>;
-}
-export type ActionKind = "answer_page" | "page_strengthened" | "structured_data" | "docs_page" | "community_answer" | "third_party_listicle" | "backlink";
-export type EngineScore = {
-    engine: string;
-    status: "measured" | "unmeasured";
-    observations: number;
-    shareOfVoicePct?: number | null;
-    presenceRatePct?: number | null;
-    /** NULL, never 0, when nothing grounded: an engine that answered without retrieving has told you
-     *  nothing about whether your pages were a source. */
-    sourcedRatePct?: number | null;
-    confidence95?: {
-        shareOfVoicePct: {
-            low: number;
-            high: number;
-        } | null;
-        presenceRatePct: {
-            low: number;
-            high: number;
-        } | null;
-    };
-    lowConfidence?: boolean;
-    rivalsNamed?: number;
-    topRivals?: {
-        label: string;
-        count: number;
-    }[];
-};
-export type Readiness = {
-    actionable: boolean;
-    reasons: string[];
-};
-export type ProjectRef = {
-    id: string;
-    slug: string;
-    name: string;
-};
-export type ScoreboardResponse = {
-    project: ProjectRef;
-    readiness: Readiness;
-    engines: EngineScore[];
-};
-export type GapsResponse = {
-    project: ProjectRef;
-    readiness: Readiness;
-    actionable: Gap[];
-    researchOnly: Gap[];
-};
-export type Gap = {
-    question: string;
-    actionable: boolean;
-    citedRate?: number | null;
-    researchReasons?: string[];
-    competitors?: string[];
-};
-export type LiftResponse = {
-    project: ProjectRef;
-    holdoutArm: string[];
-    assets: {
-        slug: string;
-        question: string;
-        publishedAt: string;
-        /** Non-null means the after-window is not full yet. That resolves with TIME, not more content —
-         *  the distinction between "no effect" and "too early to say". */
-        daysUntilComparable: number | null;
-        engines: {
-            engine: string;
-            status: string;
-            proven: boolean;
-            netCiteLift: number | null;
-            verdict: string;
+    lift(): Promise<{
+        project: {
+            id: string;
+            slug: string;
+            name: string;
+        };
+        holdoutArm: string[];
+        assets: {
+            slug: string;
+            question: string;
+            publishedAt: string;
+            daysUntilComparable: number | null;
+            engines: {
+                [x: string]: unknown;
+                engine: string;
+                status: string;
+                proven: boolean;
+                netCiteLift: number | null;
+                verdict: string;
+            }[];
         }[];
-    }[];
-    guidance: string;
-};
+        guidance: string;
+    }>;
+}

package/dist/index.js

@@ -1,12 +1,32 @@
+// geovouch — the client. You bring an API key; we bring the measurement.
+//
+// THIS PACKAGE DELIBERATELY EXPOSES NO TECHNIQUE. No database, no migrations, no vendor token, no
+// engine list to configure, no statistical parameter to tune. Those are ours, and keeping them ours
+// is what lets the numbers get better without you redeploying — the previous shape of this SDK was a
+// bag of pure functions, which meant every consumer assembled their own instrument and every one of
+// them drifted from ours.
+//
+// What you get instead is the four verbs of a closed loop: where you stand, what to do, a receipt for
+// what you did, and whether it worked.
+import { ActionKind, ApiRefusal, GapsResponse, LiftResponse, ProjectsResponse, RecordActionBody, RecordActionResponse, ScoreboardResponse, } from "geovouch-schema/api";
+import { z } from "zod";
+// Two payloads whose full shape belongs to the recommender, not the wire: loose records, so a richer
+// server never has fields STRIPPED by the client. Parse may reject; it may never rewrite.
+const Brief = z.object({ project: z.object({ id: z.string(), slug: z.string(), name: z.string() }) }).loose();
+const Recommend = z.object({ actions: z.array(z.unknown()) }).loose();
 /** Every failure arrives as this, with the server's own sentence. A thrown string would make callers
  *  parse prose to find out whether to retry. */
 export class GeoVouchError extends Error {
     status;
     body;
-    constructor(status, message, body) {
+    refused;
+    constructor(status, message, body, 
+    /** The machine-readable refusal, when the server sent one — switch on this, not on `message`. */
+    refused) {
         super(message);
         this.status = status;
         this.body = body;
+        this.refused = refused;
         this.name = "GeoVouchError";
     }
 }
@@ -24,7 +44,10 @@ export class GeoVouch {
         this.#project = options.project;
         this.#fetch = options.fetchImpl ?? fetch;
     }
-    async #call(path, init) {
+    /** Every response is PARSED through the shared wire schema, never cast. The server ran the same
+     *  object before answering, so the two ends are incapable of disagreeing about a field — and a drift
+     *  surfaces here as a thrown `GeoVouchError`, not as `undefined` in a customer's dashboard. */
+    async #call(path, schema, init) {
         const url = new URL(`${this.#base}/api/v1/${path}`);
         if (this.#project)
             url.searchParams.set("project", this.#project);
@@ -46,34 +69,41 @@ export class GeoVouch {
             throw new GeoVouchError(res.status, `geovouch: ${res.status} returned a non-JSON body`, text);
         }
         if (!res.ok) {
-            const message = parsed?.error;
-            throw new GeoVouchError(res.status, message || `geovouch: request failed (${res.status})`, parsed);
+            const refusal = ApiRefusal.safeParse(parsed);
+            const message = refusal.success ? refusal.data.error : `geovouch: request failed (${res.status})`;
+            throw new GeoVouchError(res.status, message, parsed, refusal.success ? refusal.data.refused : undefined);
         }
-        return parsed;
+        const checked = schema.safeParse(parsed);
+        if (!checked.success) {
+            // The server answered 200 with a shape this client does not recognise. That is a version skew
+            // between the two ends, and saying so beats returning a partially-undefined object.
+            throw new GeoVouchError(res.status, `geovouch: ${path} answered a shape this client does not understand — upgrade the \`geovouch\` package`, parsed);
+        }
+        return checked.data;
     }
     /** Which projects this key can read. */
     projects() {
-        return this.#call("projects");
+        return this.#call("projects", ProjectsResponse);
     }
     /** Where you stand, per engine. Never averaged across engines — they diverge by ~46x, so one
      *  blended score is the mean of four different instruments. */
     scoreboard() {
-        return this.#call("scoreboard");
+        return this.#call("scoreboard", ScoreboardResponse);
     }
     /** The buyer questions you are losing, split by whether the evidence can carry a decision.
      *  `actionable` cleared precision, the 50% boundary and an anytime-valid familywise threshold;
      *  `researchOnly` did not, and acting on it is acting on a draw. */
     gaps() {
-        return this.#call("gaps");
+        return this.#call("gaps", GapsResponse);
     }
     /** What to write for one actionable question. */
     brief(question) {
-        return this.#call("brief", { query: { question } });
+        return this.#call("brief", Brief, { query: { question } });
     }
     /** Ranked next-best-actions. An EMPTY list means measured-and-nothing-to-do; it never means the
      *  gate was shut — that arrives as a `collect_more_data` action naming the blocker. */
     recommend() {
-        return this.#call("recommend");
+        return this.#call("recommend", Recommend);
     }
     /** TELL US WHAT YOU DID. This is the verb that closes the loop: we never publish on your behalf, so
      *  without a receipt your work is invisible to the step that measures whether it landed.
@@ -81,14 +111,17 @@ export class GeoVouch {
      *  `publishedAt` is when the work went LIVE, not when you are reporting it — it is the before/after
      *  pivot, and reporting Friday about a Tuesday page would count three days of "after" as before. */
     recordAction(input) {
-        return this.#call("actions", {
-            method: "POST",
-            body: { ...input, publishedAt: input.publishedAt instanceof Date ? input.publishedAt.toISOString() : input.publishedAt },
+        // Validated CLIENT-SIDE too, with the same object the server runs: a bad receipt fails here with a
+        // field-keyed error instead of a round trip, and the two validators cannot disagree.
+        const body = RecordActionBody.parse({
+            ...input,
+            publishedAt: input.publishedAt instanceof Date ? input.publishedAt.toISOString() : input.publishedAt,
         });
+        return this.#call("actions", RecordActionResponse, { method: "POST", body });
     }
     /** Did it work? Control-adjusted, per engine, against a holdout arm nothing ever targets.
      *  `unmeasured` means a window is missing or there is no control — it is not a zero. */
     lift() {
-        return this.#call("lift");
+        return this.#call("lift", LiftResponse);
     }
 }

package/package.json

@@ -1,28 +1,44 @@
 {
   "name": "geovouch",
-  "version": "0.2.0",
-  "description": "GeoVouch client — measure whether AI assistants name your brand, know when the evidence can carry a decision, and prove whether what you shipped worked. Bring an API key; the storage, the engines and the statistics are ours.",
+  "version": "0.3.0",
+  "description": "GeoVouch client \u2014 measure whether AI assistants name your brand, know when the evidence can carry a decision, and prove whether what you shipped worked. Bring an API key; the storage, the engines and the statistics are ours.",
   "license": "MIT",
   "type": "module",
   "engines": {
-  "node": ">=20"
-},
-"files": ["dist", "README.md", "LICENSE"],
-"repository": {
-"type": "git",
-"url": "git+https://github.com/theinfluencecompany/geovouch.git",
-"directory": "libs/client"
-},
-"keywords": ["geo", "aeo", "generative-engine-optimization", "ai-search", "share-of-voice", "llm", "brand-visibility"],
-"exports": {
-".": {
-"types": "./dist/index.d.ts",
-"default": "./dist/index.js"
-}
-},
-"scripts": {
-  "typecheck": "tsc -p tsconfig.json --noEmit",
-  "build": "tsc -p tsconfig.build.json",
-  "test": "node --test --experimental-transform-types test/*.test.ts"
-}
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theinfluencecompany/geovouch.git",
+    "directory": "libs/client"
+  },
+  "keywords": [
+    "geo",
+    "aeo",
+    "generative-engine-optimization",
+    "ai-search",
+    "share-of-voice",
+    "llm",
+    "brand-visibility"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test --experimental-transform-types test/*.test.ts"
+  },
+  "dependencies": {
+    "geovouch-schema": "0.1.0",
+    "zod": "^4.5.4"
+  }
 }