@ainyc/canonry 3.6.4 → 4.1.3

package/dist/{chunk-RQMOJEJT.js → chunk-KCETXLDF.js}

@@ -8,9 +8,11 @@ import {
   notificationEventSchema,
   projectConfigSchema,
   projectUpsertRequestSchema,
+  queryBatchRequestSchema,
+  queryGenerateRequestSchema,
   runTriggerRequestSchema,
   scheduleUpsertRequestSchema
-} from "./chunk-O7EVT3AF.js";
+} from "./chunk-O5JZQUPX.js";
 
 // src/config.ts
 import fs from "fs";
@@ -454,6 +456,18 @@ var ApiClient = class {
   async deleteProject(name) {
     await this.request("DELETE", `/projects/${encodeURIComponent(name)}`);
   }
+  async putQueries(project, queries) {
+    await this.request("PUT", `/projects/${encodeURIComponent(project)}/queries`, { queries });
+  }
+  async listQueries(project) {
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/queries`);
+  }
+  async deleteQueries(project, queries) {
+    await this.request("DELETE", `/projects/${encodeURIComponent(project)}/queries`, { queries });
+  }
+  async appendQueries(project, queries) {
+    await this.request("POST", `/projects/${encodeURIComponent(project)}/queries`, { queries });
+  }
   async putKeywords(project, keywords) {
     await this.request("PUT", `/projects/${encodeURIComponent(project)}/keywords`, { keywords });
   }
@@ -567,6 +581,13 @@ var ApiClient = class {
   async updateTelemetry(enabled) {
     return this.request("PUT", "/telemetry", { enabled });
   }
+  async generateQueries(project, provider, count) {
+    return this.request(
+      "POST",
+      `/projects/${encodeURIComponent(project)}/queries/generate`,
+      { provider, count }
+    );
+  }
   async generateKeywords(project, provider, count) {
     return this.request(
       "POST",
@@ -1042,6 +1063,14 @@ var gaWindowInputSchema = z2.object({
 var gaTrafficInputSchema = gaWindowInputSchema.extend({
   limit: z2.number().int().positive().max(500).optional()
 });
+var queriesInputSchema = z2.object({
+  project: projectNameSchema,
+  request: queryBatchRequestSchema
+});
+var queryGenerateInputSchema = z2.object({
+  project: projectNameSchema,
+  request: queryGenerateRequestSchema
+});
 var keywordsInputSchema = z2.object({
   project: projectNameSchema,
   request: keywordBatchRequestSchema
@@ -1124,7 +1153,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_project_overview",
     title: "Get project overview (composite)",
-    description: 'One-call summary for "how is project X doing?" \u2014 bundles project info, latest run, top undismissed insights, latest health snapshot, keyword cited rate, per-provider breakdown, and gained/lost/emerging vs the previous run. Prefer this over fanning out to separate tools.',
+    description: 'One-call summary for "how is project X doing?" \u2014 bundles project info, latest run, top undismissed insights, latest health snapshot, query cited rate, per-provider breakdown, and gained/lost/emerging vs the previous run. Prefer this over fanning out to separate tools.',
     access: "read",
     tier: "core",
     inputSchema: projectInputSchema,
@@ -1135,7 +1164,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_report",
     title: "Get aggregated AEO report",
-    description: "Returns the full client-facing AEO report bundle for a project \u2014 executive summary, per-keyword \xD7 per-provider citation matrix, competitor landscape, AI citation sources, GSC/GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps. Same payload `canonry report <project>` consumes to render the self-contained HTML.",
+    description: "Returns the full client-facing AEO report bundle for a project \u2014 executive summary, per-query \xD7 per-provider citation matrix, competitor landscape, AI citation sources, GSC/GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps. Same payload `canonry report <project>` consumes to render the self-contained HTML.",
     access: "read",
     tier: "monitoring",
     inputSchema: projectInputSchema,
@@ -1146,7 +1175,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_search",
     title: "Search project (composite)",
-    description: "Search query snapshots and intelligence insights for the given text. Looks at snapshot answer text, cited domains, raw provider responses, and insight title/keyword/recommendation/cause. Returns ranked hits with snippets \u2014 use it instead of paginating snapshots when you need to find a competitor mention or term.",
+    description: "Search query snapshots and intelligence insights for the given text. Looks at snapshot answer text, cited domains, raw provider responses, and insight title/query/recommendation/cause. Returns ranked hits with snippets \u2014 use it instead of paginating snapshots when you need to find a competitor mention or term.",
     access: "read",
     tier: "core",
     inputSchema: z2.object({
@@ -1227,7 +1256,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_timeline_get",
     title: "Get project timeline",
-    description: "Get per-keyword citation history for a Canonry project.",
+    description: "Get per-query citation history for a Canonry project.",
     access: "read",
     tier: "monitoring",
     inputSchema: timelineInputSchema,
@@ -1308,7 +1337,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_citations_visibility",
     title: "Get citation visibility",
-    description: 'Single-call AI citation surface for a Canonry project. Returns the project headline (cited by N of M engines), per-keyword engine coverage rows from the latest snapshot per (keyword \xD7 provider), and a competitor-gap list (keywords where a configured competitor is cited but the project is not). Carries `status: "no-data"` with `reason: "no-keywords"` or `"no-runs-yet"` when inputs are missing.',
+    description: 'Single-call AI citation surface for a Canonry project. Returns the project headline (cited by N of M engines), per-query engine coverage rows from the latest snapshot per (query \xD7 provider), and a competitor-gap list (queries where a configured competitor is cited but the project is not). Carries `status: "no-data"` with `reason: "no-queries"` or `"no-runs-yet"` when inputs are missing.',
     access: "read",
     tier: "monitoring",
     inputSchema: projectInputSchema,
@@ -1352,10 +1381,21 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/content/gaps"],
     handler: (client, input) => client.getContentGaps(input.project)
   }),
+  defineTool({
+    name: "canonry_queries_list",
+    title: "List queries",
+    description: "List tracked queries for a Canonry project.",
+    access: "read",
+    tier: "setup",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/queries"],
+    handler: (client, input) => client.listQueries(input.project)
+  }),
   defineTool({
     name: "canonry_keywords_list",
-    title: "List keywords",
-    description: "List tracked keywords for a Canonry project.",
+    title: "List keywords (legacy alias)",
+    description: "Legacy alias for canonry_queries_list. Returns tracked queries using the pre-queries keyword response shape.",
     access: "read",
     tier: "setup",
     inputSchema: projectInputSchema,
@@ -1609,10 +1649,21 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/apply"],
     handler: (client, input) => client.apply(input.config)
   }),
+  defineTool({
+    name: "canonry_queries_generate",
+    title: "Generate query suggestions",
+    description: "Generate candidate queries using a configured provider. Returns suggestions only; use canonry_queries_add to persist them.",
+    access: "write",
+    tier: "setup",
+    inputSchema: queryGenerateInputSchema,
+    annotations: writeAnnotations({ idempotentHint: false, openWorldHint: true }),
+    openApiOperations: ["POST /api/v1/projects/{name}/queries/generate"],
+    handler: (client, input) => client.generateQueries(input.project, input.request.provider, input.request.count)
+  }),
   defineTool({
     name: "canonry_keywords_generate",
-    title: "Generate keyword suggestions",
-    description: "Generate candidate key phrases using a configured provider. Returns suggestions only; use canonry_keywords_add to persist them.",
+    title: "Generate keyword suggestions (legacy alias)",
+    description: "Legacy alias for canonry_queries_generate. Returns suggestions using the pre-queries keyword response shape.",
     access: "write",
     tier: "setup",
     inputSchema: keywordGenerateInputSchema,
@@ -1620,10 +1671,23 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/projects/{name}/keywords/generate"],
     handler: (client, input) => client.generateKeywords(input.project, input.request.provider, input.request.count)
   }),
+  defineTool({
+    name: "canonry_queries_replace",
+    title: "Replace queries",
+    description: "Replace the tracked query set for a Canonry project.",
+    access: "write",
+    tier: "setup",
+    inputSchema: queriesInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["PUT /api/v1/projects/{name}/queries"],
+    handler: async (client, input) => {
+      await client.putQueries(input.project, uniqueStrings(input.request.queries));
+    }
+  }),
   defineTool({
     name: "canonry_keywords_replace",
-    title: "Replace keywords",
-    description: "Replace the tracked keyword set for a Canonry project.",
+    title: "Replace keywords (legacy alias)",
+    description: "Legacy alias for canonry_queries_replace. Replaces the same canonical tracked query set.",
     access: "write",
     tier: "setup",
     inputSchema: keywordsInputSchema,
@@ -1655,10 +1719,23 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/runs/{id}/cancel"],
     handler: (client, input) => client.cancelRun(input.runId)
   }),
+  defineTool({
+    name: "canonry_queries_add",
+    title: "Add queries",
+    description: "Append tracked queries to a Canonry project; existing queries are skipped by the API.",
+    access: "write",
+    tier: "setup",
+    inputSchema: queriesInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true }),
+    openApiOperations: ["POST /api/v1/projects/{name}/queries"],
+    handler: async (client, input) => {
+      await client.appendQueries(input.project, uniqueStrings(input.request.queries));
+    }
+  }),
   defineTool({
     name: "canonry_keywords_add",
-    title: "Add keywords",
-    description: "Append tracked keywords to a Canonry project; existing keywords are skipped by the API.",
+    title: "Add keywords (legacy alias)",
+    description: "Legacy alias for canonry_queries_add. Appends to the same canonical tracked query set.",
     access: "write",
     tier: "setup",
     inputSchema: keywordsInputSchema,
@@ -1668,10 +1745,23 @@ var canonryMcpTools = [
       await client.appendKeywords(input.project, uniqueStrings(input.request.keywords));
     }
   }),
+  defineTool({
+    name: "canonry_queries_remove",
+    title: "Remove queries",
+    description: "Remove tracked queries from a Canonry project.",
+    access: "write",
+    tier: "setup",
+    inputSchema: queriesInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
+    openApiOperations: ["DELETE /api/v1/projects/{name}/queries"],
+    handler: async (client, input) => {
+      await client.deleteQueries(input.project, uniqueStrings(input.request.queries));
+    }
+  }),
   defineTool({
     name: "canonry_keywords_remove",
-    title: "Remove keywords",
-    description: "Remove tracked keywords from a Canonry project.",
+    title: "Remove keywords (legacy alias)",
+    description: "Legacy alias for canonry_queries_remove. Removes from the same canonical tracked query set.",
     access: "write",
     tier: "setup",
     inputSchema: keywordsInputSchema,

package/dist/{chunk-O7EVT3AF.js → chunk-O5JZQUPX.js}

@@ -168,8 +168,8 @@ var groundingSourceSchema = z2.object({
 var querySnapshotDtoSchema = z2.object({
   id: z2.string(),
   runId: z2.string(),
-  keywordId: z2.string(),
-  keyword: z2.string().optional(),
+  queryId: z2.string(),
+  query: z2.string().optional(),
   provider: providerNameSchema,
   citationState: citationStateSchema,
   answerMentioned: z2.boolean().optional(),
@@ -191,8 +191,8 @@ var snapshotListResponseSchema = z2.object({
   total: z2.number().int().nonnegative()
 });
 var snapshotDiffRowSchema = z2.object({
-  keywordId: z2.string().nullable(),
-  keyword: z2.string().nullable(),
+  queryId: z2.string().nullable(),
+  query: z2.string().nullable(),
   run1State: citationStateSchema.nullable(),
   run2State: citationStateSchema.nullable(),
   run1AnswerMentioned: z2.boolean().nullable(),
@@ -311,18 +311,27 @@ var projectDtoSchema = z4.object({
   createdAt: z4.string().optional(),
   updatedAt: z4.string().optional()
 });
+var queryDtoSchema = z4.object({
+  id: z4.string(),
+  query: z4.string(),
+  createdAt: z4.string()
+});
 var keywordDtoSchema = z4.object({
   id: z4.string(),
   keyword: z4.string(),
   createdAt: z4.string()
 });
+var queryBatchRequestSchema = z4.object({
+  queries: z4.array(z4.string().trim().min(1)).min(1)
+});
 var keywordBatchRequestSchema = z4.object({
   keywords: z4.array(z4.string().trim().min(1)).min(1)
 });
-var keywordGenerateRequestSchema = z4.object({
+var queryGenerateRequestSchema = z4.object({
   provider: providerNameSchema,
   count: z4.number().int().min(1).max(20).optional()
 });
+var keywordGenerateRequestSchema = queryGenerateRequestSchema;
 var competitorDtoSchema = z4.object({
   id: z4.string(),
   domain: z4.string(),
@@ -444,13 +453,15 @@ var configGoogleSchema = z5.object({
     cron: z5.string().optional()
   }).optional()
 }).optional();
+var configQueryListSchema = z5.array(z5.string().min(1));
 var configSpecSchema = z5.object({
   displayName: z5.string().min(1),
   canonicalDomain: z5.string().min(1),
   ownedDomains: z5.array(z5.string().min(1)).optional().default([]),
   country: z5.string().length(2),
   language: z5.string().min(2),
-  keywords: z5.array(z5.string().min(1)).optional().default([]),
+  queries: configQueryListSchema.optional(),
+  keywords: configQueryListSchema.optional(),
   competitors: z5.array(z5.string().min(1)).optional().default([]),
   providers: z5.array(providerNameSchema).optional().default([]),
   locations: z5.array(locationContextSchema).optional().default([]),
@@ -460,6 +471,13 @@ var configSpecSchema = z5.object({
   google: configGoogleSchema,
   autoExtractBacklinks: z5.boolean().optional().default(false)
 }).superRefine((spec, ctx) => {
+  if (spec.queries !== void 0 && spec.keywords !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Use spec.queries; spec.keywords is accepted only as a legacy alias when spec.queries is omitted",
+      path: ["keywords"]
+    });
+  }
   const duplicateLabels = findDuplicateLocationLabels(spec.locations);
   if (duplicateLabels.length > 0) {
     ctx.addIssue({
@@ -482,6 +500,9 @@ var projectConfigSchema = z5.object({
   metadata: configMetadataSchema,
   spec: configSpecSchema
 });
+function resolveConfigSpecQueries(spec) {
+  return spec.queries ?? spec.keywords ?? [];
+}
 
 // ../contracts/src/errors.ts
 var AppError = class extends Error {
@@ -870,12 +891,25 @@ function isAgentProviderId(value) {
 // ../contracts/src/snapshot.ts
 import { z as z9 } from "zod";
 var snapshotAccuracySchema = z9.enum(["yes", "no", "unknown", "not-mentioned"]);
+var snapshotQueryListSchema = z9.array(z9.string().min(1));
 var snapshotRequestSchema = z9.object({
   companyName: z9.string().min(1),
   domain: z9.string().min(1),
-  phrases: z9.array(z9.string().min(1)).optional().default([]),
+  queries: snapshotQueryListSchema.optional(),
+  phrases: snapshotQueryListSchema.optional(),
   competitors: z9.array(z9.string().min(1)).optional().default([])
+}).superRefine((input, ctx) => {
+  if (input.queries !== void 0 && input.phrases !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Use queries; phrases is accepted only as a legacy alias when queries is omitted",
+      path: ["phrases"]
+    });
+  }
 });
+function resolveSnapshotRequestQueries(input) {
+  return input.queries ?? input.phrases ?? [];
+}
 var snapshotCompetitorEntrySchema = z9.object({
   name: z9.string(),
   count: z9.number().int().nonnegative()
@@ -925,7 +959,7 @@ var snapshotProviderResultSchema = z9.object({
   error: z9.string().nullable().optional()
 });
 var snapshotQueryResultSchema = z9.object({
-  phrase: z9.string(),
+  query: z9.string(),
   providerResults: z9.array(snapshotProviderResultSchema).default([])
 });
 var snapshotSummarySchema = z9.object({
@@ -944,7 +978,7 @@ var snapshotReportSchema = z9.object({
   domain: z9.string(),
   homepageUrl: z9.string(),
   generatedAt: z9.string(),
-  phrases: z9.array(z9.string()).default([]),
+  queries: z9.array(z9.string()).default([]),
   competitors: z9.array(z9.string()).default([]),
   profile: snapshotProfileSchema,
   audit: snapshotAuditSchema,
@@ -1463,11 +1497,11 @@ var projectSearchSnapshotHitSchema = z15.object({
   kind: z15.literal("snapshot"),
   id: z15.string(),
   runId: z15.string(),
-  keyword: z15.string(),
+  query: z15.string(),
   provider: z15.string(),
   model: z15.string().nullable(),
   citationState: citationStateSchema,
-  matchedField: z15.enum(["answerText", "citedDomains", "searchQueries", "keyword"]),
+  matchedField: z15.enum(["answerText", "citedDomains", "searchQueries", "query"]),
   snippet: z15.string(),
   createdAt: z15.string()
 });
@@ -1478,9 +1512,9 @@ var projectSearchInsightHitSchema = z15.object({
   type: z15.enum(["regression", "gain", "opportunity"]),
   severity: z15.enum(["critical", "high", "medium", "low"]),
   title: z15.string(),
-  keyword: z15.string(),
+  query: z15.string(),
   provider: z15.string(),
-  matchedField: z15.enum(["title", "keyword", "recommendation", "cause"]),
+  matchedField: z15.enum(["title", "query", "recommendation", "cause"]),
   snippet: z15.string(),
   dismissed: z15.boolean(),
   createdAt: z15.string()
@@ -1793,16 +1827,16 @@ var citationCoverageProviderSchema = z18.object({
   runCreatedAt: z18.string()
 });
 var citationCoverageRowSchema = z18.object({
-  keywordId: z18.string(),
-  keyword: z18.string(),
+  queryId: z18.string(),
+  query: z18.string(),
   providers: z18.array(citationCoverageProviderSchema),
   citedCount: z18.number().int().nonnegative(),
   mentionedCount: z18.number().int().nonnegative(),
   totalProviders: z18.number().int().nonnegative()
 });
 var competitorGapRowSchema = z18.object({
-  keywordId: z18.string(),
-  keyword: z18.string(),
+  queryId: z18.string(),
+  query: z18.string(),
   provider: z18.string(),
   citingCompetitors: z18.array(z18.string()),
   runId: z18.string(),
@@ -1812,23 +1846,23 @@ var citationVisibilitySummarySchema = z18.object({
   providersConfigured: z18.number().int().nonnegative(),
   providersCiting: z18.number().int().nonnegative(),
   providersMentioning: z18.number().int().nonnegative(),
-  totalKeywords: z18.number().int().nonnegative(),
-  // Cross-tab buckets — each tracked keyword with at least one snapshot lands
-  // in exactly one of these. Keywords with zero snapshots are not counted in
-  // any bucket; (sum of buckets) ≤ totalKeywords.
-  keywordsCitedAndMentioned: z18.number().int().nonnegative(),
-  keywordsCitedOnly: z18.number().int().nonnegative(),
-  keywordsMentionedOnly: z18.number().int().nonnegative(),
-  keywordsInvisible: z18.number().int().nonnegative(),
+  totalQueries: z18.number().int().nonnegative(),
+  // Cross-tab buckets — each tracked query with at least one snapshot lands
+  // in exactly one of these. Queries with zero snapshots are not counted in
+  // any bucket; (sum of buckets) ≤ totalQueries.
+  queriesCitedAndMentioned: z18.number().int().nonnegative(),
+  queriesCitedOnly: z18.number().int().nonnegative(),
+  queriesMentionedOnly: z18.number().int().nonnegative(),
+  queriesInvisible: z18.number().int().nonnegative(),
   latestRunId: z18.string().nullable(),
   latestRunAt: z18.string().nullable()
 });
 var citationVisibilityResponseSchema = z18.object({
   summary: citationVisibilitySummarySchema,
-  byKeyword: z18.array(citationCoverageRowSchema),
+  byQuery: z18.array(citationCoverageRowSchema),
   competitorGaps: z18.array(competitorGapRowSchema),
   status: z18.enum(["ready", "no-data"]),
-  reason: z18.enum(["no-runs-yet", "no-keywords"]).optional()
+  reason: z18.enum(["no-runs-yet", "no-queries"]).optional()
 });
 function emptyCitationVisibility(reason) {
   return {
@@ -1836,15 +1870,15 @@ function emptyCitationVisibility(reason) {
       providersConfigured: 0,
       providersCiting: 0,
       providersMentioning: 0,
-      totalKeywords: 0,
-      keywordsCitedAndMentioned: 0,
-      keywordsCitedOnly: 0,
-      keywordsMentionedOnly: 0,
-      keywordsInvisible: 0,
+      totalQueries: 0,
+      queriesCitedAndMentioned: 0,
+      queriesCitedOnly: 0,
+      queriesMentionedOnly: 0,
+      queriesInvisible: 0,
       latestRunId: null,
       latestRunAt: null
     },
-    byKeyword: [],
+    byQuery: [],
     competitorGaps: [],
     status: "no-data",
     reason
@@ -1873,7 +1907,9 @@ export {
   findDuplicateLocationLabels,
   hasLocationLabel,
   projectUpsertRequestSchema,
+  queryBatchRequestSchema,
   keywordBatchRequestSchema,
+  queryGenerateRequestSchema,
   keywordGenerateRequestSchema,
   competitorBatchRequestSchema,
   normalizeProjectDomain,
@@ -1881,6 +1917,7 @@ export {
   brandLabelFromDomain,
   effectiveDomains,
   projectConfigSchema,
+  resolveConfigSpecQueries,
   AppError,
   notFound,
   validationError,
@@ -1909,6 +1946,7 @@ export {
   serializeRunError,
   formatRunErrorOneLine,
   snapshotRequestSchema,
+  resolveSnapshotRequestQueries,
   scheduleUpsertRequestSchema,
   parseWindow,
   windowCutoff,