@clickminded/coauthor-cli 0.0.69 → 0.0.71

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/dist/commands.js CHANGED
@@ -1969,6 +1969,7 @@ async function runProfileCommand(action, input, client) {
1969
1969
  throw new Error('Usage: coauthor profile <list|show|update>');
1970
1970
  }
1971
1971
  const WIDGET_EDIT_INSTRUCTION_MAX_CHARS = 500;
1972
+ const WIDGET_SCENE_NOTICE_TEXT = 'Add an OpenAI key in AI settings to get illustrated interactives.';
1972
1973
  function widgetList(data) {
1973
1974
  const value = getResponseValue(data, 'widgets');
1974
1975
  return Array.isArray(value)
@@ -2015,6 +2016,8 @@ function describeWidget(widget, options = {}) {
2015
2016
  }
2016
2017
  if (widget.fact_check_warning)
2017
2018
  lines.push(` fact check: ${String(widget.fact_check_warning)}`);
2019
+ if (widget.scene_notice === 'byok_no_openai_key')
2020
+ lines.push(` ${WIDGET_SCENE_NOTICE_TEXT}`);
2018
2021
  const error = widgetError(widget);
2019
2022
  if (error)
2020
2023
  lines.push(` error: ${String(error.code)}: ${String(error.message)}`);
@@ -2299,6 +2302,8 @@ function httpErrorCode(error) {
2299
2302
  const code = planRecord(body.error).code;
2300
2303
  return typeof code === 'string' ? code : null;
2301
2304
  }
2305
+ /** Post types the plan gives to link magnets: reference posts other sites link to as a source. */
2306
+ const SEO_PLAN_LINK_MAGNET_POST_TYPES = ['stats_hub', 'regulation_tracker', 'cost_reference'];
2302
2307
  function seoPlanItemLine(item) {
2303
2308
  const keyword = planString(item, 'primary_keyword');
2304
2309
  const title = planString(item, 'title') ?? keyword ?? '(untitled)';
@@ -2308,7 +2313,9 @@ function seoPlanItemLine(item) {
2308
2313
  planString(item, 'chance'),
2309
2314
  ].filter(Boolean).join(', ');
2310
2315
  const id = planString(item, 'id') ?? '';
2311
- const head = ` ${id} ${title}`;
2316
+ const postType = planString(item, 'post_type');
2317
+ const linkMagnet = (item.kind === undefined || item.kind === 'post') && postType !== null && SEO_PLAN_LINK_MAGNET_POST_TYPES.includes(postType) ? '[link magnet] ' : '';
2318
+ const head = ` ${id} ${linkMagnet}${title}`;
2312
2319
  const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
2313
2320
  const where = planString(item, 'existing_url');
2314
2321
  const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.69",
3
+ "version": "0.0.71",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -23,7 +23,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
23
23
  ```
24
24
 
25
25
  - `list` returns `data.widgets` (each with `id`, `spec.title`, `spec.aha`, `spec.move`, `spec.visual`, `credit_cap`, `edit_credit_cap`, `replaces_image`, `build_state`, `current_version`, `embed_url`, and `error` when a build failed), `data.availability` (`canBuild` and the reason when not), and `data.model` (the build model and its cap). A placeholder has `current_version: null` and `build_state: "idle"`.
26
- - `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build takes a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
26
+ - `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build usually takes 1-4 minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
27
27
  - `build-all` with no ids builds every placeholder; with ids, only those.
28
28
  - `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
29
29
  - `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
@@ -37,6 +37,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
37
37
  - **WordPress:** live embeds need a WordPress user who can post unfiltered HTML. Otherwise they export as images linked to the live version, and WordPress may strip embeds on save, which also falls back to the linked image.
38
38
  - **Own API keys (Pro):** when included credits run low and the user builds with their own keys, interactives need an Anthropic API key (`widget_requires_anthropic_key`). They add it in CoAuthor's AI settings, never in chat.
39
39
  - **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
40
+ - **Illustrated interactives:** a built widget may carry `scene_notice: "byok_no_openai_key"` (null otherwise). It means the build used the user's own keys and has no OpenAI key, so the interactive was built without illustrations. Tell the user: Add an OpenAI key in AI settings to get illustrated interactives. They add it in CoAuthor's AI settings, never in chat.
40
41
  - Interactives never appear in unbuilt form: placeholders are left out of every export.
41
42
 
42
43
  Error codes: `references/troubleshooting.md`.
@@ -52,6 +52,18 @@ Each item has a `kind`, which decides what you can do with it:
52
52
  | `covered` | The site already ranks well for it. | Nothing. |
53
53
  | `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
54
54
 
55
+ ### Link magnets
56
+
57
+ Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
58
+
59
+ - `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
60
+ - `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
61
+ - `cost_reference`: a price or cost reference, with where each figure comes from.
62
+
63
+ They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
64
+
65
+ Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
66
+
55
67
  Other fields to use when you recommend an idea:
56
68
 
57
69
  - `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
@@ -421,7 +421,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
421
421
  ```
422
422
 
423
423
  - `list` returns `data.widgets` (each with `id`, `spec.title`, `spec.aha`, `spec.move`, `spec.visual`, `credit_cap`, `edit_credit_cap`, `replaces_image`, `build_state`, `current_version`, `embed_url`, and `error` when a build failed), `data.availability` (`canBuild` and the reason when not), and `data.model` (the build model and its cap). A placeholder has `current_version: null` and `build_state: "idle"`.
424
- - `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build takes a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
424
+ - `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build usually takes 1-4 minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
425
425
  - `build-all` with no ids builds every placeholder; with ids, only those.
426
426
  - `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
427
427
  - `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
@@ -435,6 +435,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
435
435
  - **WordPress:** live embeds need a WordPress user who can post unfiltered HTML. Otherwise they export as images linked to the live version, and WordPress may strip embeds on save, which also falls back to the linked image.
436
436
  - **Own API keys (Pro):** when included credits run low and the user builds with their own keys, interactives need an Anthropic API key (`widget_requires_anthropic_key`). They add it in CoAuthor's AI settings, never in chat.
437
437
  - **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
438
+ - **Illustrated interactives:** a built widget may carry `scene_notice: "byok_no_openai_key"` (null otherwise). It means the build used the user's own keys and has no OpenAI key, so the interactive was built without illustrations. Tell the user: Add an OpenAI key in AI settings to get illustrated interactives. They add it in CoAuthor's AI settings, never in chat.
438
439
  - Interactives never appear in unbuilt form: placeholders are left out of every export.
439
440
 
440
441
  Error codes: `references/troubleshooting.md`.
@@ -646,6 +647,18 @@ Each item has a `kind`, which decides what you can do with it:
646
647
  | `covered` | The site already ranks well for it. | Nothing. |
647
648
  | `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
648
649
 
650
+ #### Link magnets
651
+
652
+ Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
653
+
654
+ - `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
655
+ - `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
656
+ - `cost_reference`: a price or cost reference, with where each figure comes from.
657
+
658
+ They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
659
+
660
+ Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
661
+
649
662
  Other fields to use when you recommend an idea:
650
663
 
651
664
  - `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.