@clickminded/coauthor-cli 0.0.36 → 0.0.37

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.
@@ -10,6 +10,7 @@ export type CommandContext = {
10
10
  token: string;
11
11
  };
12
12
  export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
13
+ export declare function describeImageOperation(operation: JsonValue | undefined): string | null;
13
14
  export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?: (line: string) => void): void;
14
15
  /**
15
16
  * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
package/dist/commands.js CHANGED
@@ -782,6 +782,9 @@ async function runResourceCommand(resource, action, input, client) {
782
782
  if (getString(input.values, 'prompt') !== undefined) {
783
783
  throw new Error('--prompt steers one image: use it with --placeholder-id <id>, not --all.');
784
784
  }
785
+ if (getString(input.values, 'idempotency-key') !== undefined) {
786
+ throw new Error('--idempotency-key names one image job: use it with --placeholder-id <id>, not --all (each image gets its own key in data.operations).');
787
+ }
785
788
  return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
786
789
  }
787
790
  if (resource === 'images' && resolvedAction === 'metadata') {
@@ -830,9 +833,39 @@ async function runResourceCommand(resource, action, input, client) {
830
833
  'edit-prompt',
831
834
  ]);
832
835
  const path = resolvedAction === 'create' && resource !== 'threads' ? basePath : `${basePath}/${resolvedAction}`;
836
+ if (resource === 'images' && (resolvedAction === 'generate' || resolvedAction === 'edit')) {
837
+ return imageOperationRequest(client, input, projectId, path, body, resolvedAction);
838
+ }
833
839
  const data = await client.request({ method: 'POST', path, body });
834
840
  return { ok: true, data };
835
841
  }
842
+ // Image generate/edit is recorded as an image.generate/image.edit operation
843
+ // under its Idempotency-Key: print the key so the caller can follow the job
844
+ // to the finished image (`operation status`) or retry it safely.
845
+ async function imageOperationRequest(client, input, projectId, path, body, action) {
846
+ const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
847
+ const data = await client.request({ method: 'POST', path, body, idempotencyKey });
848
+ const operation = getResponseValue(data, 'operation');
849
+ // A server without image operations returns only the job.
850
+ if (!operation || typeof operation !== 'object' || Array.isArray(operation))
851
+ return { ok: true, data };
852
+ const lookup = `Operation key: ${idempotencyKey} (coauthor operation status ${idempotencyKey} --json).`;
853
+ if (getResponseValue(data, 'replayed') === true) {
854
+ const status = typeof operation.status === 'string' ? operation.status : 'unknown';
855
+ return {
856
+ ok: true,
857
+ message: `Replayed recorded image ${action} operation (${status}); no new job was queued. ${lookup}`,
858
+ idempotency_key: idempotencyKey,
859
+ data,
860
+ };
861
+ }
862
+ return {
863
+ ok: true,
864
+ message: `Image ${action === 'edit' ? 'edit' : 'generation'} queued. ${lookup} Or poll coauthor image status ${projectId} --json.`,
865
+ idempotency_key: idempotencyKey,
866
+ data,
867
+ };
868
+ }
836
869
  // Publish and export run as recorded operations keyed by the Idempotency-Key.
837
870
  // Print the key so the caller can look the outcome up (`operation status`) or
838
871
  // replay the same request safely with --idempotency-key.
@@ -888,15 +921,37 @@ function exportRequestBody(action, input) {
888
921
  async function runOperationCommand(action, input, client) {
889
922
  const key = getString(input.values, 'id') ?? input.positionals[0];
890
923
  if (!action || action === 'list') {
891
- return { ok: true, data: await client.request({ path: 'operations' }) };
924
+ const projectId = getString(input.values, 'project');
925
+ const path = projectId ? `operations?project_id=${encodeURIComponent(projectId)}` : 'operations';
926
+ return { ok: true, data: await client.request({ path }) };
892
927
  }
893
928
  if (action === 'show' || action === 'status') {
894
929
  if (!key)
895
930
  throw new Error('Usage: coauthor operation status <operationKey>');
896
- return { ok: true, data: await client.request({ path: `operations/${encodeURIComponent(key)}` }) };
931
+ const data = await client.request({ path: `operations/${encodeURIComponent(key)}` });
932
+ const message = describeImageOperation(getResponseValue(data, 'operation'));
933
+ return message ? { ok: true, message, data } : { ok: true, data };
897
934
  }
898
935
  throw new Error('Usage: coauthor operation <list|show|status>');
899
936
  }
937
+ // One line for an image.generate/image.edit operation, e.g.
938
+ // "image.generate succeeded: https://...". Other operations print as before.
939
+ export function describeImageOperation(operation) {
940
+ if (!operation || typeof operation !== 'object' || Array.isArray(operation))
941
+ return null;
942
+ const action = typeof operation.action === 'string' ? operation.action : '';
943
+ if (action !== 'image.generate' && action !== 'image.edit')
944
+ return null;
945
+ const status = typeof operation.status === 'string' ? operation.status : 'unknown';
946
+ const result = operation.result && typeof operation.result === 'object' && !Array.isArray(operation.result) ? operation.result : {};
947
+ const error = typeof operation.error_message === 'string' ? operation.error_message : null;
948
+ if (status === 'succeeded') {
949
+ return typeof result.final_image_url === 'string' ? `${action} succeeded: ${result.final_image_url}` : `${action} succeeded.`;
950
+ }
951
+ if (status === 'running' || status === 'pending')
952
+ return `${action} running: the image is still generating. Check again shortly.`;
953
+ return error ? `${action} ${status}: ${error}` : `${action} ${status}.`;
954
+ }
900
955
  const SKILL_NAMES = ['claude', 'codex', 'agents', 'cursor'];
901
956
  const AGENT_LABELS = {
902
957
  claude: 'Claude Code',
@@ -2125,11 +2180,15 @@ async function generateAllImages(client, projectId, wait) {
2125
2180
  const before = imageStatusRows(await client.request({ path: statusPath }));
2126
2181
  const toGenerate = before.filter((row) => row.status !== 'done' && row.status !== 'generating');
2127
2182
  const started = [];
2183
+ const operations = [];
2128
2184
  const failedToStart = [];
2129
2185
  for (const row of toGenerate) {
2186
+ // Each image is its own recorded operation (coauthor operation status <key>).
2187
+ const idempotencyKey = randomUUID();
2130
2188
  try {
2131
- await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id } });
2189
+ await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id }, idempotencyKey });
2132
2190
  started.push(row.id);
2191
+ operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
2133
2192
  }
2134
2193
  catch (error) {
2135
2194
  failedToStart.push({ id: row.id, error: error instanceof Error ? error.message : String(error) });
@@ -2154,6 +2213,7 @@ async function generateAllImages(client, projectId, wait) {
2154
2213
  failed: wait ? count('failed') : null,
2155
2214
  generating,
2156
2215
  failed_to_start: failedToStart,
2216
+ operations,
2157
2217
  };
2158
2218
  return {
2159
2219
  ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
@@ -2372,7 +2432,7 @@ export function helpResult(command = []) {
2372
2432
  ' slideshow show|save',
2373
2433
  ' publish thread (supports --idempotency-key)',
2374
2434
  ' export list|wordpress (supports --idempotency-key)',
2375
- ' operation list|show|status',
2435
+ ' operation list|show|status (publish, export and image generate/edit)',
2376
2436
  ' credits',
2377
2437
  ' share <project-id>',
2378
2438
  ' models list|preferences show|preferences set',
@@ -2599,18 +2659,28 @@ function commandHelp(command) {
2599
2659
  'show: status and the proposed groups. apply: keep every group, or only --accept / all but --reject. discard: drop the revision (cancels it if still running).',
2600
2660
  ].join('\n'),
2601
2661
  'image generate': [
2602
- 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
2662
+ 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
2603
2663
  '',
2604
2664
  'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
2605
2665
  'Images are drawn from the planned brief. --prompt replaces what the image shows (the planned scene, its required elements and, on photo + doodle images, the planned doodles)',
2606
2666
  'and is saved, so later regenerations keep it;',
2607
2667
  'the profile\'s visual style still applies. Comparison and technical-diagram images have no scene to replace: generate them, then use image edit --edit-prompt.',
2608
2668
  'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
2669
+ 'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
2670
+ '--idempotency-key <key> replays an earlier request with that key instead of queueing a second job. With --all, each image gets its own key (data.operations).',
2609
2671
  ].join('\n'),
2610
2672
  'image edit': [
2611
- 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--json]',
2673
+ 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
2612
2674
  '',
2613
2675
  'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
2676
+ 'Prints an operation key: coauthor operation status <key> reports the edited image url or the error; --idempotency-key <key> replays instead of editing twice.',
2677
+ ].join('\n'),
2678
+ operation: [
2679
+ 'Usage: coauthor operation list [--project <project-id>] [--json]',
2680
+ ' coauthor operation status <key> [--json] (show is the same)',
2681
+ '',
2682
+ 'Recorded publish, export and image generate/edit requests, looked up by the operation key the command printed.',
2683
+ 'Image operations report succeeded (with data.operation.result.final_image_url), running, failed (with error_message), or unknown (superseded or cleared before it finished).',
2614
2684
  ].join('\n'),
2615
2685
  'contract save': [
2616
2686
  'Usage: coauthor contract save <project-id> --data @contract.json [--json]',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.36",
3
+ "version": "0.0.37",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -8,6 +8,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
8
8
  2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
9
9
  3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
10
10
  - To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
11
+ - Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
11
12
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
12
13
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
13
14
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
@@ -32,7 +32,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
32
32
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
33
33
  | `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 "..."`. |
34
34
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
35
- | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
35
+ | `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. |
36
36
 
37
37
  ## Sign-in
38
38
 
@@ -337,6 +337,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
337
337
  2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
338
338
  3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
339
339
  - To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
340
+ - Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
340
341
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
341
342
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
342
343
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
@@ -511,7 +512,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
511
512
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
512
513
  | `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 "..."`. |
513
514
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
514
- | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
515
+ | `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. |
515
516
 
516
517
  ### Sign-in
517
518