@clickminded/coauthor-cli 0.0.57 → 0.0.59

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
@@ -80,6 +80,7 @@ coauthor repurpose download <id> --out ./social # copy-ready files
80
80
  coauthor share <id> --json # public read-only link
81
81
  coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
82
82
  coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
83
+ coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it)
83
84
  coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
84
85
  coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
85
86
  coauthor credits <id> --json
package/dist/commands.js CHANGED
@@ -754,8 +754,22 @@ async function runPostDetailsCommand(action, input, client) {
754
754
  if (value !== undefined)
755
755
  body[field] = value.trim() ? value : null;
756
756
  }
757
+ // The live URL is not an SEO field: the server stores it outside user_edited_fields and keeps it
758
+ // across regeneration and exports. --clear-live-url removes it (auto-detection then leaves the post alone).
759
+ const liveUrl = getString(input.values, 'live-url')?.trim();
760
+ const clearLiveUrl = getBoolean(input.values, 'clear-live-url');
761
+ if (clearLiveUrl && liveUrl)
762
+ throw new Error('Pass either --live-url <url> or --clear-live-url, not both.');
763
+ if (liveUrl) {
764
+ if (!/^https?:\/\/\S+$/i.test(liveUrl))
765
+ throw new Error('--live-url needs a full address starting with http:// or https://.');
766
+ body.published_url = liveUrl;
767
+ }
768
+ else if (clearLiveUrl) {
769
+ body.published_url = null;
770
+ }
757
771
  if (Object.keys(body).length === 0) {
758
- throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."]');
772
+ throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url]');
759
773
  }
760
774
  return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
761
775
  }
@@ -2273,8 +2287,10 @@ function seoPlanShowMessage(data, kind) {
2273
2287
  const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
2274
2288
  const estimate = typeof view.estimate_credits === 'number' ? view.estimate_credits : null;
2275
2289
  const status = plan ? planString(plan, 'status') : null;
2290
+ const firstPlanFree = view.first_plan_free === true;
2276
2291
  if (!plan || status === 'idle') {
2277
- return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${estimate ? ` (about ${estimate} credits)` : ''}.`;
2292
+ const cost = firstPlanFree ? ' (your first plan is free)' : estimate ? ` (about ${estimate} credits)` : '';
2293
+ return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${cost}.`;
2278
2294
  }
2279
2295
  const lines = [];
2280
2296
  if (status === 'queued' || status === 'running') {
@@ -2283,7 +2299,7 @@ function seoPlanShowMessage(data, kind) {
2283
2299
  }
2284
2300
  else if (status === 'failed') {
2285
2301
  const code = planString(plan, 'error_code');
2286
- lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.`);
2302
+ lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.${firstPlanFree ? ' Your first plan is free, so the retry uses no credits.' : ''}`);
2287
2303
  }
2288
2304
  if (view.stale === true)
2289
2305
  lines.push('The profile\'s website or market changed since this plan was made. `coauthor seo-plan generate` updates it.');
@@ -2412,7 +2428,9 @@ async function runSeoPlanCommand(action, input, client) {
2412
2428
  throw error;
2413
2429
  }
2414
2430
  const estimate = getResponseNumber(started, 'estimate_credits');
2415
- const queued = `Plan queued${estimate ? ` (about ${estimate} credits, charged as it runs)` : ''}. It takes about 5 to 12 minutes.`;
2431
+ const free = planRecord(started).free === true;
2432
+ const cost = free ? ' (your first plan is free: no credits are used)' : estimate ? ` (about ${estimate} credits, charged as it runs)` : '';
2433
+ const queued = `Plan queued${cost}. It takes about 5 to 12 minutes.`;
2416
2434
  if (!wait) {
2417
2435
  return {
2418
2436
  ok: true,
@@ -3554,10 +3572,11 @@ function commandHelp(command) {
3554
3572
  ].join('\n'),
3555
3573
  'post-details': [
3556
3574
  'Usage: coauthor post-details show <project-id> [--json]',
3557
- ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--json]',
3575
+ ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--json]',
3558
3576
  '',
3559
3577
  'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
3560
3578
  'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
3579
+ 'The live URL is where the post is published. show returns published_url and published_url_source (export, manual, auto_detect or cleared). --live-url sets it by hand (an http or https address) and wins over later exports; --clear-live-url removes it, and CoAuthor then does not look for it again.',
3561
3580
  'Posts drafted before post details launched have none (show returns post_details: null; set returns post_details_unavailable).',
3562
3581
  'SEO posts also return seo: the target keyword, market, SEO research credits and a checklist computed from the current draft (pass, warn, fail or skip per check).',
3563
3582
  ].join('\n'),
package/dist/parser.js CHANGED
@@ -54,6 +54,8 @@ const OPTIONS = {
54
54
  'connection-id': { type: 'string' },
55
55
  excerpt: { type: 'string' },
56
56
  'seo-title': { type: 'string' },
57
+ 'live-url': { type: 'string' },
58
+ 'clear-live-url': { type: 'boolean', default: false },
57
59
  keyword: { type: 'string' },
58
60
  seo: { type: 'string' },
59
61
  'confirm-reset': { type: 'boolean', default: false },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.57",
3
+ "version": "0.0.59",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -9,7 +9,7 @@ Rough costs, to set expectations before starting:
9
9
  - A complete article (brief through draft) is typically about 300 credits.
10
10
  - Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
11
11
  - Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
12
- - An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
12
+ - An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
13
13
 
14
14
  Tell the user the expected cost before large or repeated work, and report credits used at the end.
15
15
 
@@ -20,10 +20,14 @@ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and
20
20
  ```sh
21
21
  coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
22
22
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
23
+ coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
24
+ coauthor post-details set <id> --clear-live-url --json
23
25
  ```
24
26
 
25
27
  `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
26
28
 
29
+ The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
30
+
27
31
  For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
28
32
 
29
33
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
@@ -12,8 +12,9 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
12
12
 
13
13
  ## Cost and timing
14
14
 
15
- - A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
16
- - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
15
+ - The first plan an account makes is free: no credits are used. `show` reports `data.first_plan_free: true` until any plan has finished, and `generate` returns `data.free: true` with `data.estimate_credits: 0`. A first run that fails leaves the account eligible, so the retry is free too. It starts only if the account has at least 1 credit remaining (`insufficient_credits` with `details.required: 1` otherwise).
16
+ - Every later plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. This includes Update plan, `--adjust`, and a plan for another profile. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
17
+ - A paid plan needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
17
18
  - Reading the plan (`show`), writing from it, and dismissing or marking ideas done cost nothing. Writing a post from an idea then costs credits like any other piece.
18
19
  - Only one plan runs per account at a time (`plan_running`).
19
20
 
@@ -29,7 +30,7 @@ coauthor seo-plan done <item-id> [--undo] --json
29
30
  ```
30
31
 
31
32
  - Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
32
- - `generate` returns at once with `data.plan_id` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
33
+ - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
33
34
  - `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
34
35
  - `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
35
36
  - A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
@@ -50,7 +50,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
50
50
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
51
51
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
52
52
  | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
53
- | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
53
+ | `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
54
54
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
55
55
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
56
56
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
@@ -61,7 +61,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
61
61
  | `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
62
62
  | `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
63
63
  | `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
64
- | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
64
+ | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). The first plan is free but still needs at least 1 credit remaining (`details.free: true`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
65
65
  | `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
66
66
  | `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
67
67
  | `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |
@@ -276,7 +276,7 @@ Rough costs, to set expectations before starting:
276
276
  - A complete article (brief through draft) is typically about 300 credits.
277
277
  - Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
278
278
  - Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
279
- - An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
279
+ - An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
280
280
 
281
281
  Tell the user the expected cost before large or repeated work, and report credits used at the end.
282
282
 
@@ -458,10 +458,14 @@ After a draft, CoAuthor writes the post's SEO title, meta description, slug, and
458
458
  ```sh
459
459
  coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
460
460
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
461
+ coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
462
+ coauthor post-details set <id> --clear-live-url --json
461
463
  ```
462
464
 
463
465
  `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
464
466
 
467
+ The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
468
+
465
469
  For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
466
470
 
467
471
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
@@ -592,8 +596,9 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
592
596
 
593
597
  ### Cost and timing
594
598
 
595
- - A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
596
- - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
599
+ - The first plan an account makes is free: no credits are used. `show` reports `data.first_plan_free: true` until any plan has finished, and `generate` returns `data.free: true` with `data.estimate_credits: 0`. A first run that fails leaves the account eligible, so the retry is free too. It starts only if the account has at least 1 credit remaining (`insufficient_credits` with `details.required: 1` otherwise).
600
+ - Every later plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. This includes Update plan, `--adjust`, and a plan for another profile. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
601
+ - A paid plan needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
597
602
  - Reading the plan (`show`), writing from it, and dismissing or marking ideas done cost nothing. Writing a post from an idea then costs credits like any other piece.
598
603
  - Only one plan runs per account at a time (`plan_running`).
599
604
 
@@ -609,7 +614,7 @@ coauthor seo-plan done <item-id> [--undo] --json
609
614
  ```
610
615
 
611
616
  - Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
612
- - `generate` returns at once with `data.plan_id` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
617
+ - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
613
618
  - `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
614
619
  - `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
615
620
  - A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
@@ -711,7 +716,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
711
716
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
712
717
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
713
718
  | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
714
- | `invalid_post_details` | `post-details set` got something other than text for a field. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`. |
719
+ | `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
715
720
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
716
721
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
717
722
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
@@ -722,7 +727,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
722
727
  | `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
723
728
  | `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
724
729
  | `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
725
- | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
730
+ | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). The first plan is free but still needs at least 1 credit remaining (`details.free: true`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
726
731
  | `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
727
732
  | `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
728
733
  | `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |