@clickminded/coauthor-cli 0.0.85 → 0.0.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,6 +17,11 @@ export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?
17
17
  * reported as completed *with items to review*, never as plainly done.
18
18
  */
19
19
  export declare function draftCompletionMessage(base: string, status: JsonValue): string;
20
+ /**
21
+ * "Where AI search mentions you" in `seo-plan show`: mentions per platform, the comparison leader and the top
22
+ * question. Nothing when the plan has no AI search data.
23
+ */
24
+ export declare function seoPlanAiSearchLines(value: unknown): string[];
20
25
  /**
21
26
  * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
22
27
  * list (at most 4 endings, at most one custom).
package/dist/commands.js CHANGED
@@ -2480,7 +2480,11 @@ function seoPlanItemLine(item) {
2480
2480
  const id = planString(item, 'id') ?? '';
2481
2481
  const postType = planString(item, 'post_type');
2482
2482
  const linkMagnet = (item.kind === undefined || item.kind === 'post') && postType !== null && SEO_PLAN_LINK_MAGNET_POST_TYPES.includes(postType) ? '[link magnet] ' : '';
2483
- const head = ` ${id} ${linkMagnet}${title}`;
2483
+ const aiGap = item.ai_gap && typeof item.ai_gap === 'object' && Array.isArray(item.ai_gap.competitors)
2484
+ ? item.ai_gap.competitors
2485
+ : null;
2486
+ const aiGapTag = aiGap && aiGap.length > 0 ? '[AI gap] ' : '';
2487
+ const head = ` ${id} ${linkMagnet}${aiGapTag}${title}`;
2484
2488
  const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
2485
2489
  const where = planString(item, 'existing_url');
2486
2490
  const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
@@ -2492,8 +2496,41 @@ function seoPlanItemLine(item) {
2492
2496
  `${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}${done}`,
2493
2497
  where ? ` ${where}${position}` : null,
2494
2498
  hint ? ` ${hint}` : null,
2499
+ aiGapTag ? ` Google AI answers cite ${aiGap.filter((domain) => typeof domain === 'string').join(', ')} for this, not you.` : null,
2495
2500
  ].filter(Boolean).join('\n');
2496
2501
  }
2502
+ /**
2503
+ * "Where AI search mentions you" in `seo-plan show`: mentions per platform, the comparison leader and the top
2504
+ * question. Nothing when the plan has no AI search data.
2505
+ */
2506
+ export function seoPlanAiSearchLines(value) {
2507
+ if (!value || typeof value !== 'object')
2508
+ return [];
2509
+ const visibility = planRecord(value);
2510
+ const platform = (key, label) => {
2511
+ if (visibility[key] === null || visibility[key] === undefined)
2512
+ return null;
2513
+ const row = planRecord(visibility[key]);
2514
+ const mentions = typeof row.mentions === 'number' ? row.mentions : 0;
2515
+ const cited = typeof row.cited === 'number' ? row.cited : 0;
2516
+ return `${label} ${mentions.toLocaleString('en-US')} ${mentions === 1 ? 'answer' : 'answers'}${mentions > 0 ? ` (${cited.toLocaleString('en-US')} cite you)` : ''}`;
2517
+ };
2518
+ const parts = [platform('google', 'Google AI answers'), platform('chat_gpt', 'ChatGPT')].filter((part) => part !== null);
2519
+ if (parts.length === 0)
2520
+ return [];
2521
+ const lines = [`AI search mentions: ${parts.join('; ')}.${visibility.chat_gpt_available === false ? ' ChatGPT data covers the United States in English only.' : ''}`];
2522
+ const competitors = Array.isArray(visibility.competitors) ? visibility.competitors.map(planRecord) : [];
2523
+ const leader = competitors.find((row) => typeof row.mentions === 'number' && row.mentions > 0);
2524
+ if (leader)
2525
+ lines.push(` Top competitor in Google AI answers: ${planString(leader, 'domain')} (${leader.mentions.toLocaleString('en-US')}).`);
2526
+ const questions = Array.isArray(planRecord(visibility.google).questions) ? planRecord(visibility.google).questions.map(planRecord) : [];
2527
+ const top = questions[0];
2528
+ if (top) {
2529
+ const url = Array.isArray(top.own_urls) && typeof top.own_urls[0] === 'string' ? top.own_urls[0] : null;
2530
+ lines.push(` Top question: "${planString(top, 'question')}"${url ? ` -> ${url}` : ''}.`);
2531
+ }
2532
+ return lines;
2533
+ }
2497
2534
  function seoPlanShowMessage(data, kind) {
2498
2535
  const view = planRecord(data);
2499
2536
  const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
@@ -2534,6 +2571,9 @@ function seoPlanShowMessage(data, kind) {
2534
2571
  const competitors = planString(plan, 'competitors_line');
2535
2572
  if (competitors)
2536
2573
  lines.push(`Competitors: ${competitors}`);
2574
+ const aiSearch = seoPlanAiSearchLines(plan.ai_visibility);
2575
+ if (aiSearch.length > 0)
2576
+ lines.push(...aiSearch);
2537
2577
  const doNext = Array.isArray(view.do_next) ? view.do_next.map(planRecord) : [];
2538
2578
  if (doNext.length > 0) {
2539
2579
  lines.push('', 'Do next:');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.85",
3
+ "version": "0.0.87",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -72,6 +72,26 @@ Other fields to use when you recommend an idea:
72
72
  - `do_next_rank` (1 to 5) marks the plan's own top moves.
73
73
  - Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
74
74
 
75
+ ### Where AI search mentions the site
76
+
77
+ `data.plan.ai_visibility` says how often stored AI answers mention the site, from DataForSEO's saved answers (no live prompting). It is `null` when the plan has none (plans made before it, or when the lookup did not run). When present:
78
+
79
+ - `google`: Google AI answers (AI Overviews and AI Mode) in the plan's market. `mentions` counts answers that used one of the site's pages, `cited` the ones that link to it as a source, and `questions` lists up to 8 questions answered with its pages (`own_urls`, `cited`).
80
+ - `chat_gpt`: the same for ChatGPT. It is `null` outside the United States in English (`chat_gpt_available: false`): ChatGPT answers are only stored for that market.
81
+ - `competitors`: the plan's competitors with their Google AI `mentions`, most first.
82
+
83
+ A mention is not a citation: most mentions mean the AI read the page while answering. Report both numbers as they are, and do not promise that writing a post will change them. The human output of `show` prints one summary line. The web app shows a "Where AI search mentions you" section.
84
+
85
+ ### AI gap ideas
86
+
87
+ Some plans tag ideas whose searches are ones where Google AI answers cite a competitor and never mention the site. Those items carry `ai_gap` (`null` on every other item):
88
+
89
+ - `competitors`: the competitor domains the answers cite, most mentioned first (up to 3).
90
+ - `ai_search_volume`: DataForSEO's estimate of monthly AI searches behind the idea's matching searches.
91
+ - `questions`: on United States / English plans, up to 3 ChatGPT questions about the idea whose answers cite a competitor (`question`, `competitor`). Empty elsewhere.
92
+
93
+ An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief, and the outline answers them.
94
+
75
95
  ## Write this
76
96
 
77
97
  `coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.
@@ -677,6 +677,26 @@ Other fields to use when you recommend an idea:
677
677
  - `do_next_rank` (1 to 5) marks the plan's own top moves.
678
678
  - Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
679
679
 
680
+ #### Where AI search mentions the site
681
+
682
+ `data.plan.ai_visibility` says how often stored AI answers mention the site, from DataForSEO's saved answers (no live prompting). It is `null` when the plan has none (plans made before it, or when the lookup did not run). When present:
683
+
684
+ - `google`: Google AI answers (AI Overviews and AI Mode) in the plan's market. `mentions` counts answers that used one of the site's pages, `cited` the ones that link to it as a source, and `questions` lists up to 8 questions answered with its pages (`own_urls`, `cited`).
685
+ - `chat_gpt`: the same for ChatGPT. It is `null` outside the United States in English (`chat_gpt_available: false`): ChatGPT answers are only stored for that market.
686
+ - `competitors`: the plan's competitors with their Google AI `mentions`, most first.
687
+
688
+ A mention is not a citation: most mentions mean the AI read the page while answering. Report both numbers as they are, and do not promise that writing a post will change them. The human output of `show` prints one summary line. The web app shows a "Where AI search mentions you" section.
689
+
690
+ #### AI gap ideas
691
+
692
+ Some plans tag ideas whose searches are ones where Google AI answers cite a competitor and never mention the site. Those items carry `ai_gap` (`null` on every other item):
693
+
694
+ - `competitors`: the competitor domains the answers cite, most mentioned first (up to 3).
695
+ - `ai_search_volume`: DataForSEO's estimate of monthly AI searches behind the idea's matching searches.
696
+ - `questions`: on United States / English plans, up to 3 ChatGPT questions about the idea whose answers cite a competitor (`question`, `competitor`). Empty elsewhere.
697
+
698
+ An AI gap idea went through the same checks as every other idea; the tag explains why it matters, it does not mean the idea is more likely to rank. The human output of `show` prefixes it with `[AI gap]` and names the competitors. When you write one, `seo-plan write` puts its questions into the post's brief, and the outline answers them.
699
+
680
700
  ### Write this
681
701
 
682
702
  `coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.