@clickminded/coauthor-cli 0.0.56 → 0.0.57

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
@@ -91,6 +91,7 @@ coauthor seo-plan generate --wait --json # SEO content pla
91
91
  coauthor seo-plan show --kind post --json # strategy, Do next moves, counts, and the post ideas
92
92
  coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
93
93
  coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
94
+ coauthor seo-plan done <item-id> --json # mark an idea done, e.g. after improving the page (--undo clears it)
94
95
  ```
95
96
 
96
97
  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
@@ -2219,6 +2219,7 @@ const SEO_PLAN_USAGE = [
2219
2219
  ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
2220
2220
  ' coauthor seo-plan write <item-id> [--json]',
2221
2221
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
2222
+ ' coauthor seo-plan done <item-id> [--undo] [--json]',
2222
2223
  ].join('\n');
2223
2224
  function planRecord(value) {
2224
2225
  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -2260,8 +2261,9 @@ function seoPlanItemLine(item) {
2260
2261
  const hint = planString(item, 'improve_hint') ?? planString(item, 'reason') ?? planString(item, 'note');
2261
2262
  const written = planString(item, 'project_id') ? ` -> project ${planString(item, 'project_id')}` : '';
2262
2263
  const dismissed = item.dismissed === true ? ' (dismissed)' : '';
2264
+ const done = planString(item, 'done_at') ? ' (done)' : '';
2263
2265
  return [
2264
- `${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}`,
2266
+ `${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}${done}`,
2265
2267
  where ? ` ${where}${position}` : null,
2266
2268
  hint ? ` ${hint}` : null,
2267
2269
  ].filter(Boolean).join('\n');
@@ -2361,7 +2363,7 @@ async function waitForSeoPlan(client, profileId, started) {
2361
2363
  };
2362
2364
  }
2363
2365
  async function runSeoPlanCommand(action, input, client) {
2364
- if (!action || !['show', 'generate', 'write', 'dismiss'].includes(action))
2366
+ if (!action || !['show', 'generate', 'write', 'dismiss', 'done'].includes(action))
2365
2367
  throw new Error(SEO_PLAN_USAGE);
2366
2368
  if (action === 'show') {
2367
2369
  const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
@@ -2440,6 +2442,24 @@ async function runSeoPlanCommand(action, input, client) {
2440
2442
  data,
2441
2443
  };
2442
2444
  }
2445
+ if (action === 'done') {
2446
+ if (!itemId)
2447
+ throw new Error('Usage: coauthor seo-plan done <item-id> [--undo]');
2448
+ const undoDone = getBoolean(input.values, 'undo');
2449
+ const data = await client.request({
2450
+ method: 'POST',
2451
+ path: `seo-plan/items/${encodeURIComponent(itemId)}/done`,
2452
+ body: { done: !undoDone },
2453
+ });
2454
+ return {
2455
+ ok: true,
2456
+ message: undoDone
2457
+ ? `Cleared the done mark on ${itemId}.`
2458
+ : `Marked ${itemId} as done. Clear it with \`coauthor seo-plan done ${itemId} --undo\`.`,
2459
+ messageIncludesData: true,
2460
+ data,
2461
+ };
2462
+ }
2443
2463
  if (!itemId)
2444
2464
  throw new Error('Usage: coauthor seo-plan dismiss <item-id> [--undo]');
2445
2465
  const undo = getBoolean(input.values, 'undo');
@@ -3257,7 +3277,7 @@ export function helpResult(command = []) {
3257
3277
  ' profile list|show|update (update: --interactive-widgets on|off)',
3258
3278
  ' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
3259
3279
  ' site status|reindex [--profile <profile-id>] (limited rollout)',
3260
- ' seo-plan show|generate|write|dismiss (limited rollout)',
3280
+ ' seo-plan show|generate|write|dismiss|done (limited rollout)',
3261
3281
  ' source list|add|remove',
3262
3282
  ' integrations list',
3263
3283
  ' log add|show',
@@ -3394,12 +3414,14 @@ function commandHelp(command) {
3394
3414
  ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
3395
3415
  ' coauthor seo-plan write <item-id> [--json]',
3396
3416
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
3417
+ ' coauthor seo-plan done <item-id> [--undo] [--json]',
3397
3418
  '',
3398
3419
  'SEO content plan (limited rollout): a business-wide keyword plan for a writer profile, built from live search data and the profile\'s website. Without --profile it uses the default profile.',
3399
3420
  'show prints the strategy, the Do next moves, counts per kind, and the ideas of one kind (default post). Kinds: post (written post ideas), improve (existing pages to improve), page (page ideas, not blog posts), left_out (searches skipped, with a reason), covered, not_checked.',
3400
3421
  'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running; run the same command again to keep waiting.',
3401
3422
  'write <item-id> opens a project for a post idea, already set up from the plan, and prints its id and the start prompt. Continue with the normal project flow. Writing the same idea again returns the same project.',
3402
3423
  'dismiss hides an idea from the plan; --undo brings it back.',
3424
+ '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.',
3403
3425
  '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.',
3404
3426
  ].join('\n'),
3405
3427
  integrations: [
package/dist/parser.js CHANGED
@@ -188,7 +188,7 @@ function commandLength(positionals) {
188
188
  if (first === 'site')
189
189
  return second && ['status', 'reindex'].includes(second) ? 2 : 1;
190
190
  if (first === 'seo-plan')
191
- return second && ['show', 'generate', 'write', 'dismiss'].includes(second) ? 2 : 1;
191
+ return second && ['show', 'generate', 'write', 'dismiss', 'done'].includes(second) ? 2 : 1;
192
192
  if (first === 'integrations')
193
193
  return second === 'list' ? 2 : 1;
194
194
  if (first === 'source')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.56",
3
+ "version": "0.0.57",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -69,6 +69,7 @@ When the user wants to know what to write about for a business site, or asks for
69
69
  - `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
70
70
  - `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
71
71
  - `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
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.
72
73
 
73
74
  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.
74
75
 
@@ -14,7 +14,7 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
14
14
 
15
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
16
  - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
17
- - Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
17
+ - 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
18
  - Only one plan runs per account at a time (`plan_running`).
19
19
 
20
20
  ## Commands
@@ -25,6 +25,7 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
25
25
  coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] --json
26
26
  coauthor seo-plan write <item-id> --json
27
27
  coauthor seo-plan dismiss <item-id> [--undo] --json
28
+ coauthor seo-plan done <item-id> [--undo] --json
28
29
  ```
29
30
 
30
31
  - 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.
@@ -40,7 +41,7 @@ Each item has a `kind`, which decides what you can do with it:
40
41
  | `kind` | What it is | What to do |
41
42
  | --- | --- | --- |
42
43
  | `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
43
- | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
44
+ | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says (two or three short sentences, each one concrete change; the edit happens on their site). Mark it done afterwards with `seo-plan done`. |
44
45
  | `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
45
46
  | `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
46
47
  | `covered` | The site already ranks well for it. | Nothing. |
@@ -68,6 +69,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
68
69
 
69
70
  `coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
70
71
 
72
+ ## Mark as done
73
+
74
+ `coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
75
+
71
76
  ## What to tell the user
72
77
 
73
78
  Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
@@ -75,7 +75,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
75
75
  | `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
76
76
  | `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
77
77
  | `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
78
- | `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
78
+ | `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
79
79
  | `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
80
80
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
81
81
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
@@ -71,6 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
71
71
  - `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
72
72
  - `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
73
73
  - `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
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.
74
75
 
75
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.
76
77
 
@@ -593,7 +594,7 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
593
594
 
594
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.
595
596
  - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
596
- - Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
597
+ - 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.
597
598
  - Only one plan runs per account at a time (`plan_running`).
598
599
 
599
600
  ### Commands
@@ -604,6 +605,7 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
604
605
  coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] --json
605
606
  coauthor seo-plan write <item-id> --json
606
607
  coauthor seo-plan dismiss <item-id> [--undo] --json
608
+ coauthor seo-plan done <item-id> [--undo] --json
607
609
  ```
608
610
 
609
611
  - 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.
@@ -619,7 +621,7 @@ Each item has a `kind`, which decides what you can do with it:
619
621
  | `kind` | What it is | What to do |
620
622
  | --- | --- | --- |
621
623
  | `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
622
- | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
624
+ | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says (two or three short sentences, each one concrete change; the edit happens on their site). Mark it done afterwards with `seo-plan done`. |
623
625
  | `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
624
626
  | `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
625
627
  | `covered` | The site already ranks well for it. | Nothing. |
@@ -647,6 +649,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
647
649
 
648
650
  `coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
649
651
 
652
+ ### Mark as done
653
+
654
+ `coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
655
+
650
656
  ### What to tell the user
651
657
 
652
658
  Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
@@ -730,7 +736,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
730
736
  | `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
731
737
  | `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
732
738
  | `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
733
- | `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
739
+ | `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
734
740
  | `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
735
741
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
736
742
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |