@ainyc/canonry 2.10.1 → 2.12.0

package/dist/{chunk-KWQCQMPY.js → chunk-PLI7EOPM.js}

@@ -1540,6 +1540,148 @@ var ccCachedReleaseSchema = z14.object({
   lastUsedAt: z14.string().nullable()
 });
 
+// ../contracts/src/composites.ts
+import { z as z15 } from "zod";
+var searchHitKindSchema = z15.enum(["snapshot", "insight"]);
+var projectSearchSnapshotHitSchema = z15.object({
+  kind: z15.literal("snapshot"),
+  id: z15.string(),
+  runId: z15.string(),
+  keyword: z15.string(),
+  provider: z15.string(),
+  model: z15.string().nullable(),
+  citationState: citationStateSchema,
+  matchedField: z15.enum(["answerText", "citedDomains", "searchQueries", "keyword"]),
+  snippet: z15.string(),
+  createdAt: z15.string()
+});
+var projectSearchInsightHitSchema = z15.object({
+  kind: z15.literal("insight"),
+  id: z15.string(),
+  runId: z15.string().nullable(),
+  type: z15.enum(["regression", "gain", "opportunity"]),
+  severity: z15.enum(["critical", "high", "medium", "low"]),
+  title: z15.string(),
+  keyword: z15.string(),
+  provider: z15.string(),
+  matchedField: z15.enum(["title", "keyword", "recommendation", "cause"]),
+  snippet: z15.string(),
+  dismissed: z15.boolean(),
+  createdAt: z15.string()
+});
+var projectSearchHitSchema = z15.discriminatedUnion("kind", [
+  projectSearchSnapshotHitSchema,
+  projectSearchInsightHitSchema
+]);
+var projectSearchResponseSchema = z15.object({
+  query: z15.string(),
+  totalHits: z15.number().int().nonnegative(),
+  truncated: z15.boolean(),
+  hits: z15.array(projectSearchHitSchema)
+});
+
+// ../contracts/src/content.ts
+import { z as z16 } from "zod";
+var contentActionSchema = z16.enum(["create", "expand", "refresh", "add-schema"]);
+var ContentActions = contentActionSchema.enum;
+var demandSourceSchema = z16.enum(["gsc", "competitor-evidence", "both"]);
+var DemandSources = demandSourceSchema.enum;
+var actionConfidenceSchema = z16.enum(["high", "medium", "low"]);
+var ActionConfidences = actionConfidenceSchema.enum;
+var pageTypeSchema = z16.enum([
+  "blog-post",
+  "comparison",
+  "listicle",
+  "how-to",
+  "guide",
+  "glossary"
+]);
+var PageTypes = pageTypeSchema.enum;
+var contentActionStateSchema = z16.enum([
+  "proposed",
+  "briefed",
+  "payload-generated",
+  "draft-created",
+  "published",
+  "validated",
+  "dismissed"
+]);
+var ContentActionStates = contentActionStateSchema.enum;
+var ourBestPageSchema = z16.object({
+  url: z16.string(),
+  gscImpressions: z16.number().nonnegative(),
+  gscClicks: z16.number().nonnegative(),
+  // Null when the page came from the inventory fallback (no GSC ranking data).
+  gscAvgPosition: z16.number().nonnegative().nullable(),
+  organicSessions: z16.number().nonnegative()
+});
+var winningCompetitorSchema = z16.object({
+  domain: z16.string(),
+  url: z16.string(),
+  title: z16.string(),
+  citationCount: z16.number().int().nonnegative()
+});
+var scoreBreakdownSchema = z16.object({
+  demand: z16.number(),
+  competitor: z16.number(),
+  absence: z16.number(),
+  gapSeverity: z16.number()
+});
+var existingActionRefSchema = z16.object({
+  actionId: z16.string(),
+  state: contentActionStateSchema,
+  lastUpdated: z16.string()
+});
+var contentTargetRowDtoSchema = z16.object({
+  targetRef: z16.string(),
+  query: z16.string(),
+  action: contentActionSchema,
+  ourBestPage: ourBestPageSchema.nullable(),
+  winningCompetitor: winningCompetitorSchema.nullable(),
+  score: z16.number(),
+  scoreBreakdown: scoreBreakdownSchema,
+  drivers: z16.array(z16.string()),
+  demandSource: demandSourceSchema,
+  actionConfidence: actionConfidenceSchema,
+  existingAction: existingActionRefSchema.nullable()
+});
+var contentTargetsResponseDtoSchema = z16.object({
+  targets: z16.array(contentTargetRowDtoSchema),
+  contextMetrics: z16.object({
+    totalAiReferralSessions: z16.number().int().nonnegative(),
+    latestRunId: z16.string(),
+    runTimestamp: z16.string()
+  })
+});
+var contentGroundingSourceSchema = z16.object({
+  uri: z16.string(),
+  title: z16.string(),
+  domain: z16.string(),
+  isOurDomain: z16.boolean(),
+  isCompetitor: z16.boolean(),
+  citationCount: z16.number().int().nonnegative(),
+  providers: z16.array(providerNameSchema)
+});
+var contentSourceRowDtoSchema = z16.object({
+  query: z16.string(),
+  groundingSources: z16.array(contentGroundingSourceSchema)
+});
+var contentSourcesResponseDtoSchema = z16.object({
+  sources: z16.array(contentSourceRowDtoSchema),
+  latestRunId: z16.string()
+});
+var contentGapRowDtoSchema = z16.object({
+  query: z16.string(),
+  competitorDomains: z16.array(z16.string()),
+  competitorCount: z16.number().int().nonnegative(),
+  missRate: z16.number().min(0).max(1),
+  lastSeenInRunId: z16.string()
+});
+var contentGapsResponseDtoSchema = z16.object({
+  gaps: z16.array(contentGapRowDtoSchema),
+  latestRunId: z16.string()
+});
+
 // src/client.ts
 function createApiClient() {
   const config = loadConfig();
@@ -2105,9 +2247,43 @@ var ApiClient = class {
   async dismissInsight(project, id) {
     return this.request("POST", `/projects/${encodeURIComponent(project)}/insights/${encodeURIComponent(id)}/dismiss`);
   }
+  // ── Content ──────────────────────────────────────────────────────────
+  async getContentTargets(project, opts) {
+    const params = new URLSearchParams();
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.includeInProgress) params.set("include-in-progress", "true");
+    const qs = params.toString();
+    return this.request(
+      "GET",
+      `/projects/${encodeURIComponent(project)}/content/targets${qs ? `?${qs}` : ""}`
+    );
+  }
+  async getContentSources(project) {
+    return this.request(
+      "GET",
+      `/projects/${encodeURIComponent(project)}/content/sources`
+    );
+  }
+  async getContentGaps(project) {
+    return this.request(
+      "GET",
+      `/projects/${encodeURIComponent(project)}/content/gaps`
+    );
+  }
   async getHealth(project) {
     return this.request("GET", `/projects/${encodeURIComponent(project)}/health/latest`);
   }
+  async getProjectOverview(project) {
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/overview`);
+  }
+  async searchProject(project, opts) {
+    const params = new URLSearchParams({ q: opts.q });
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    return this.request(
+      "GET",
+      `/projects/${encodeURIComponent(project)}/search?${params.toString()}`
+    );
+  }
   async getHealthHistory(project, limit) {
     const qs = limit ? `?limit=${limit}` : "";
     return this.request("GET", `/projects/${encodeURIComponent(project)}/health/history${qs}`);
@@ -2203,6 +2379,7 @@ export {
   RunStatuses,
   RunKinds,
   RunTriggers,
+  CitationStates,
   runTriggerRequestSchema,
   parseRunError,
   buildRunErrorFromMessages,

package/dist/{chunk-PYHANJ3B.js → chunk-UM6RDSRJ.js}

@@ -1329,6 +1329,328 @@ function analyzeRuns(currentRun, previousRun, allRuns) {
   };
 }
 
+// ../intelligence/src/query-shape.ts
+var TRANSACTIONAL = /\b(buy|price|pricing|cost|cheap|discount|coupon|deal|sale|trial|plan)\b/i;
+var NAVIGATIONAL = /\b(login|sign[- ]?in|contact|support|help|download|app|homepage)\b|\.(com|io|net|org|app|ai)\b/i;
+function isBlogShapedQuery(query) {
+  const trimmed = query.trim();
+  if (!trimmed) return false;
+  if (TRANSACTIONAL.test(trimmed)) return false;
+  if (NAVIGATIONAL.test(trimmed)) return false;
+  return true;
+}
+
+// ../intelligence/src/site-inventory.ts
+var BLOG_SHAPED_PATH_PREFIXES = [
+  "/blog/",
+  "/posts/",
+  "/articles/",
+  "/guides/",
+  "/learn/",
+  "/resources/",
+  "/glossary/"
+];
+function buildInventory(input) {
+  const map = /* @__PURE__ */ new Map();
+  const addPage = (rawUrl, source) => {
+    const path = extractPath(rawUrl);
+    if (!path) return;
+    if (!isBlogShaped(path)) return;
+    let sources = map.get(path);
+    if (!sources) {
+      sources = /* @__PURE__ */ new Set();
+      map.set(path, sources);
+    }
+    sources.add(source);
+  };
+  for (const url of input.gscPages) addPage(url, "gsc");
+  for (const url of input.ga4LandingPages) addPage(url, "ga4");
+  for (const url of input.sitemapUrls) addPage(url, "sitemap");
+  for (const url of input.wpPosts) addPage(url, "wp");
+  return Array.from(map.entries()).map(([url, sources]) => ({
+    url,
+    sources: Array.from(sources)
+  }));
+}
+function extractPath(url) {
+  const trimmed = url.trim();
+  if (!trimmed) return "";
+  const match = /^https?:\/\/[^/]+(.*)$/.exec(trimmed);
+  const path = match ? match[1] : trimmed;
+  const stripped = path.replace(/\/+$/, "");
+  return stripped || "/";
+}
+function isBlogShaped(path) {
+  return BLOG_SHAPED_PATH_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+// ../intelligence/src/content-classifier.ts
+var SEO_STRONG_THRESHOLD = 10;
+var SEO_WEAK_THRESHOLD = 30;
+function classifyContentAction(input) {
+  const { ourPage, ourPageInGroundingSources, ourPageHasSchema } = input;
+  if (!ourPage) return "create";
+  if (ourPageInGroundingSources) {
+    if (ourPageHasSchema === false) return "add-schema";
+    return null;
+  }
+  if (ourPage.position <= SEO_STRONG_THRESHOLD) return "refresh";
+  if (ourPage.position <= SEO_WEAK_THRESHOLD) return "expand";
+  return "create";
+}
+
+// ../intelligence/src/content-scorer.ts
+var SEVERITY_BY_ACTION = {
+  create: 1,
+  "add-schema": 0.7,
+  expand: 0.6,
+  refresh: 0.4
+};
+function scoreContentTarget(input) {
+  const demand = computeDemandComponent(input.gscImpressions, input.aiReferralFactor);
+  const competitor = computeCompetitorComponent(
+    input.competitorCount,
+    input.recentMissRate,
+    input.citationCount
+  );
+  const absence = clamp01(1 - input.ourCitedRate);
+  const gapSeverity = input.action ? SEVERITY_BY_ACTION[input.action] : 0;
+  const score = (demand + competitor) * absence * gapSeverity;
+  return {
+    score,
+    scoreBreakdown: { demand, competitor, absence, gapSeverity },
+    drivers: buildDrivers(input),
+    demandSource: classifyDemandSource(input.gscImpressions, input.competitorCount)
+  };
+}
+function computeDemandComponent(gscImpressions, aiReferralFactor) {
+  const logImpressions = Math.log(Math.max(gscImpressions, 0) + 1);
+  const aiBoost = 1 + Math.max(aiReferralFactor, 0);
+  return logImpressions * aiBoost;
+}
+function computeCompetitorComponent(competitorCount, recentMissRate, citationCount) {
+  if (competitorCount <= 0) return 0;
+  const logCompetitors = Math.log(competitorCount + 1);
+  return logCompetitors * clamp01(recentMissRate) * Math.max(citationCount, 0);
+}
+function classifyDemandSource(gscImpressions, competitorCount) {
+  const hasGsc = gscImpressions > 0;
+  const hasCompetitor = competitorCount > 0;
+  if (hasGsc && hasCompetitor) return "both";
+  if (hasCompetitor) return "competitor-evidence";
+  return "gsc";
+}
+function clamp01(value) {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+function buildDrivers(input) {
+  const drivers = [];
+  if (input.competitorCount > 0) {
+    const noun = input.competitorCount === 1 ? "competitor" : "competitors";
+    drivers.push(`${input.competitorCount} ${noun} cited`);
+  }
+  if (input.gscImpressions > 0) {
+    drivers.push(`${formatImpressions(input.gscImpressions)} GSC impressions`);
+  }
+  if (input.recentMissRate >= 0.5 && input.competitorCount > 0) {
+    const pct = Math.round(clamp01(input.recentMissRate) * 100);
+    drivers.push(`missed in ${pct}% of recent runs`);
+  }
+  if (input.action === "create" && input.position === null) {
+    drivers.push("no existing page");
+  }
+  if (input.position !== null && input.position > 30) {
+    drivers.push(`page ranks #${input.position} (effectively invisible)`);
+  } else if (input.position !== null && input.position > 10) {
+    drivers.push(`page ranks #${input.position}`);
+  }
+  if (input.action === "add-schema") {
+    drivers.push("cited by LLMs but lacks structured data");
+  }
+  return drivers;
+}
+function formatImpressions(impressions) {
+  if (impressions >= 1e3) {
+    return `${Math.round(impressions / 100) / 10}k`;
+  }
+  return String(impressions);
+}
+
+// ../intelligence/src/content-confidence.ts
+var GSC_DENSE_IMPRESSIONS_THRESHOLD = 100;
+var RUN_HISTORY_HIGH_CONFIDENCE_THRESHOLD = 3;
+function calculateActionConfidence(input) {
+  const gscDense = input.hasGsc && input.gscImpressions >= GSC_DENSE_IMPRESSIONS_THRESHOLD;
+  const historyDeep = input.runsOfHistory >= RUN_HISTORY_HIGH_CONFIDENCE_THRESHOLD;
+  if (gscDense && historyDeep) return "high";
+  if (!input.hasGsc && !input.hasInventoryMatch) {
+    return "low";
+  }
+  return "medium";
+}
+
+// ../intelligence/src/content-targets.ts
+function buildContentTargetRows(input) {
+  const rows = [];
+  for (const cq of input.candidateQueries) {
+    const ourPage = resolveOurPage(cq, input.inventory);
+    const ourPageInGroundingSources = cq.ourCitedInLatestRun;
+    const ourPageHasSchema = ourPage ? input.wpSchemaAudit.get(ourPage.url) ?? null : null;
+    const action = classifyContentAction({
+      ourPage,
+      ourPageInGroundingSources,
+      ourPageHasSchema
+    });
+    if (!action) continue;
+    const hasGsc = cq.gscImpressions > 0;
+    const hasCompetitor = cq.competitorDomains.length > 0;
+    if (!hasGsc && !hasCompetitor && !cq.ourCitedInLatestRun) continue;
+    const aiReferralFactor = computeAiReferralFactor(
+      input.totalAiReferralSessions,
+      cq.competitorCitationCount
+    );
+    const scoring = scoreContentTarget({
+      gscImpressions: cq.gscImpressions,
+      aiReferralFactor,
+      competitorCount: cq.competitorDomains.length,
+      recentMissRate: cq.recentMissRate,
+      citationCount: cq.competitorCitationCount,
+      ourCitedRate: cq.ourCitedRate,
+      action,
+      position: ourPage?.position ?? null
+    });
+    const actionConfidence = calculateActionConfidence({
+      hasGsc: cq.gscPage !== null,
+      gscImpressions: cq.gscImpressions,
+      runsOfHistory: cq.runsOfHistory,
+      hasCompetitorEvidence: cq.competitorDomains.length > 0,
+      hasInventoryMatch: ourPage?.source === "inventory"
+    });
+    const targetRef = computeTargetRef({
+      projectId: input.projectId,
+      query: cq.query,
+      action,
+      targetPage: ourPage?.url ?? null
+    });
+    const winningCompetitor = pickTopCompetitor(cq.competitorGroundingUrls);
+    const ourBestPage = ourPage ? {
+      url: ourPage.url,
+      gscImpressions: cq.gscImpressions,
+      gscClicks: cq.gscClicks,
+      gscAvgPosition: cq.gscPosition,
+      organicSessions: input.gaTrafficByPage.get(ourPage.url) ?? 0
+    } : null;
+    rows.push({
+      targetRef,
+      query: cq.query,
+      action,
+      ourBestPage,
+      winningCompetitor,
+      score: scoring.score,
+      scoreBreakdown: scoring.scoreBreakdown,
+      drivers: scoring.drivers,
+      demandSource: scoring.demandSource,
+      actionConfidence,
+      existingAction: input.inProgressActions.get(targetRef) ?? null
+    });
+  }
+  return rows.sort((a, b) => b.score - a.score);
+}
+function buildContentSourceRows(input) {
+  return input.candidateQueries.map((cq) => ({
+    query: cq.query,
+    groundingSources: [
+      ...cq.ourGroundingUrls.map((g) => ({
+        uri: g.uri,
+        title: g.title,
+        domain: g.domain,
+        isOurDomain: true,
+        isCompetitor: false,
+        citationCount: g.citationCount,
+        providers: g.providers
+      })),
+      ...cq.competitorGroundingUrls.map((g) => ({
+        uri: g.uri,
+        title: g.title,
+        domain: g.domain,
+        isOurDomain: false,
+        isCompetitor: true,
+        citationCount: g.citationCount,
+        providers: g.providers
+      }))
+    ]
+  }));
+}
+function buildContentGapRows(input) {
+  const gaps = [];
+  for (const cq of input.candidateQueries) {
+    if (cq.competitorDomains.length === 0) continue;
+    if (cq.ourCitedRate >= 1) continue;
+    gaps.push({
+      query: cq.query,
+      competitorDomains: cq.competitorDomains,
+      competitorCount: cq.competitorDomains.length,
+      missRate: clamp012(cq.recentMissRate),
+      lastSeenInRunId: input.latestRunId
+    });
+  }
+  return gaps.sort((a, b) => {
+    if (b.missRate !== a.missRate) return b.missRate - a.missRate;
+    return b.competitorCount - a.competitorCount;
+  });
+}
+function resolveOurPage(cq, inventory) {
+  if (cq.gscPage && cq.gscPosition !== null) {
+    return { url: cq.gscPage, position: cq.gscPosition, source: "gsc" };
+  }
+  for (const page of inventory) {
+    if (slugMatchesQuery(page.url, cq.query)) {
+      return { url: page.url, position: 100, source: "inventory" };
+    }
+  }
+  return null;
+}
+function slugMatchesQuery(url, query) {
+  const slug = url.toLowerCase();
+  const queryAsSlug = query.toLowerCase().trim().replace(/\s+/g, "-");
+  if (slug.includes(queryAsSlug)) return true;
+  const queryTokens = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+  const slugTokens = new Set(slug.split(/[/\s\-_.]+/));
+  const overlap = queryTokens.filter((t) => slugTokens.has(t)).length;
+  return overlap >= 2;
+}
+function computeAiReferralFactor(totalAiReferralSessions, competitorCount) {
+  if (totalAiReferralSessions <= 0) return 0;
+  const baseline = Math.min(totalAiReferralSessions / 1e3, 0.5);
+  const competitorBoost = competitorCount > 0 ? 0.1 : 0;
+  return Math.min(baseline + competitorBoost, 1);
+}
+function pickTopCompetitor(competitors2) {
+  if (competitors2.length === 0) return null;
+  const top = [...competitors2].sort((a, b) => b.citationCount - a.citationCount)[0];
+  return {
+    domain: top.domain,
+    url: top.uri,
+    title: top.title,
+    citationCount: top.citationCount
+  };
+}
+function computeTargetRef(input) {
+  const key = [input.projectId, input.query, input.action, input.targetPage ?? ""].join("|");
+  let hash = 0;
+  for (let i = 0; i < key.length; i++) {
+    hash = (hash << 5) - hash + key.charCodeAt(i) | 0;
+  }
+  return `tgt_${(hash >>> 0).toString(36)}`;
+}
+function clamp012(value) {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
 // src/intelligence-service.ts
 import crypto from "crypto";
 
@@ -1589,6 +1911,11 @@ export {
   extractLegacyCredentials,
   dropLegacyCredentialColumns,
   migrate,
+  isBlogShapedQuery,
+  buildInventory,
+  buildContentTargetRows,
+  buildContentSourceRows,
+  buildContentGapRows,
   createLogger,
   IntelligenceService
 };