@siteoshq/cli 1.12.0 → 1.13.0

package/README.md

@@ -1,7 +1,7 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace, SEO/GEO and Integrations. This source is version 1.11.0; source changes require a separate release to reach npm.
+Search, Trace, SEO/GEO and Integrations. This source is version 1.13.0; source changes require a separate release to reach npm.
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -205,6 +205,10 @@ Research and GSC Insights use these commands with a matching server release:
 siteos seo research summary --json
 siteos seo research history --kind keywords --json
 siteos seo research show <run-id> --json
+siteos seo research serp show <run-id> --keyword "website analytics" --json
+siteos seo research serp ensure <run-id> --keyword "website analytics" --json
+siteos seo research serp wait <run-id> --keyword "website analytics" --json
+siteos seo research serp export <run-id> --keyword "website analytics" --format json --output ./serp-report.json --json
 siteos seo research plan --input ./research-request.json --json
 siteos seo research run --input ./research-request.json --idempotency-key <retry-key> --json
 siteos seo research wait <run-id> --json
@@ -219,6 +223,8 @@ Research supports keywords, Domain Overview (`domain`), rankings, backlinks, bra
 Domain Overview collects domain totals, up to 100 ranking keywords, pages and competitors for a market.
 `--kind domain` includes legacy `competitors` history; existing `competitors` inputs keep their original two-part plan.
 New request example: `{"kind":"domain","target":"example.com","country":"US","language":"en"}`.
+SERP `ensure` collects at most one saved snapshot per returned keyword and Keyword Research report. Repeat calls reuse the saved job, including failures. SERP show/wait/export only read; market and device come from the parent report.
+
 Reading/planning/saving spends no research credits. Launch uses Organization credits and the same
 server admission as the interface. Keep the retry key after an uncertain response; no paid retries
 are automatic. Wait exit 3 means pending; exit 4 failed/cancelled. Partial evidence remains readable.

package/dist/cli.js

@@ -10516,6 +10516,10 @@ var RESEARCH_HELP = `
   siteos seo research wait <run-id> [--timeout <seconds>] [--environment <slug>] [--json]
   siteos seo research cancel <run-id> [--environment <slug>] [--json]
   siteos seo research export <run-id> --format <json|csv> --output <new-file> [--environment <slug>] [--json]
+  siteos seo research serp show <run-id> --keyword <word> [--environment <slug>] [--json]
+  siteos seo research serp ensure <run-id> --keyword <word> [--environment <slug>] [--json]
+  siteos seo research serp wait <run-id> --keyword <word> [--timeout <seconds>] [--environment <slug>] [--json]
+  siteos seo research serp export <run-id> --keyword <word> --format <json|csv> --output <new-file> [--environment <slug>] [--json]
   siteos seo research saved list --kind <kind> [--environment <slug>] [--json]
   siteos seo research saved save --input <request.json> --name <name> [--id <saved-id>] [--environment <slug>] [--json]
   siteos seo research saved remove <saved-id> [--environment <slug>] [--json]
@@ -10529,6 +10533,7 @@ Markets: US, GB, ES, DE, FR, CA, AU. Languages: en, es, de, fr, pt, it, nl, ru.
 Platforms: chat_gpt, claude, gemini, perplexity. Brand lookup uses brandPlatform chat_gpt|google and brandMatch domain|brand.
 Plan validates the request and shows planned parts and available research credits without enqueueing work.
 Run consumes Organization research credits through the same worker as the interface. Preserve the retry key after an uncertain response.
+SERP ensure collects one saved organic snapshot for a keyword returned by the selected completed Keyword Research report. It uses research credits once; repeating the same report/word returns the saved job, including failures. Show/wait/export only read and never spend. New reports can collect fresh snapshots.
 History returns the latest 30 checks per kind; show/export can address older retained run IDs. Saved checks are limited to 100 per resource.
 Wait defaults to 120 seconds (maximum 900); exit 3 means still pending, exit 4 means failed or cancelled. Partial evidence stays accessible.
 Exports preserve scope, dates and partial state. CSV stores one dataset row as JSON per row, including failed parts; it never converts missing metrics to zero.
@@ -10569,6 +10574,7 @@ async function runSeoResearchCommand(options) {
         json: { type: "boolean" },
         environment: { type: "string" },
         kind: { type: "string" },
+        keyword: { type: "string" },
         input: { type: "string" },
         name: { type: "string" },
         id: { type: "string" },
@@ -10578,9 +10584,13 @@ async function runSeoResearchCommand(options) {
         output: { type: "string" }
       }
     });
-    const action = positionals[0] === "saved" ? positionals.slice(0, 2).join(" ") : positionals[0] ?? "";
-    const id = positionals[action.startsWith("saved ") ? 2 : 1];
+    const action = ["saved", "serp"].includes(positionals[0] ?? "") ? positionals.slice(0, 2).join(" ") : positionals[0] ?? "";
+    const id = positionals[action.includes(" ") ? 2 : 1];
     const operations = {
+      "serp show": { args: 3, flags: ["keyword"] },
+      "serp ensure": { args: 3, flags: ["keyword"] },
+      "serp wait": { args: 3, flags: ["keyword", "timeout"] },
+      "serp export": { args: 3, flags: ["keyword", "format", "output"] },
       summary: { args: 1, flags: [] },
       status: { args: 1, flags: ["kind"] },
       history: { args: 1, flags: ["kind"] },
@@ -10601,6 +10611,10 @@ async function runSeoResearchCommand(options) {
       throw new Error(
         "Invalid research operation or flags. Run siteos seo --help."
       );
+    if (action.startsWith("serp ") && (!values.keyword?.trim() || values.keyword.length > 200))
+      throw new Error(
+        "Provide --keyword with 1 to 200 characters from the selected keyword report."
+      );
     if (values.kind === "domain") values.kind = "competitors";
     if (operation.flags.includes("kind") && !kinds.includes(values.kind))
       throw new Error("Choose a documented --kind.");
@@ -10613,7 +10627,7 @@ async function runSeoResearchCommand(options) {
     const timeout = Number(values.timeout ?? 120);
     if (!Number.isInteger(timeout) || timeout < 1 || timeout > 900)
       throw new Error("Use a wait timeout between 1 and 900 seconds.");
-    if (action === "export" && (!values.output || !["json", "csv"].includes(values.format ?? "")))
+    if (["export", "serp export"].includes(action) && (!values.output || !["json", "csv"].includes(values.format ?? "")))
       throw new Error(
         "Export requires --format json|csv and --output for a new file."
       );
@@ -10665,6 +10679,109 @@ async function runSeoResearchCommand(options) {
     );
     const query = `?kind=${encodeURIComponent(values.kind ?? "rankings")}`;
     let record;
+    if (action.startsWith("serp ")) {
+      const snapshotSchema = z19.object({
+        id: z19.string(),
+        organizationId: z19.literal(client.organizationId),
+        resourceId: z19.literal(client.resourceId),
+        sourceRunId: z19.literal(id),
+        request: requestSchema,
+        keywordKey: z19.literal(
+          values.keyword.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, " ")
+        ),
+        state: z19.enum([
+          "queued",
+          "running",
+          "completed",
+          "failed",
+          "cancelled"
+        ]),
+        dataset: z19.object({
+          type: z19.literal("serp"),
+          keyword: z19.string(),
+          country: z19.string(),
+          language: z19.string(),
+          device: z19.enum(["desktop", "mobile"]),
+          observedAt: z19.string(),
+          rows: z19.array(
+            z19.object({
+              position: z19.number(),
+              title: z19.string(),
+              url: z19.string(),
+              domain: z19.string(),
+              description: z19.string()
+            })
+          )
+        }).nullable()
+      }).passthrough();
+      const suffix = `/runs/${encodeURIComponent(id)}/serp`;
+      const read = () => get(`${suffix}?keyword=${encodeURIComponent(values.keyword)}`);
+      record = action === "serp ensure" ? await get(suffix, "run", { keyword: values.keyword }) : await read();
+      const deadline = Date.now() + timeout * 1e3;
+      let snapshot = record.serp == null ? null : snapshotSchema.parse(record.serp);
+      if (action === "serp ensure" && !snapshot)
+        throw new Error(
+          "The server did not return the admitted SERP snapshot."
+        );
+      while (action === "serp wait" && snapshot && ["queued", "running"].includes(snapshot.state)) {
+        if (Date.now() >= deadline)
+          return {
+            exitCode: 3,
+            stdout: JSON.stringify({ ...record, timedOut: true }, null, 2)
+          };
+        await setTimeout2(Math.min(2e3, Math.max(0, deadline - Date.now())));
+        record = await read();
+        snapshot = record.serp == null ? null : snapshotSchema.parse(record.serp);
+      }
+      if (action === "serp export") {
+        if (!snapshot)
+          throw new Error("No saved SERP exists for this report and keyword.");
+        const data = snapshot.dataset;
+        const content = values.format === "json" ? JSON.stringify(record, null, 2) : [
+          [
+            "report_id",
+            "keyword",
+            "country",
+            "language",
+            "device",
+            "state",
+            "observed_at",
+            "error",
+            "position",
+            "title",
+            "url",
+            "description"
+          ],
+          ...(data?.rows.length ? data.rows : [null]).map((row) => [
+            id,
+            values.keyword,
+            data?.country,
+            data?.language,
+            data?.device,
+            snapshot.state,
+            data?.observedAt,
+            snapshot.error,
+            row?.position,
+            row?.title,
+            row?.url,
+            row?.description
+          ])
+        ].map((row) => row.map(csvCell).join(",")).join("\r\n");
+        const output = await writeSeoReport(options, values.output, content);
+        record = {
+          contractVersion: 1,
+          runId: id,
+          keyword: values.keyword,
+          state: snapshot.state,
+          format: values.format,
+          output
+        };
+      }
+      return {
+        exitCode: action === "serp wait" && (!snapshot || ["failed", "cancelled"].includes(snapshot.state)) ? 4 : 0,
+        stdout: JSON.stringify(record, null, 2)
+      };
+    }
     if (action === "plan" || action === "run" || action === "saved save") {
       const plan = await get("/plan", "read", input);
       resourceSchema.parse(plan.resource);