@easycustomerfeedback/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @easycustomerfeedback/cli
 
-`ecf` is the command-line interface for [EasyCustomerFeedback](https://easycustomerfeedback.com). Triage feedback submissions, update statuses, and leave internal comments from your terminal.
+`ecf` is the command-line interface for [EasyCustomerFeedback](https://easycustomerfeedback.com). Triage feedback submissions, manage knowledge base articles, and leave internal comments from your terminal.
 
 ## Install
 
@@ -21,41 +21,42 @@ Requires Node.js 18 or newer.
 1. In the EasyCustomerFeedback dashboard, open **Integrations → Personal API tokens** and create a token. Copy it — tokens are only shown once.
 2. Log in:
 
-    ```sh
-    ecf login
-    ```
+   ```sh
+   ecf login
+   ```
+
+   You'll be prompted for the server URL (defaults to `https://easycustomerfeedback.com`) and the token. Credentials are saved to `~/.config/ecf/config.json`.
 
-    You'll be prompted for the server URL (defaults to `https://easycustomerfeedback.com`) and the token. Credentials are saved to `~/.config/ecf/config.json`.
 3. If you belong to multiple workspaces, pick a default:
 
-    ```sh
-    ecf workspace list
-    ecf workspace use <workspaceId>
-    ```
+   ```sh
+   ecf workspace list
+   ecf workspace use <workspaceId>
+   ```
 
 ## Commands
 
 ### Authentication
 
-| Command | What it does |
-| --- | --- |
+| Command     | What it does                                                                         |
+| ----------- | ------------------------------------------------------------------------------------ |
 | `ecf login` | Configure server URL and API token. Auto-selects the workspace if you only have one. |
 
 ### Workspaces
 
-| Command | What it does |
-| --- | --- |
-| `ecf workspace list` | Show the workspaces you belong to (marks the active one). |
-| `ecf workspace use <id>` | Set the default workspace for future commands. |
+| Command                  | What it does                                              |
+| ------------------------ | --------------------------------------------------------- |
+| `ecf workspace list`     | Show the workspaces you belong to (marks the active one). |
+| `ecf workspace use <id>` | Set the default workspace for future commands.            |
 
 ### Submissions
 
-| Command | What it does |
-| --- | --- |
-| `ecf submissions list [options]` | List submissions in the active workspace. |
-| `ecf submissions get <id> [--json]` | Show details for a submission. |
-| `ecf submissions status <id> <status>` | Update a submission's status. |
-| `ecf submissions comment <id> [body]` | Add an internal comment (body may come from stdin). |
+| Command                                | What it does                                        |
+| -------------------------------------- | --------------------------------------------------- |
+| `ecf submissions list [options]`       | List submissions in the active workspace.           |
+| `ecf submissions get <id> [--json]`    | Show details for a submission.                      |
+| `ecf submissions status <id> <status>` | Update a submission's status.                       |
+| `ecf submissions comment <id> [body]`  | Add an internal comment (body may come from stdin). |
 
 `ecf submissions list` options:
 
@@ -68,6 +69,48 @@ Requires Node.js 18 or newer.
 
 Valid status values for `ecf submissions status`: `untriaged`, `open`, `in_progress`, `resolved`, `closed`.
 
+### Knowledge base
+
+Manage articles and categories scoped to a project. Pass the project's slug as the first positional argument.
+
+#### Categories
+
+| Command                                                         | What it does                          |
+| --------------------------------------------------------------- | ------------------------------------- |
+| `ecf kb categories list <projectSlug> [--json]`                 | List categories in the project.       |
+| `ecf kb categories create <projectSlug> --name <n> [--description <d>]` | Create a category.            |
+| `ecf kb categories delete <projectSlug> <categoryId>`           | Delete a category.                    |
+
+#### Articles
+
+| Command                                                  | What it does                              |
+| -------------------------------------------------------- | ----------------------------------------- |
+| `ecf kb articles list <projectSlug> [options]`           | List articles (optionally filter by status/category). |
+| `ecf kb articles get <projectSlug> <articleId> [--json]` | Show an article (title, metadata, plain-text body). |
+| `ecf kb articles create <projectSlug> --title <t> [options]` | Create a draft article.               |
+| `ecf kb articles update <projectSlug> <articleId> [options]` | Update an article. Unspecified fields keep their current values. |
+| `ecf kb articles publish <projectSlug> <articleId>`      | Publish (or republish) the article.       |
+| `ecf kb articles unpublish <projectSlug> <articleId>`    | Move the article back to draft.           |
+| `ecf kb articles archive <projectSlug> <articleId>`      | Archive the article.                      |
+| `ecf kb articles delete <projectSlug> <articleId>`       | Delete the article.                       |
+
+`ecf kb articles list` options:
+
+- `--status <s>` — filter by status (`draft`, `published`, `archived`)
+- `--category <id>` — filter by category id
+- `--json` — output raw JSON
+
+`ecf kb articles create` / `update` options:
+
+- `--title <t>` — required for `create`; optional for `update`
+- `--summary <s>` — short blurb shown in lists and SEO meta
+- `--category <id>` — assign to a category (use `--no-category` on `update` to detach)
+- `--visibility public|internal` — defaults to `public`
+- `--body-md <path|->` — read a Markdown file (or `-` for stdin) and convert to TipTap JSON
+- `--body-json <path|->` — read a TipTap JSON document directly (file path or `-` for stdin)
+
+Pass either `--body-md` or `--body-json`, not both. The Markdown importer supports headings, paragraphs, bullet/ordered lists, blockquotes, fenced code blocks, horizontal rules, hard breaks, and inline marks (`**bold**`, `*italic*`, `` `code` ``, `~~strike~~`, `[link](url)`).
+
 ## Examples
 
 List open bugs, piped to your pager:
@@ -88,6 +131,24 @@ Resolve a submission:
 ecf submissions status sub_abc123 resolved
 ```
 
+Draft a knowledge base article from a Markdown file and publish it:
+
+```sh
+ecf kb articles create my-project \
+  --title "Resetting your password" \
+  --summary "Step-by-step instructions for password resets." \
+  --body-md ./docs/password-reset.md
+# → Created kba_abc123  (resetting-your-password)
+
+ecf kb articles publish my-project kba_abc123
+```
+
+Pipe Markdown straight from your editor:
+
+```sh
+pbpaste | ecf kb articles update my-project kba_abc123 --body-md -
+```
+
 ## Configuration
 
 Configuration lives at `~/.config/ecf/config.json` and is created by `ecf login`. Delete the file to reset.

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
-// src/commands/login.ts
-import { createInterface } from "node:readline/promises";
+// src/commands/kb.ts
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
 
 // src/api.ts
 class ApiError extends Error {
@@ -68,7 +69,324 @@ function requireConfig() {
   return config;
 }
 
+// src/commands/kb.ts
+var VALID_STATUSES = ["draft", "published", "archived"];
+var VALID_VISIBILITIES = ["public", "internal"];
+async function kbCommand(args) {
+  const [resource, ...rest] = args;
+  if (resource === "categories")
+    return categoriesCommand(rest);
+  if (resource === "articles")
+    return articlesCommand(rest);
+  console.error("Usage: ecf kb <categories|articles> ...");
+  process.exit(1);
+}
+async function categoriesCommand(args) {
+  const [sub, ...rest] = args;
+  if (sub === "list")
+    return listCategories(rest);
+  if (sub === "create")
+    return createCategory(rest);
+  if (sub === "delete")
+    return deleteCategory(rest);
+  console.error("Usage: ecf kb categories <list|create|delete> ...");
+  process.exit(1);
+}
+async function listCategories(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { json: { type: "boolean" } },
+    allowPositionals: true
+  });
+  const [projectSlug] = positionals;
+  if (!projectSlug) {
+    console.error("Usage: ecf kb categories list <projectSlug> [--json]");
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const { categories } = await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/categories`);
+  if (values.json) {
+    console.log(JSON.stringify(categories, null, 2));
+    return;
+  }
+  if (categories.length === 0) {
+    console.log("No categories.");
+    return;
+  }
+  for (const c of categories) {
+    console.log(`${c.id}  ${c.slug.padEnd(24)} ${c.name}`);
+  }
+}
+async function createCategory(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      name: { type: "string" },
+      description: { type: "string" }
+    },
+    allowPositionals: true
+  });
+  const [projectSlug] = positionals;
+  if (!projectSlug || !values.name) {
+    console.error("Usage: ecf kb categories create <projectSlug> --name <name> [--description <desc>]");
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const { category } = await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/categories`, {
+    method: "POST",
+    body: JSON.stringify({ name: values.name, description: values.description })
+  });
+  console.log(`Created ${category.id}  (${category.slug})`);
+}
+async function deleteCategory(args) {
+  const [projectSlug, categoryId] = args;
+  if (!projectSlug || !categoryId) {
+    console.error("Usage: ecf kb categories delete <projectSlug> <categoryId>");
+    process.exit(1);
+  }
+  const config = requireConfig();
+  await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/categories/${encodeURIComponent(categoryId)}`, { method: "DELETE" });
+  console.log(`Deleted ${categoryId}`);
+}
+async function articlesCommand(args) {
+  const [sub, ...rest] = args;
+  if (sub === "list")
+    return listArticles(rest);
+  if (sub === "get")
+    return getArticle(rest);
+  if (sub === "create")
+    return createArticle(rest);
+  if (sub === "update")
+    return updateArticle(rest);
+  if (sub === "publish")
+    return setStatus(rest, "published");
+  if (sub === "unpublish")
+    return setStatus(rest, "draft");
+  if (sub === "archive")
+    return setStatus(rest, "archived");
+  if (sub === "delete")
+    return deleteArticle(rest);
+  console.error("Usage: ecf kb articles <list|get|create|update|publish|unpublish|archive|delete> ...");
+  process.exit(1);
+}
+async function listArticles(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      status: { type: "string" },
+      category: { type: "string" },
+      json: { type: "boolean" }
+    },
+    allowPositionals: true
+  });
+  const [projectSlug] = positionals;
+  if (!projectSlug) {
+    console.error("Usage: ecf kb articles list <projectSlug> [--status draft|published|archived] [--category <id>] [--json]");
+    process.exit(1);
+  }
+  if (values.status && !VALID_STATUSES.includes(values.status)) {
+    console.error(`Invalid --status. Must be one of: ${VALID_STATUSES.join(", ")}`);
+    process.exit(1);
+  }
+  const params = new URLSearchParams;
+  if (values.status)
+    params.set("status", values.status);
+  if (values.category)
+    params.set("categoryId", values.category);
+  const config = requireConfig();
+  const query = params.toString();
+  const { articles } = await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles${query ? `?${query}` : ""}`);
+  if (values.json) {
+    console.log(JSON.stringify(articles, null, 2));
+    return;
+  }
+  if (articles.length === 0) {
+    console.log("No articles.");
+    return;
+  }
+  for (const a of articles) {
+    const cat = a.categoryName ?? "—";
+    console.log(`${a.id}  [${a.status.padEnd(9)}] ${a.visibility.padEnd(8)} ${cat.padEnd(20)} ${a.title}`);
+  }
+}
+async function getArticle(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: { json: { type: "boolean" } },
+    allowPositionals: true
+  });
+  const [projectSlug, articleId] = positionals;
+  if (!projectSlug || !articleId) {
+    console.error("Usage: ecf kb articles get <projectSlug> <articleId> [--json]");
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const { article } = await fetchArticle(config, projectSlug, articleId);
+  if (values.json) {
+    console.log(JSON.stringify(article, null, 2));
+    return;
+  }
+  console.log(`# ${article.title}`);
+  console.log(`id: ${article.id}  slug: ${article.slug}  status: ${article.status}  visibility: ${article.visibility}`);
+  if (article.categoryName)
+    console.log(`category: ${article.categoryName} (${article.categoryId})`);
+  if (article.summary)
+    console.log(`
+${article.summary}`);
+  if (article.bodyText)
+    console.log(`
+${article.bodyText}`);
+}
+async function createArticle(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      title: { type: "string" },
+      summary: { type: "string" },
+      category: { type: "string" },
+      visibility: { type: "string" },
+      "body-md": { type: "string" },
+      "body-json": { type: "string" }
+    },
+    allowPositionals: true
+  });
+  const [projectSlug] = positionals;
+  if (!projectSlug || !values.title) {
+    console.error("Usage: ecf kb articles create <projectSlug> --title <t> [--summary <s>] [--category <id>] [--visibility public|internal] [--body-md <path|-> | --body-json <path|->]");
+    process.exit(1);
+  }
+  if (values.visibility && !VALID_VISIBILITIES.includes(values.visibility)) {
+    console.error(`Invalid --visibility. Must be one of: ${VALID_VISIBILITIES.join(", ")}`);
+    process.exit(1);
+  }
+  const bodyFields = await readBodyFields({
+    bodyMd: values["body-md"],
+    bodyJson: values["body-json"]
+  });
+  if (bodyFields instanceof Error) {
+    console.error(bodyFields.message);
+    process.exit(1);
+  }
+  const payload = {
+    title: values.title,
+    summary: values.summary,
+    categoryId: values.category ?? null,
+    visibility: values.visibility,
+    ...bodyFields
+  };
+  const config = requireConfig();
+  const { article } = await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles`, { method: "POST", body: JSON.stringify(payload) });
+  console.log(`Created ${article.id}  (${article.slug})`);
+}
+async function updateArticle(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      title: { type: "string" },
+      summary: { type: "string" },
+      category: { type: "string" },
+      "no-category": { type: "boolean" },
+      visibility: { type: "string" },
+      "body-md": { type: "string" },
+      "body-json": { type: "string" }
+    },
+    allowPositionals: true
+  });
+  const [projectSlug, articleId] = positionals;
+  if (!projectSlug || !articleId) {
+    console.error("Usage: ecf kb articles update <projectSlug> <articleId> [--title ...] [--summary ...] [--category <id> | --no-category] [--visibility ...] [--body-md <path|-> | --body-json <path|->]");
+    process.exit(1);
+  }
+  if (values.visibility && !VALID_VISIBILITIES.includes(values.visibility)) {
+    console.error(`Invalid --visibility. Must be one of: ${VALID_VISIBILITIES.join(", ")}`);
+    process.exit(1);
+  }
+  const bodyFields = await readBodyFields({
+    bodyMd: values["body-md"],
+    bodyJson: values["body-json"]
+  });
+  if (bodyFields instanceof Error) {
+    console.error(bodyFields.message);
+    process.exit(1);
+  }
+  const config = requireConfig();
+  const { article: current } = await fetchArticle(config, projectSlug, articleId);
+  const nextTitle = values.title ?? current.title;
+  const nextSummary = values.summary !== undefined ? values.summary : current.summary ?? undefined;
+  const nextVisibility = values.visibility ?? current.visibility;
+  let nextCategoryId;
+  if (values["no-category"]) {
+    nextCategoryId = null;
+  } else if (typeof values.category === "string") {
+    nextCategoryId = values.category;
+  } else {
+    nextCategoryId = current.categoryId;
+  }
+  const payload = {
+    title: nextTitle,
+    summary: nextSummary,
+    categoryId: nextCategoryId,
+    visibility: nextVisibility,
+    ...Object.keys(bodyFields).length > 0 ? bodyFields : { bodyJson: current.bodyJson ?? { type: "doc", content: [] } }
+  };
+  const { article } = await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles/${encodeURIComponent(articleId)}`, { method: "PATCH", body: JSON.stringify(payload) });
+  console.log(`Updated ${article.id}  (${article.slug})`);
+}
+async function setStatus(args, status) {
+  const [projectSlug, articleId] = args;
+  if (!projectSlug || !articleId) {
+    console.error(`Usage: ecf kb articles <publish|unpublish|archive> <projectSlug> <articleId>`);
+    process.exit(1);
+  }
+  const config = requireConfig();
+  await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles/${encodeURIComponent(articleId)}/status`, { method: "POST", body: JSON.stringify({ status }) });
+  console.log(`${articleId} → ${status}`);
+}
+async function deleteArticle(args) {
+  const [projectSlug, articleId] = args;
+  if (!projectSlug || !articleId) {
+    console.error("Usage: ecf kb articles delete <projectSlug> <articleId>");
+    process.exit(1);
+  }
+  const config = requireConfig();
+  await apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles/${encodeURIComponent(articleId)}`, { method: "DELETE" });
+  console.log(`Deleted ${articleId}`);
+}
+async function fetchArticle(config, projectSlug, articleId) {
+  return apiFetch(config, `/api/v1/projects/${encodeURIComponent(projectSlug)}/kb/articles/${encodeURIComponent(articleId)}`);
+}
+async function readSource(source) {
+  if (source === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+  }
+  return readFile(source, "utf8");
+}
+async function readBodyFields(input) {
+  if (input.bodyMd && input.bodyJson) {
+    return new Error("Pass either --body-md or --body-json, not both");
+  }
+  if (input.bodyMd) {
+    const text = await readSource(input.bodyMd);
+    return { bodyMarkdown: text };
+  }
+  if (input.bodyJson) {
+    const text = await readSource(input.bodyJson);
+    try {
+      const parsed = JSON.parse(text);
+      return { bodyJson: parsed };
+    } catch {
+      return new Error(`--body-json: not valid JSON (${input.bodyJson})`);
+    }
+  }
+  return {};
+}
+
 // src/commands/login.ts
+import { createInterface } from "node:readline/promises";
 async function prompt(rl, question, def) {
   const suffix = def ? ` [${def}]` : "";
   const answer = (await rl.question(`${question}${suffix}: `)).trim();
@@ -109,7 +427,7 @@ Active workspace set to ${workspaces[0].name}.`);
 }
 
 // src/commands/submissions.ts
-import { parseArgs } from "node:util";
+import { parseArgs as parseArgs2 } from "node:util";
 function resolveWorkspace(config, override) {
   const id = override ?? config.workspaceId;
   if (!id) {
@@ -139,7 +457,7 @@ async function submissionsCommand(args) {
   process.exit(1);
 }
 async function list(args) {
-  const { values } = parseArgs({
+  const { values } = parseArgs2({
     args,
     options: {
       status: { type: "string", multiple: true },
@@ -177,7 +495,7 @@ async function list(args) {
   }
 }
 async function get(args) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals } = parseArgs2({
     args,
     options: { json: { type: "boolean" } },
     allowPositionals: true
@@ -307,6 +625,20 @@ Usage:
   ecf submissions status <id> <status>       Update a submission's status
   ecf submissions comment <id> [body]        Add an internal comment
     (if body is omitted, reads from stdin)
+
+  ecf kb categories list <projectSlug> [--json]
+  ecf kb categories create <projectSlug> --name <n> [--description <d>]
+  ecf kb categories delete <projectSlug> <categoryId>
+
+  ecf kb articles list <projectSlug> [--status <s>] [--category <id>] [--json]
+  ecf kb articles get <projectSlug> <articleId> [--json]
+  ecf kb articles create <projectSlug> --title <t> [options]
+    --summary <s>   --category <id>   --visibility public|internal
+    --body-md <path|->     Markdown source (file path, or "-" for stdin)
+    --body-json <path|->   TipTap JSON source (file path, or "-" for stdin)
+  ecf kb articles update <projectSlug> <articleId> [same options + --no-category]
+  ecf kb articles publish|unpublish|archive <projectSlug> <articleId>
+  ecf kb articles delete <projectSlug> <articleId>
 `;
 async function main() {
   const argv = process.argv.slice(2);
@@ -326,6 +658,9 @@ async function main() {
       case "submissions":
         await submissionsCommand(rest);
         return;
+      case "kb":
+        await kbCommand(rest);
+        return;
       default:
         console.error(`Unknown command: ${command}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@easycustomerfeedback/cli",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Command-line interface for EasyCustomerFeedback — list, triage, and comment on feedback submissions from your terminal.",
 	"license": "MIT",
 	"type": "module",