@ainyc/canonry 4.115.1 → 4.117.0

package/dist/{chunk-CW4JISBL.js → chunk-PJATAPZW.js}

@@ -25,7 +25,7 @@ import {
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema
-} from "./chunk-6LOKMEL3.js";
+} from "./chunk-IAJ5TQ4S.js";
 
 // src/config.ts
 import fs from "fs";
@@ -1578,6 +1578,18 @@ var getApiV1ProjectsByNameVisibilityStats = (options) => {
     ...options
   });
 };
+var getApiV1ProjectsByNameVisibilityCompare = (options) => {
+  return (options.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/v1/projects/{name}/visibility-compare",
+    ...options
+  });
+};
 var getApiV1ProjectsByNameSnapshotsDiff = (options) => {
   return (options.client ?? client).get({
     security: [
@@ -5171,6 +5183,15 @@ var ApiClient = class {
       })
     );
   }
+  async getVisibilityCompare(project, from, to) {
+    return this.invoke(
+      () => getApiV1ProjectsByNameVisibilityCompare({
+        client: this.heyClient,
+        path: { name: project },
+        query: { from, to }
+      })
+    );
+  }
   // ── Backlinks — workspace-level ────────────────────────────────────────
   async backlinksStatus() {
     return this.invoke(() => getApiV1BacklinksStatus({ client: this.heyClient }));
@@ -5915,6 +5936,21 @@ var canonryMcpTools = [
       shareOfVoice: input.shareOfVoice
     })
   }),
+  defineTool({
+    name: "canonry_visibility_compare",
+    title: "Compare AEO visibility month over month",
+    description: "Statistically honest month-over-month AEO comparison in ONE call \u2014 use this instead of hand-computing deltas from two visibility-stats calls. Share of voice (`mention-share-of-voice`, `driftRobust: true`) is less exposed to broad model-wide naming propensity than absolute rates, but it never overrides model continuity. The response restricts to common query/provider pairs, then includes only providers with exactly one known, identical configured model id in both months. `continuity` surfaces every provider, its model evidence, and whether it was excluded for a changed, mixed mid-month, or unknown model. When no provider remains, metrics return `model-discontinuous` or `model-unknown`, never a directional call. A silent upstream version bump under an unchanged configured id remains undetectable. `from` must be a month strictly before `to`.",
+    access: "read",
+    tier: "monitoring",
+    inputSchema: z2.object({
+      project: projectNameSchema,
+      from: z2.string().describe('Earlier calendar month (YYYY-MM), the baseline. Must be strictly before "to".'),
+      to: z2.string().describe('Later calendar month (YYYY-MM), compared against "from".')
+    }),
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/visibility-compare"],
+    handler: (client2, input) => client2.getVisibilityCompare(input.project, input.from, input.to)
+  }),
   defineTool({
     name: "canonry_content_targets",
     title: "Get content targets",

package/dist/{chunk-B2SNXXAJ.js → chunk-ZZEA774R.js}

@@ -10,7 +10,7 @@ import {
   loadConfig,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-CW4JISBL.js";
+} from "./chunk-PJATAPZW.js";
 import {
   CC_CACHE_DIR,
   DUCKDB_SPEC,
@@ -115,7 +115,7 @@ import {
   siteAuditPages,
   siteAuditSnapshots,
   usageCounters
-} from "./chunk-Z3OGDQHB.js";
+} from "./chunk-FVVKNMZW.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -178,7 +178,7 @@ import {
   validationError,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-6LOKMEL3.js";
+} from "./chunk-IAJ5TQ4S.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -6515,7 +6515,7 @@ function readStoredGroundingSources(rawResponse) {
   return result;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-4AWB2V7U.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-J7G4CMI5.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);

package/dist/cli.js

@@ -29,7 +29,7 @@ import {
   setTelemetrySource,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-B2SNXXAJ.js";
+} from "./chunk-ZZEA774R.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -46,7 +46,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-CW4JISBL.js";
+} from "./chunk-PJATAPZW.js";
 import {
   apiKeys,
   createClient,
@@ -54,7 +54,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-Z3OGDQHB.js";
+} from "./chunk-FVVKNMZW.js";
 import {
   BacklinkSources,
   CcReleaseSyncStatuses,
@@ -80,7 +80,7 @@ import {
   providerQuotaPolicySchema,
   resolveProviderInput,
   winnabilityClassSchema
-} from "./chunk-6LOKMEL3.js";
+} from "./chunk-IAJ5TQ4S.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -4698,7 +4698,8 @@ function formatEventLine(event) {
         event.evidenceType,
         event.sourceDomain,
         event.landingPathNormalized,
-        `${event.hits} hits`
+        `${event.hits} hits`,
+        `(paid ${event.paidHits} \xB7 organic ${event.organicHits} \xB7 unclassified ${event.unknownHits})`
       ].join("  ");
   }
 }
@@ -4743,6 +4744,9 @@ async function trafficEvents(project, opts) {
   console.log(`  Crawler hits total (window):   ${result.totals.crawlerHits}`);
   console.log(`  AI user-fetch hits (window):   ${result.totals.aiUserFetchHits}`);
   console.log(`  AI referral sessions (window): ${result.totals.aiReferralHits}`);
+  console.log(`    paid:                       ${result.totals.aiReferralPaidHits}`);
+  console.log(`    organic:                    ${result.totals.aiReferralOrganicHits}`);
+  console.log(`    unclassified:               ${result.totals.aiReferralUnknownHits}  (ingested before paid/organic classification)`);
   console.log("");
   if (result.events.length === 0) {
     console.log("No events in this window.");
@@ -11837,6 +11841,78 @@ async function showVisibilityStats(project, opts) {
 function pct3(rate) {
   return rate === null ? "\u2014" : formatRatio(rate);
 }
+async function showVisibilityCompare(project, opts) {
+  if (!opts.from || !opts.to) throw new Error("visibility-compare requires --from <YYYY-MM> and --to <YYYY-MM>");
+  const client = createApiClient();
+  const data = await client.getVisibilityCompare(project, opts.from, opts.to);
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  printVisibilityCompare(data);
+}
+function periodCell(p) {
+  if (p.point === null || p.ciLow === null || p.ciHigh === null) return "no data";
+  const p1 = (v) => formatRatio(v);
+  return `${p1(p.point)} [${p1(p.ciLow)}, ${p1(p.ciHigh)}]`;
+}
+function verdictCell(m) {
+  switch (m.verdict) {
+    case "within-noise":
+      return "within noise";
+    case "insufficient-data":
+      return "no data";
+    case "moved":
+      return `moved ${m.direction === "down" ? "down" : m.direction === "up" ? "up" : ""}`.trim();
+    case "model-discontinuous":
+      return "model discontinuity";
+    case "model-unknown":
+      return "model unknown";
+  }
+}
+function printVisibilityCompare(data) {
+  console.log(`AEO month over month: ${data.project}   ${data.from.month} -> ${data.to.month}`);
+  const b = data.basket;
+  const excl = [];
+  if (b.excludedFromOnly > 0) excl.push(`${b.excludedFromOnly} only in ${data.from.month}`);
+  if (b.excludedToOnly > 0) excl.push(`${b.excludedToOnly} only in ${data.to.month}`);
+  if (b.excludedProviders.length > 0) excl.push(`engines dropped: ${b.excludedProviders.join(", ")}`);
+  console.log(`Basket: ${b.queryCount} quer${b.queryCount === 1 ? "y" : "ies"}, ${b.providers.length} engine(s)${excl.length ? ` (excluded: ${excl.join("; ")})` : ""}`);
+  const sweeps = `Sweeps: ${data.from.month} ${data.from.runCount}, ${data.to.month} ${data.to.runCount}`;
+  const low = data.from.lowRunCount || data.to.lowRunCount;
+  console.log(low ? `${sweeps}  (below the 5-sweep floor \u2014 intervals are wide, a "moved" verdict is unlikely to be reachable)` : sweeps);
+  if (data.continuity.status !== "comparable") {
+    console.log(`Continuity: ${data.continuity.status.replace("-", " ")} \u2014 no directional call is made.`);
+  }
+  console.log("");
+  const rows = data.metrics.map((m) => ({
+    label: `${m.label}${m.driftRobust ? " *" : ""}`,
+    to: periodCell(m.to),
+    from: periodCell(m.from),
+    verdict: verdictCell(m)
+  }));
+  rows.push({
+    label: "Queries named (count)",
+    to: `${data.queriesMentioned.to.count} of ${data.queriesMentioned.to.of}`,
+    from: `${data.queriesMentioned.from.count} of ${data.queriesMentioned.from.of}`,
+    verdict: ""
+  });
+  const w = (sel, head) => Math.max(head.length, ...rows.map((r) => sel(r).length));
+  const lw = w((r) => r.label, "Metric");
+  const tw = w((r) => r.to, data.to.month);
+  const fw = w((r) => r.from, data.from.month);
+  console.log(`  ${"Metric".padEnd(lw)}  ${data.to.month.padEnd(tw)}  ${data.from.month.padEnd(fw)}  Verdict`);
+  for (const r of rows) {
+    console.log(`  ${r.label.padEnd(lw)}  ${r.to.padEnd(tw)}  ${r.from.padEnd(fw)}  ${r.verdict}`);
+  }
+  console.log("");
+  console.log("  * share of voice is less exposed to broad model-wide naming propensity; model continuity is still required.");
+  for (const provider of data.continuity.providers) {
+    if (provider.status !== "included") {
+      console.log(`  Excluded for model continuity: ${provider.provider} (${provider.fromModels.join("/") || "?"} -> ${provider.toModels.join("/") || "?"}; ${provider.status.replace("-", " ")})`);
+    }
+  }
+}
 function citedCell(c) {
   return `${c.cited}/${c.total}`;
 }
@@ -11928,6 +12004,7 @@ function printVisibilityStats(data) {
 
 // src/cli-commands/visibility-stats.ts
 var USAGE4 = "canonry visibility-stats <project> [--since <iso>] [--until <iso>] [--month <YYYY-MM>] [--last-runs <n>] [--by-provider] [--share-of-voice] [--format json|jsonl]";
+var COMPARE_USAGE = "canonry visibility-compare <project> --from <YYYY-MM> --to <YYYY-MM> [--format json]";
 var VISIBILITY_STATS_CLI_COMMANDS = [
   {
     path: ["visibility-stats"],
@@ -11956,6 +12033,22 @@ var VISIBILITY_STATS_CLI_COMMANDS = [
         format: input.format
       });
     }
+  },
+  {
+    path: ["visibility-compare"],
+    usage: COMPARE_USAGE,
+    options: {
+      from: stringOption(),
+      to: stringOption()
+    },
+    run: async (input) => {
+      const project = requireProject(input, "visibility-compare", COMPARE_USAGE);
+      await showVisibilityCompare(project, {
+        from: getString(input.values, "from"),
+        to: getString(input.values, "to"),
+        format: input.format
+      });
+    }
   }
 ];
 

package/dist/index.js

@@ -1,11 +1,11 @@
 import {
   createServer
-} from "./chunk-B2SNXXAJ.js";
+} from "./chunk-ZZEA774R.js";
 import {
   loadConfig
-} from "./chunk-CW4JISBL.js";
-import "./chunk-Z3OGDQHB.js";
-import "./chunk-6LOKMEL3.js";
+} from "./chunk-PJATAPZW.js";
+import "./chunk-FVVKNMZW.js";
+import "./chunk-IAJ5TQ4S.js";
 export {
   createServer,
   loadConfig

package/dist/{intelligence-service-4AWB2V7U.js → intelligence-service-J7G4CMI5.js}

@@ -1,7 +1,7 @@
 import {
   IntelligenceService
-} from "./chunk-Z3OGDQHB.js";
-import "./chunk-6LOKMEL3.js";
+} from "./chunk-FVVKNMZW.js";
+import "./chunk-IAJ5TQ4S.js";
 export {
   IntelligenceService
 };

package/dist/mcp.js

@@ -3,10 +3,10 @@ import {
   PACKAGE_VERSION,
   canonryMcpTools,
   createApiClient
-} from "./chunk-CW4JISBL.js";
+} from "./chunk-PJATAPZW.js";
 import {
   isReadOnlyKey
-} from "./chunk-6LOKMEL3.js";
+} from "./chunk-IAJ5TQ4S.js";
 
 // src/mcp/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "4.115.1",
+  "version": "4.117.0",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -66,22 +66,22 @@
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "@ainyc/canonry-api-client": "0.0.0",
+    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
     "@ainyc/canonry-contracts": "0.0.0",
-    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
-    "@ainyc/canonry-integration-cloud-run": "0.0.0",
+    "@ainyc/canonry-integration-openai-ads": "0.0.0",
     "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-integration-cloud-run": "0.0.0",
     "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-integration-openai-ads": "0.0.0",
     "@ainyc/canonry-integration-google-business-profile": "0.0.0",
     "@ainyc/canonry-integration-google-places": "0.0.0",
     "@ainyc/canonry-integration-traffic": "0.0.0",
+    "@ainyc/canonry-integration-wordpress": "0.0.0",
+    "@ainyc/canonry-provider-cdp": "0.0.0",
     "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-provider-claude": "0.0.0",
-    "@ainyc/canonry-provider-cdp": "0.0.0",
-    "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-provider-gemini": "0.0.0",
     "@ainyc/canonry-provider-openai": "0.0.0",
     "@ainyc/canonry-provider-perplexity": "0.0.0",