@senso-ai/cli 0.14.0 → 0.15.0

package/README.md

@@ -118,7 +118,7 @@ argument and flag, generated from the CLI itself.
 | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | `login` `logout` `whoami`                                                | Authentication and the current organization                         |
 | `search`                                                                 | Ask the knowledge base, with an AI answer, raw chunks, or streaming |
-| `kb` `ingest` `content`                                                  | The knowledge base: upload, browse, organize, verify                |
+| `kb` `ingest` `content` `website-import`                                 | The knowledge base: upload, browse, organize, verify                |
 | `ctas`                                                                   | Call-to-action cards on published pages                             |
 | `generate` `engine` `generated-content` `destinations` `publish-records` | Generate content and publish it                                     |
 | `analytics`                                                              | GEO metrics for your own organization                               |

package/dist/cli.js

@@ -201,6 +201,9 @@ var ApiError = class extends Error {
     this.body = body;
     this.name = "ApiError";
   }
+  status;
+  statusText;
+  body;
 };
 function extractErrorMessage(body, fallback) {
   if (typeof body !== "object" || !body) return fallback;
@@ -934,10 +937,10 @@ function registerOrgCommands(program) {
     })
   );
   org.command("update").description(
-    "Update organization details. All fields are optional \u2014 only provided fields are changed. Pass an empty array for websites/locations to clear them."
+    "Update organization details. Only the fields you pass are changed; omitting a field leaves it alone. But 'websites' and 'locations' REPLACE their whole list when passed \u2014 sending one website deletes the rest. To add to either list, run 'org get' first and send back every entry you want to keep."
   ).requiredOption(
     "--data <json>",
-    'JSON: { "name": "...", "slug": "...", "logo_url": "...", "websites": [...], "locations": [...] }'
+    `JSON: { "name": "Acme", "slug": "acme", "logo_url": "https://acme.com/logo.png", "websites": [{"url": "https://acme.com"}], "locations": [{"country_code": "US", "region_name": "California"}] }. Every field is optional. "websites" and "locations" REPLACE the existing list rather than adding to it \u2014 include every entry you want to keep, or pass [] to clear the list. A website entry takes only "url"; sending the "org_website_id" from 'org get' is rejected. Send "logo_url": "" to clear the logo.`
   ).action(
     runAction(program, async (ctx, cmdOpts) => {
       const body = parseJsonFlag(cmdOpts.data);
@@ -1769,7 +1772,7 @@ function registerIngestCommands(program) {
     "Ingest files into the knowledge base. Upload documents (PDF, TXT, DOCX, etc.) to be parsed, chunked, and embedded for semantic search."
   );
   ingest.command("upload <files...>").description(
-    "Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker. Poll 'senso content get <content-id>' until processing_status is 'complete' before searching the uploaded content."
+    "Upload files to the knowledge base. Accepts local file paths (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker. Poll 'senso kb get <kb-node-id>' until content.processing_status is 'complete' before searching the uploaded content."
   ).option("--folder-id <id>", "Destination folder ID (skip interactive prompt)").action(
     runAction(program, async (ctx, files, cmdOpts) => {
       if (files.length > 10) {
@@ -1868,9 +1871,13 @@ function registerIngestCommands(program) {
           rows: items.map((i) => ({
             filename: i.filename,
             status: i.status,
+            // The id `senso kb get` takes. `content_id` is not interchangeable
+            // with it: polling a KB upload through `senso content get` hits an
+            // endpoint that serves non-KB content only and answers 400.
+            kb_node_id: i.kb_node_id,
             content_id: i.content_id
           })),
-          columns: ["filename", "status", "content_id"]
+          columns: ["filename", "status", "kb_node_id", "content_id"]
         },
         plain: []
       });
@@ -1904,6 +1911,159 @@ function registerIngestCommands(program) {
   );
 }
 
+// src/commands/website-import.ts
+var POLL_INTERVAL_MS = 2e3;
+var IMPORT_TIMEOUT_MS = 18e4;
+var RUN_COLUMNS = [
+  "run_id",
+  "status",
+  "source_url",
+  "pages_fetched",
+  "pages_ingested",
+  "brand_kit_generated"
+];
+function getStatus(ctx) {
+  return apiRequest({
+    path: "/org/website-import/status",
+    apiKey: ctx.apiKey,
+    baseUrl: ctx.baseUrl
+  });
+}
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+async function waitForImport(runId, ctx) {
+  const deadline = Date.now() + IMPORT_TIMEOUT_MS;
+  let lastStatus = "";
+  while (Date.now() < deadline) {
+    const { current, latest_completed: latest } = await getStatus(ctx);
+    if (current && !ctx.quiet && current.status !== lastStatus) {
+      info(`Website import status: ${current.status}`);
+      lastStatus = current.status;
+    }
+    if (!current) {
+      if (latest?.run_id === runId) return latest;
+      throw new CliError(
+        `Website import ${runId} finished but its result could not be read.`,
+        EXIT.ERROR,
+        {
+          hint: "Run `senso website-import status` to see the most recent import."
+        }
+      );
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new CliError(`Timed out waiting for website import ${runId}.`, EXIT.NETWORK, {
+    code: "timeout",
+    hint: "Run `senso website-import status` to check on it."
+  });
+}
+function describeOutcome(run, quiet) {
+  if (quiet) return;
+  if (run.status === "failed") {
+    error(`Website import failed: ${run.error_message ?? "no reason given"}`);
+    if (run.error_code) error(`Reason code: ${run.error_code}`);
+    return;
+  }
+  success(
+    `Imported ${String(run.pages_ingested)} of ${String(run.pages_fetched)} page(s) from ${run.source_url}.`
+  );
+  if (run.brand_kit_generated) {
+    success("A brand kit was generated from the site.");
+  } else if (run.brand_kit_skip_reason === "already_populated") {
+    info("Brand kit left alone \u2014 this organization already has one.");
+  }
+  if (run.pages_ingested < run.pages_fetched) {
+    info("Pages already in the knowledge base unchanged are fetched but not re-ingested.");
+  }
+}
+function buildStatusRows(data) {
+  const rows = [];
+  if (data.current) rows.push({ slot: "current", ...data.current });
+  if (data.latest_completed) rows.push({ slot: "latest_completed", ...data.latest_completed });
+  return rows;
+}
+function registerWebsiteImportCommands(program) {
+  const websiteImport = program.command("website-import").description(
+    "Import your organization's website into the knowledge base. Fetches the home page plus up to 10 linked pages, ingests each as a document under a folder named 'Website', and drafts a brand kit if the organization does not have one yet."
+  );
+  websiteImport.command("start").description(
+    "Start a website import and wait for it to finish. The site imported is the one on file for your organization \u2014 see 'senso org get' \u2014 not a value you pass, so this takes no arguments. Exits 1 if the import finishes in a failed state."
+  ).option(
+    "--no-wait",
+    "Return the accepted run immediately instead of polling until the import finishes."
+  ).action(
+    runAction(program, async (ctx, cmdOpts) => {
+      let accepted;
+      try {
+        accepted = await apiRequest({
+          method: "POST",
+          path: "/org/website-import",
+          apiKey: ctx.apiKey,
+          baseUrl: ctx.baseUrl
+        });
+      } catch (err) {
+        const status = err.status;
+        if (status === 409) {
+          throw new CliError(
+            "A website import is already running for this organization.",
+            EXIT.ERROR,
+            {
+              code: "conflict",
+              status: 409,
+              hint: "Run `senso website-import status` to follow the one in flight.",
+              cause: err
+            }
+          );
+        }
+        throw err;
+      }
+      if (!cmdOpts.wait) {
+        if (!ctx.quiet) success(`Website import ${accepted.run_id} started.`);
+        emit(ctx, accepted, { columns: RUN_COLUMNS });
+        return;
+      }
+      const spin = spinner4(ctx.quiet);
+      spin.start("Importing website...");
+      let finished;
+      try {
+        finished = await waitForImport(accepted.run_id, ctx);
+      } catch (err) {
+        spin.stop("Website import did not finish");
+        throw err;
+      }
+      spin.stop("Website import finished");
+      describeOutcome(finished, ctx.quiet);
+      if (finished.status === "failed") {
+        throw new CliError(
+          `Website import ${finished.run_id} failed${finished.error_code ? ` (${finished.error_code})` : ""}.`,
+          EXIT.ERROR,
+          { hint: "Run `senso website-import status` for the full record." }
+        );
+      }
+      emit(ctx, finished, { columns: RUN_COLUMNS });
+    })
+  );
+  websiteImport.command("status").description(
+    "Show the website import in flight and the most recently finished one. Either may be absent. This is a read: it exits 0 even when the last import failed."
+  ).action(
+    runAction(program, async (ctx) => {
+      const data = await getStatus(ctx);
+      if (!ctx.quiet && !data.current && !data.latest_completed) {
+        info("This organization has never imported its website.");
+      }
+      emit(ctx, data, {
+        // A status envelope is two nullable runs, not a list, so the table
+        // rendering is built here rather than left to findRows.
+        table: {
+          rows: buildStatusRows(data),
+          columns: ["slot", ...RUN_COLUMNS]
+        }
+      });
+    })
+  );
+}
+
 // src/commands/content.ts
 import pc9 from "picocolors";
 
@@ -2716,14 +2876,14 @@ async function waitForSampleJob(sampleJobId, opts) {
     if (job.status === "completed" || job.status === "failed" || job.status === "expired") {
       return job;
     }
-    await sleep(SAMPLE_JOB_POLL_INTERVAL_MS);
+    await sleep2(SAMPLE_JOB_POLL_INTERVAL_MS);
   }
   throw new CliError(`Timed out waiting for sample job ${sampleJobId}.`, EXIT.NETWORK, {
     code: "timeout",
     hint: `Poll /org/content-generation/sample-jobs/${sampleJobId} for status.`
   });
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 
@@ -2893,11 +3053,122 @@ function registerPublishRecordsCommands(program) {
 }
 
 // src/commands/brand-kit.ts
+var GUIDELINE_STRING_FIELDS = [
+  "brand_name",
+  "brand_domain",
+  "brand_description",
+  "voice_and_tone",
+  "author_persona"
+];
+var GUIDELINE_FIELDS = [...GUIDELINE_STRING_FIELDS, "global_writing_rules"];
+var FIELD_LIST = GUIDELINE_FIELDS.join(", ");
+var SET_EXAMPLE = `--data '{"guidelines":{"brand_name":"Acme","voice_and_tone":"Warm and direct"}}'`;
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+function nearest(key, allowed) {
+  let best;
+  let bestDistance = 3;
+  for (const candidate of allowed) {
+    const distance = editDistance(key, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+  return best;
+}
+function editDistance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) {
+      next.push(
+        Math.min(
+          (row[j] ?? 0) + 1,
+          (next[j - 1] ?? 0) + 1,
+          (row[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1)
+        )
+      );
+    }
+    row = next;
+  }
+  return row[b.length] ?? 0;
+}
+function usageError(message, hint2) {
+  return new CliError(message, EXIT.USAGE, { code: "usage", hint: hint2 });
+}
+function parseBrandKitData(data, mode) {
+  const body = parseJsonFlag(data);
+  if (!("guidelines" in body)) {
+    throw usageError(
+      `--data must have a "guidelines" object at the top level.`,
+      `The fields go inside it: ${SET_EXAMPLE}. Accepted fields: ${FIELD_LIST}.`
+    );
+  }
+  const stray = Object.keys(body).filter((key) => key !== "guidelines");
+  if (stray.length > 0) {
+    throw usageError(
+      `--data has ${stray.length === 1 ? "a key" : "keys"} outside "guidelines": ${stray.join(", ")}.`,
+      `Move ${stray.length === 1 ? "it" : "them"} inside "guidelines" \u2014 the API ignores anything beside it without reporting that it did. Accepted fields: ${FIELD_LIST}.`
+    );
+  }
+  const guidelines = body.guidelines;
+  if (typeof guidelines !== "object" || guidelines === null || Array.isArray(guidelines)) {
+    throw usageError(
+      `"guidelines" must be a JSON object, not ${describe(guidelines)}.`,
+      `Example: ${SET_EXAMPLE}`
+    );
+  }
+  const entries = Object.entries(guidelines);
+  if (mode === "merge" && entries.length === 0) {
+    throw usageError(
+      `"guidelines" must name at least one field to patch.`,
+      `Accepted fields: ${FIELD_LIST}. To clear the whole brand kit instead, run: senso brand-kit set --data '{"guidelines":{}}'`
+    );
+  }
+  for (const [key, value] of entries) {
+    if (!GUIDELINE_FIELDS.includes(key)) {
+      const suggestion = nearest(key, GUIDELINE_FIELDS);
+      throw usageError(
+        `"guidelines" does not accept the field "${key}".`,
+        suggestion ? `Did you mean "${suggestion}"? Accepted fields: ${FIELD_LIST}.` : `Accepted fields: ${FIELD_LIST}.`
+      );
+    }
+    if (key === "global_writing_rules") {
+      if (!Array.isArray(value)) {
+        throw usageError(
+          `"global_writing_rules" must be an array of strings, not ${describe(value)}.`,
+          `Example: {"global_writing_rules":["Avoid superlatives unless backed by a number"]}. Pass [] to clear the rules.`
+        );
+      }
+      const badIndex = value.findIndex((rule) => typeof rule !== "string");
+      if (badIndex !== -1) {
+        throw usageError(
+          `"global_writing_rules[${String(badIndex)}]" must be a string, not ${describe(value[badIndex])}.`,
+          `Every rule is a line of guidance for the AI writer, e.g. "Prefer concrete examples over abstract claims".`
+        );
+      }
+      continue;
+    }
+    if (typeof value !== "string") {
+      throw usageError(
+        `"${key}" must be a string, not ${describe(value)}.`,
+        value === null ? `No field may be null. Omit it to leave it unchanged, or use 'brand-kit set' without it to remove it.` : `Example: {"${key}":"..."}`
+      );
+    }
+  }
+  return body;
+}
 function registerBrandKitCommands(program) {
   const bk = program.command("brand-kit").description(
-    "Manage the organization's brand kit guidelines that inform AI content generation about your brand voice, tone, and style. The guidelines object accepts a defined set of keys: brand_name, brand_domain, brand_description, voice_and_tone, author_persona, and global_writing_rules (array). Unknown keys are rejected."
+    `Manage the organization's brand kit guidelines that inform AI content generation about your brand voice, tone, and style. The guidelines object accepts a defined set of keys: ${FIELD_LIST} (global_writing_rules is an array of strings, the rest are strings). Unknown keys, wrong types and nulls are rejected before the request is sent.`
   );
-  bk.command("get").description("Get the current brand kit guidelines.").action(
+  bk.command("get").description(
+    "Get the current brand kit guidelines. An organization that has never saved one gets an empty guidelines object rather than an error."
+  ).action(
     runAction(program, async (ctx) => {
       const data = await apiRequest({
         path: "/org/brand-kit",
@@ -2908,13 +3179,13 @@ function registerBrandKitCommands(program) {
     })
   );
   bk.command("set").description(
-    "Replace the entire brand kit (PUT). All existing fields are overwritten \u2014 run 'brand-kit get' first to preserve fields you are not changing. For a safe partial update, use 'brand-kit patch'."
+    "Replace the entire brand kit (PUT). All existing fields are overwritten \u2014 run 'brand-kit get' first to preserve fields you are not changing. For a safe partial update, use 'brand-kit patch'. This is also what creates the brand kit the first time."
   ).requiredOption(
     "--data <json>",
-    'JSON: { "guidelines": { "brand_name": "Acme", "voice_and_tone": "...", "author_persona": "...", "global_writing_rules": [] } }'
+    `JSON: { "guidelines": { "brand_name": "Acme", "brand_domain": "https://acme.com", "brand_description": "...", "voice_and_tone": "...", "author_persona": "...", "global_writing_rules": ["..."] } }. Every field is optional, but anything you omit is REMOVED \u2014 pass '{"guidelines":{}}' to clear the brand kit entirely.`
   ).action(
     runAction(program, async (ctx, cmdOpts) => {
-      const body = parseJsonFlag(cmdOpts.data);
+      const body = parseBrandKitData(cmdOpts.data, "replace");
       const data = await apiRequest({
         method: "PUT",
         path: "/org/brand-kit",
@@ -2927,13 +3198,13 @@ function registerBrandKitCommands(program) {
     })
   );
   bk.command("patch").description(
-    "Partially update the brand kit (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'set' for targeted updates."
+    "Partially update the brand kit (PATCH). Only the fields you provide are changed \u2014 existing fields are preserved. Preferred over 'set' for targeted updates. Note that global_writing_rules is replaced wholesale, not appended to, and no field can be removed this way \u2014 use 'set' for that."
   ).requiredOption(
     "--data <json>",
-    'JSON: { "guidelines": { "voice_and_tone": "Warm and approachable" } }'
+    `JSON: { "guidelines": { "voice_and_tone": "Warm and approachable" } }. At least one field is required; accepted fields are ${FIELD_LIST}.`
   ).action(
     runAction(program, async (ctx, cmdOpts) => {
-      const body = parseJsonFlag(cmdOpts.data);
+      const body = parseBrandKitData(cmdOpts.data, "merge");
       const data = await apiRequest({
         method: "PATCH",
         path: "/org/brand-kit",
@@ -3947,7 +4218,7 @@ function registerKBCommands(program) {
     })
   );
   kb.command("upload <files...>").description(
-    "Upload files to the knowledge base (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker."
+    "Upload files to the knowledge base (up to 10). Files are hashed, uploaded to S3, then parsed and embedded by a background worker. Poll 'senso kb get <kb-node-id>' until content.processing_status is 'complete' before searching the uploaded content."
   ).option("--folder-id <id>", "Parent folder node ID to place files in (omit for root)").action(
     runAction(program, async (ctx, files, cmdOpts) => {
       if (files.length > 10) {
@@ -4010,7 +4281,9 @@ function registerKBCommands(program) {
         });
       }
       if (ctx.format !== "plain") {
-        emit(ctx, response, { columns: ["filename", "status", "content_id", "error"] });
+        emit(ctx, response, {
+          columns: ["filename", "status", "kb_node_id", "content_id", "error"]
+        });
       }
     })
   );
@@ -5702,6 +5975,7 @@ function createProgram() {
   registerApiKeyCommands(program);
   registerSearchCommands(program);
   registerIngestCommands(program);
+  registerWebsiteImportCommands(program);
   registerContentCommands(program);
   registerCtaCommands(program);
   registerGenerateCommands(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senso-ai/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Senso CLI — Infrastructure for the Agentic Web. Manage your Senso knowledge base, content and GEO analytics from the terminal.",
   "type": "module",
   "bin": {
@@ -76,5 +76,8 @@
   "homepage": "https://github.com/AI-Template-SDK/senso-user-cli#readme",
   "bugs": {
     "url": "https://github.com/AI-Template-SDK/senso-user-cli/issues"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
   }
 }