@ainyc/canonry 2.9.0 → 2.10.3

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
 };

package/dist/{chunk-FPZUQADO.js → chunk-Z3BWDCBJ.js}

@@ -376,6 +376,18 @@ var runTriggerRequestSchema = z2.object({
   (data) => Number(Boolean(data.location)) + Number(Boolean(data.allLocations)) + Number(Boolean(data.noLocation)) <= 1,
   { message: 'Only one of "location", "allLocations", or "noLocation" may be provided' }
 );
+var runProviderErrorSchema = z2.object({
+  /** Human-readable error message (best-effort extracted from `raw.error.message` / `raw.message`, otherwise the raw text with any `[provider-X]` prefix stripped). */
+  message: z2.string(),
+  /** Original provider response payload, if the underlying error body parsed as JSON. Use this for structured fields like HTTP status, error code, etc. */
+  raw: z2.unknown().optional()
+});
+var runErrorSchema = z2.object({
+  /** Top-level message for runs that failed without a per-provider error (e.g. user cancellation, internal scheduling failures). */
+  message: z2.string().optional(),
+  /** Per-provider errors for visibility-sweep runs that had at least one provider fail. */
+  providers: z2.record(z2.string(), runProviderErrorSchema).optional()
+});
 var runDtoSchema = z2.object({
   id: z2.string(),
   projectId: z2.string(),
@@ -385,9 +397,70 @@ var runDtoSchema = z2.object({
   location: z2.string().nullable().optional(),
   startedAt: z2.string().nullable().optional(),
   finishedAt: z2.string().nullable().optional(),
-  error: z2.string().nullable().optional(),
+  error: runErrorSchema.nullable().optional(),
   createdAt: z2.string()
 });
+var PROVIDER_PREFIX = /^\[provider-[a-zA-Z0-9_-]+\]\s+/;
+function parseProviderErrorMessage(msg) {
+  const stripped = msg.replace(PROVIDER_PREFIX, "");
+  try {
+    const raw = JSON.parse(stripped);
+    if (raw && typeof raw === "object") {
+      const inner = raw;
+      const fromErrorMessage = typeof inner.error?.message === "string" ? inner.error.message : void 0;
+      const fromMessage = typeof inner.message === "string" ? inner.message : void 0;
+      return { message: fromErrorMessage ?? fromMessage ?? stripped, raw };
+    }
+  } catch {
+  }
+  return { message: stripped };
+}
+function parseRunError(raw) {
+  if (!raw) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { message: raw };
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return { message: raw };
+  }
+  const obj = parsed;
+  const hasProviders = obj.providers && typeof obj.providers === "object";
+  const hasMessage = typeof obj.message === "string";
+  if (hasProviders || hasMessage) {
+    return parsed;
+  }
+  const providers = {};
+  for (const [name, val] of Object.entries(obj)) {
+    providers[name] = parseProviderErrorMessage(typeof val === "string" ? val : JSON.stringify(val));
+  }
+  return { providers };
+}
+function buildRunErrorFromMessages(messages) {
+  const providers = {};
+  for (const [name, msg] of messages) {
+    providers[name] = parseProviderErrorMessage(msg);
+  }
+  return { providers };
+}
+function serializeRunError(err) {
+  return JSON.stringify(err);
+}
+function formatRunErrorOneLine(err) {
+  if (err.providers) {
+    const entries = Object.entries(err.providers);
+    if (entries.length === 1) {
+      const [provider, detail] = entries[0];
+      return `${provider}: ${detail.message}`;
+    }
+    if (entries.length > 1) {
+      return entries.map(([p, d]) => `${p}: ${d.message}`).join(" \u2022 ");
+    }
+  }
+  return err.message ?? "Run failed.";
+}
 var groundingSourceSchema = z2.object({
   uri: z2.string(),
   title: z2.string()
@@ -1467,6 +1540,108 @@ var ccCachedReleaseSchema = z14.object({
   lastUsedAt: z14.string().nullable()
 });
 
+// ../contracts/src/content.ts
+import { z as z15 } from "zod";
+var contentActionSchema = z15.enum(["create", "expand", "refresh", "add-schema"]);
+var ContentActions = contentActionSchema.enum;
+var demandSourceSchema = z15.enum(["gsc", "competitor-evidence", "both"]);
+var DemandSources = demandSourceSchema.enum;
+var actionConfidenceSchema = z15.enum(["high", "medium", "low"]);
+var ActionConfidences = actionConfidenceSchema.enum;
+var pageTypeSchema = z15.enum([
+  "blog-post",
+  "comparison",
+  "listicle",
+  "how-to",
+  "guide",
+  "glossary"
+]);
+var PageTypes = pageTypeSchema.enum;
+var contentActionStateSchema = z15.enum([
+  "proposed",
+  "briefed",
+  "payload-generated",
+  "draft-created",
+  "published",
+  "validated",
+  "dismissed"
+]);
+var ContentActionStates = contentActionStateSchema.enum;
+var ourBestPageSchema = z15.object({
+  url: z15.string(),
+  gscImpressions: z15.number().nonnegative(),
+  gscClicks: z15.number().nonnegative(),
+  // Null when the page came from the inventory fallback (no GSC ranking data).
+  gscAvgPosition: z15.number().nonnegative().nullable(),
+  organicSessions: z15.number().nonnegative()
+});
+var winningCompetitorSchema = z15.object({
+  domain: z15.string(),
+  url: z15.string(),
+  title: z15.string(),
+  citationCount: z15.number().int().nonnegative()
+});
+var scoreBreakdownSchema = z15.object({
+  demand: z15.number(),
+  competitor: z15.number(),
+  absence: z15.number(),
+  gapSeverity: z15.number()
+});
+var existingActionRefSchema = z15.object({
+  actionId: z15.string(),
+  state: contentActionStateSchema,
+  lastUpdated: z15.string()
+});
+var contentTargetRowDtoSchema = z15.object({
+  targetRef: z15.string(),
+  query: z15.string(),
+  action: contentActionSchema,
+  ourBestPage: ourBestPageSchema.nullable(),
+  winningCompetitor: winningCompetitorSchema.nullable(),
+  score: z15.number(),
+  scoreBreakdown: scoreBreakdownSchema,
+  drivers: z15.array(z15.string()),
+  demandSource: demandSourceSchema,
+  actionConfidence: actionConfidenceSchema,
+  existingAction: existingActionRefSchema.nullable()
+});
+var contentTargetsResponseDtoSchema = z15.object({
+  targets: z15.array(contentTargetRowDtoSchema),
+  contextMetrics: z15.object({
+    totalAiReferralSessions: z15.number().int().nonnegative(),
+    latestRunId: z15.string(),
+    runTimestamp: z15.string()
+  })
+});
+var contentGroundingSourceSchema = z15.object({
+  uri: z15.string(),
+  title: z15.string(),
+  domain: z15.string(),
+  isOurDomain: z15.boolean(),
+  isCompetitor: z15.boolean(),
+  citationCount: z15.number().int().nonnegative(),
+  providers: z15.array(providerNameSchema)
+});
+var contentSourceRowDtoSchema = z15.object({
+  query: z15.string(),
+  groundingSources: z15.array(contentGroundingSourceSchema)
+});
+var contentSourcesResponseDtoSchema = z15.object({
+  sources: z15.array(contentSourceRowDtoSchema),
+  latestRunId: z15.string()
+});
+var contentGapRowDtoSchema = z15.object({
+  query: z15.string(),
+  competitorDomains: z15.array(z15.string()),
+  competitorCount: z15.number().int().nonnegative(),
+  missRate: z15.number().min(0).max(1),
+  lastSeenInRunId: z15.string()
+});
+var contentGapsResponseDtoSchema = z15.object({
+  gaps: z15.array(contentGapRowDtoSchema),
+  latestRunId: z15.string()
+});
+
 // src/client.ts
 function createApiClient() {
   const config = loadConfig();
@@ -2032,6 +2207,29 @@ 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`);
   }
@@ -2130,7 +2328,12 @@ export {
   RunStatuses,
   RunKinds,
   RunTriggers,
+  CitationStates,
   runTriggerRequestSchema,
+  parseRunError,
+  buildRunErrorFromMessages,
+  serializeRunError,
+  formatRunErrorOneLine,
   snapshotRequestSchema,
   scheduleUpsertRequestSchema,
   parseWindow,