@clickminded/coauthor-cli 0.0.39 → 0.0.40

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.
package/README.md CHANGED
@@ -81,6 +81,7 @@ coauthor draft get <id> --format markdown --frontmatter --json # markdown with
81
81
  coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
82
82
  coauthor credits <id> --json
83
83
  coauthor integrations list --json # WordPress sites and X accounts
84
+ coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
84
85
  ```
85
86
 
86
87
  Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
package/dist/commands.js CHANGED
@@ -45,6 +45,8 @@ export async function runCommand(input, context) {
45
45
  return runDraftCommand(action, input, context);
46
46
  if (scope === 'post-details')
47
47
  return runPostDetailsCommand(action, input, context.client);
48
+ if (scope === 'seo')
49
+ return runSeoCommand(action, input, context.client);
48
50
  if (scope === 'workflow')
49
51
  return runWorkflowCommand(action, input, context);
50
52
  if (scope === 'credits')
@@ -645,6 +647,60 @@ const POST_DETAILS_FLAG_FIELDS = [
645
647
  ['slug', 'slug'],
646
648
  ['excerpt', 'excerpt'],
647
649
  ];
650
+ async function runSeoCommand(action, input, client) {
651
+ if (action !== 'markets')
652
+ throw new Error('Usage: coauthor seo markets [--country <country>] [--language <language>]');
653
+ const query = new URLSearchParams();
654
+ const country = getString(input.values, 'country')?.trim();
655
+ const language = getString(input.values, 'language')?.trim();
656
+ if (country)
657
+ query.set('country', country);
658
+ if (language)
659
+ query.set('language', language);
660
+ const suffix = query.toString();
661
+ const data = await client.request({ path: suffix ? `seo/markets?${suffix}` : 'seo/markets' });
662
+ return { ok: true, message: describeMarketCoverage(data), data };
663
+ }
664
+ function namesOf(value, key = 'name') {
665
+ if (!Array.isArray(value))
666
+ return [];
667
+ return value.flatMap((entry) => {
668
+ const name = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry[key] : null;
669
+ return typeof name === 'string' ? [name] : [];
670
+ });
671
+ }
672
+ /** A one-paragraph summary of a seo/markets response; --json has the full data. */
673
+ function describeMarketCoverage(data) {
674
+ if (!data || typeof data !== 'object' || Array.isArray(data))
675
+ return undefined;
676
+ const record = data;
677
+ const explanation = record.explanation && typeof record.explanation === 'object' && !Array.isArray(record.explanation)
678
+ ? record.explanation.message
679
+ : null;
680
+ if (record.kind === 'pair') {
681
+ const support = record.support;
682
+ return typeof explanation === 'string' ? explanation : `Fully covered (tier: ${String(support?.tier ?? 'full')}).`;
683
+ }
684
+ if (record.kind === 'country') {
685
+ if (typeof explanation === 'string')
686
+ return explanation;
687
+ const country = record.country;
688
+ const full = namesOf(record.full_languages);
689
+ const limited = namesOf(record.limited_languages);
690
+ return `${String(country?.name ?? 'This country')}: full data for ${full.join(', ') || 'no languages'}; limited data for ${limited.length} other language(s).`;
691
+ }
692
+ if (record.kind === 'language') {
693
+ const language = record.language;
694
+ if (!language)
695
+ return "That language isn't one CoAuthor has Google search data for.";
696
+ const countries = namesOf(record.full_countries);
697
+ return `${String(language.name)} is fully covered in ${countries.length} countries: ${countries.join(', ')}.`;
698
+ }
699
+ if (record.kind === 'all' && Array.isArray(record.full_markets)) {
700
+ return `${record.full_markets.length} countries have full search data. Use --country or --language to check one market.`;
701
+ }
702
+ return undefined;
703
+ }
648
704
  async function runPostDetailsCommand(action, input, client) {
649
705
  const projectId = requireProjectId(input);
650
706
  const path = `projects/${encodeURIComponent(projectId)}/post-details`;
@@ -2554,6 +2610,7 @@ export function helpResult(command = []) {
2554
2610
  ' draft revision show|apply|discard',
2555
2611
  ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
2556
2612
  ' post-details show|set',
2613
+ ' seo markets [--country <country>] [--language <language>]',
2557
2614
  ' workflow show|status|advance|run|rewind|approve|resume',
2558
2615
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2559
2616
  ' image list|status|show|generate|edit|metadata|replace',
@@ -2756,6 +2813,14 @@ function commandHelp(command) {
2756
2813
  'The export prints its operation key; check it with coauthor operation status <key>, or rerun with --idempotency-key <key> to replay safely.',
2757
2814
  'Needs a login with publish permission (coauthor auth login --with-publish). With several sites connected, the error lists their ids for --connection-id.',
2758
2815
  ].join('\n'),
2816
+ 'seo markets': [
2817
+ 'Usage: coauthor seo markets [--country <country>] [--language <language>] [--json]',
2818
+ '',
2819
+ 'Shows which countries and languages CoAuthor has Google search data for (from DataForSEO).',
2820
+ 'Full means keyword volume, difficulty and ranking checks are available. Limited means CoAuthor can analyze what ranks but not keyword difficulty or existing rankings.',
2821
+ 'With both --country and --language it checks one market and explains anything that is not covered, with alternatives.',
2822
+ 'Countries and languages accept names or codes ("Mexico" or "MX", "Spanish" or "es"). Markets are country-level.',
2823
+ ].join('\n'),
2759
2824
  'post-details': [
2760
2825
  'Usage: coauthor post-details show <project-id> [--json]',
2761
2826
  ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--json]',
package/dist/parser.js CHANGED
@@ -55,6 +55,8 @@ const OPTIONS = {
55
55
  excerpt: { type: 'string' },
56
56
  'seo-title': { type: 'string' },
57
57
  frontmatter: { type: 'boolean', default: false },
58
+ country: { type: 'string' },
59
+ language: { type: 'string' },
58
60
  status: { type: 'string' },
59
61
  limit: { type: 'string' },
60
62
  cursor: { type: 'string' },
@@ -193,6 +195,8 @@ function commandLength(positionals) {
193
195
  return 1;
194
196
  if (first === 'post-details')
195
197
  return second && ['show', 'set'].includes(second) ? 2 : 1;
198
+ if (first === 'seo')
199
+ return second === 'markets' ? 2 : 1;
196
200
  if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
197
201
  return second ? 2 : 1;
198
202
  return 1;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.39",
3
+ "version": "0.0.40",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -16,6 +16,10 @@ All fields are optional and omitted ones get defaults, but always include at lea
16
16
  - `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
17
17
  - Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
18
18
 
19
+ ## Search markets
20
+
21
+ `coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
22
+
19
23
  ## Writing a sharp brief
20
24
 
21
25
  - **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
@@ -95,6 +95,10 @@ All fields are optional and omitted ones get defaults, but always include at lea
95
95
  - `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
96
96
  - Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
97
97
 
98
+ ### Search markets
99
+
100
+ `coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
101
+
98
102
  ### Writing a sharp brief
99
103
 
100
104
  - **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.