@clickminded/coauthor-cli 0.0.62 → 0.0.64
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
|
@@ -94,7 +94,7 @@ coauthor seo-plan write <item-id> --json # open a project
|
|
|
94
94
|
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
|
95
95
|
coauthor seo-plan done <item-id> --json # mark an idea done, e.g. after improving the page (--undo clears it)
|
|
96
96
|
coauthor seo-plan monthly-check on|off --json # switch the plan's monthly rank check (uses credits; the first check is free)
|
|
97
|
-
coauthor seo-plan results --json # where each
|
|
97
|
+
coauthor seo-plan results --json # where each tracked post ranks after the last monthly check, and which posts have no live address yet
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
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
|
@@ -2454,6 +2454,21 @@ function seoPlanWaitFailure(status) {
|
|
|
2454
2454
|
};
|
|
2455
2455
|
}
|
|
2456
2456
|
// Polls the plan's status (capped under the 10-minute agent shell limit) until it stops queued/running.
|
|
2457
|
+
/**
|
|
2458
|
+
* "#3 in line, starts in about 16 min" for a plan that has not started yet, from the status route's queue
|
|
2459
|
+
* fields; "#3 in line, starts when free plans resume" while its queue is paused (`queue_paused`, no ETA).
|
|
2460
|
+
*/
|
|
2461
|
+
function seoPlanQueueNote(status) {
|
|
2462
|
+
const position = status.queue_position;
|
|
2463
|
+
const eta = status.queue_eta_minutes;
|
|
2464
|
+
if (status.status !== 'queued' || typeof position !== 'number')
|
|
2465
|
+
return null;
|
|
2466
|
+
if (status.queue_paused === true)
|
|
2467
|
+
return `#${position} in line, starts when free plans resume`;
|
|
2468
|
+
if (typeof eta !== 'number')
|
|
2469
|
+
return null;
|
|
2470
|
+
return `#${position} in line, starts in about ${eta} min`;
|
|
2471
|
+
}
|
|
2457
2472
|
async function waitForSeoPlan(client, profileId, started) {
|
|
2458
2473
|
const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
|
|
2459
2474
|
const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
|
|
@@ -2465,7 +2480,7 @@ async function waitForSeoPlan(client, profileId, started) {
|
|
|
2465
2480
|
status = planRecord(await client.request({ path: statusPath }));
|
|
2466
2481
|
}
|
|
2467
2482
|
if (status.done !== true) {
|
|
2468
|
-
const step = planString(planRecord(status.progress), 'step') ?? planString(planRecord(status.progress), 'label');
|
|
2483
|
+
const step = seoPlanQueueNote(status) ?? planString(planRecord(status.progress), 'step') ?? planString(planRecord(status.progress), 'label');
|
|
2469
2484
|
return {
|
|
2470
2485
|
ok: false,
|
|
2471
2486
|
status: 'still_running',
|
|
@@ -3574,7 +3589,7 @@ function commandHelp(command) {
|
|
|
3574
3589
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3575
3590
|
'done marks an idea as done (for example after you improved the page); --undo clears the mark. A done idea stays in the plan and stays done when the plan is updated.',
|
|
3576
3591
|
'monthly-check on|off switches the plan\'s monthly check (free). Once a month it re-checks where each published post ranks on Google, refreshes the plan\'s ranking data and chances, and uses credits (the first check is free). show prints its state: enabled, next_check_at and about how many credits a month. It is absent while monthly checks are not switched on for the account. Turning it on picks the next date at least 25 days after the last check.',
|
|
3577
|
-
'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the
|
|
3592
|
+
'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the posts that have a target search but no live address yet (except ones marked as still being edited), and why the last check did less than a full job. --json returns data.results, data.missing_urls, data.last_check and data.monthly_check. Without monthly checks switched on for the account there are no results. A post is tracked once it has a target search and a live address: set one with `coauthor post-details set <project-id> --live-url <url>`.',
|
|
3578
3593
|
'Errors: not_enabled, profile_not_found, profile_archived, site_required, site_indexing, market_confirmation_needed, market_not_supported, insufficient_credits, plan_running, worker_unavailable, plan_stale, plan_updated, not_writable, plan_item_not_found.',
|
|
3579
3594
|
].join('\n'),
|
|
3580
3595
|
integrations: [
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -71,7 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
71
71
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
72
72
|
- `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
|
|
73
73
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
74
|
-
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the
|
|
74
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts that have a target search but no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
75
75
|
|
|
76
76
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
77
77
|
|
|
@@ -33,6 +33,7 @@ coauthor seo-plan results [--profile <id>] --json
|
|
|
33
33
|
|
|
34
34
|
- 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.
|
|
35
35
|
- `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).
|
|
36
|
+
- Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
|
|
36
37
|
- `--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.
|
|
37
38
|
- `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.
|
|
38
39
|
- 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.
|
|
@@ -89,7 +90,7 @@ Posts are only tracked once their live URL is known: set it with `coauthor post-
|
|
|
89
90
|
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
90
91
|
|
|
91
92
|
- `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
92
|
-
- `data.missing_urls` lists
|
|
93
|
+
- `data.missing_urls` lists posts that have a target search but no live address (`project_id`, `title`, `keyword`, `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
|
|
93
94
|
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
94
95
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
95
96
|
|
|
@@ -73,7 +73,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
73
73
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
74
74
|
- `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
|
|
75
75
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
76
|
-
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the
|
|
76
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts that have a target search but no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
77
77
|
|
|
78
78
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
79
79
|
|
|
@@ -619,6 +619,7 @@ coauthor seo-plan results [--profile <id>] --json
|
|
|
619
619
|
|
|
620
620
|
- 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.
|
|
621
621
|
- `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).
|
|
622
|
+
- Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
|
|
622
623
|
- `--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.
|
|
623
624
|
- `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.
|
|
624
625
|
- 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.
|
|
@@ -675,7 +676,7 @@ Posts are only tracked once their live URL is known: set it with `coauthor post-
|
|
|
675
676
|
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
676
677
|
|
|
677
678
|
- `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
678
|
-
- `data.missing_urls` lists
|
|
679
|
+
- `data.missing_urls` lists posts that have a target search but no live address (`project_id`, `title`, `keyword`, `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
|
|
679
680
|
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
680
681
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
681
682
|
|