@tplog/zendcli 1.1.5 → 1.2.0

package/README.md

@@ -1,6 +1,13 @@
 # zendcli
 
-Minimal Zendesk CLI for listing tickets and reading ticket comment threads.
+Minimal Zendesk CLI for listing tickets and reading ticket comment timelines.
+
+`zend comments` returns a slim timeline optimized for terminal review and LLM summarization. By default it includes both public and private comments and emits only:
+
+- `author`
+- `time`
+- `visibility` (`public` or `private`)
+- `body`
 
 ## Install
 
@@ -30,7 +37,7 @@ This is the recommended option for temporary or CI usage.
 
 ```bash
 export ZENDESK_SUBDOMAIN="your-subdomain"
-export ZENDESK_EMAIL="foo@example.com"
+export ZENDESK_EMAIL="user@example.com"
 export ZENDESK_API_TOKEN="your_zendesk_api_token"
 ```
 
@@ -40,22 +47,36 @@ Environment variables take precedence over the config file.
 
 ```bash
 zend --help
-zend tickets --help
+zend ticket --help
 zend email --help
 zend follower --help
 zend comments --help
-zend tickets --limit 10
-zend tickets --status open --limit 20
-zend email foo@example.com
-zend email foo@example.com --status unresolved
-zend email foo@example.com --status open,pending
-zend follower
-zend follower foo@example.com --limit 3
+zend 12345
+zend ticket 12345 --raw
+zend email user@example.com
+zend email user@example.com --status unresolved
+zend email user@example.com --status open,pending
+zend follower user@example.com --limit 3
 zend comments 12345
-zend comments 12345 --type public
-zend comments 12345 --json
+zend comments 12345 --visibility public
+zend comments 12345 --visibility private --sort desc
 ```
 
+### Comments output shape
+
+```json
+[
+  {
+    "author": "Support Agent",
+    "time": "2026-03-13T06:19:57Z",
+    "visibility": "public",
+    "body": "Reply text..."
+  }
+]
+```
+
+Use `--visibility public` or `--visibility private` to filter the timeline.
+
 ## Development workflow
 
 ### Daily development

package/dist/cli.js

@@ -3674,6 +3674,12 @@ function parseSort(input = "desc") {
   }
   return input;
 }
+function parseVisibility(input = "all") {
+  if (input !== "all" && input !== "public" && input !== "private") {
+    throw new CliError("invalid_args", "visibility must be all, public, or private", { visibility: input });
+  }
+  return input;
+}
 function buildSearchQuery(base, rawStatus, statusFilter) {
   if (rawStatus === "unresolved") return `${base} status<solved`;
   if (statusFilter.length === 1) return `${base} status:${statusFilter[0]}`;
@@ -3714,6 +3720,41 @@ async function fetchFollowerTickets(email, rawStatus, limit, sort) {
   }
   return matches;
 }
+async function fetchUsersByIds(ids) {
+  const userMap = /* @__PURE__ */ new Map();
+  const uniqueIds = [...new Set(ids)].filter((id) => Number.isFinite(id));
+  for (let index = 0; index < uniqueIds.length; index += 100) {
+    const chunk = uniqueIds.slice(index, index + 100);
+    try {
+      const data = await apiGet("/api/v2/users/show_many.json", { ids: chunk.join(",") });
+      for (const user of data.users || []) {
+        userMap.set(user.id, user);
+      }
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) continue;
+      throw error;
+    }
+  }
+  return userMap;
+}
+function filterCommentsByVisibility(comments, visibility) {
+  if (visibility === "public") return comments.filter((comment) => comment.public === true);
+  if (visibility === "private") return comments.filter((comment) => comment.public === false);
+  return comments;
+}
+function normalizeCommentBody(comment) {
+  return String(comment.plain_body || comment.body || "").replace(/&nbsp;/g, " ").replace(/\r/g, "").trim();
+}
+function toSlimComment(comment, userMap) {
+  const authorId = typeof comment.author_id === "number" ? comment.author_id : null;
+  const author = authorId ? userMap.get(authorId)?.name || `user:${authorId}` : "unknown";
+  return {
+    author,
+    time: typeof comment.created_at === "string" ? comment.created_at : null,
+    visibility: comment.public === true ? "public" : "private",
+    body: normalizeCommentBody(comment)
+  };
+}
 function apiBaseUrl() {
   const { subdomain } = getConfig();
   return `https://${subdomain}.zendesk.com`;
@@ -3793,22 +3834,20 @@ program2.command("follower <email>").description("Find tickets where the user is
   const tickets = await fetchFollowerTickets(email, opts.status, limit, sort);
   printJson(tickets);
 }));
-program2.command("comments <ticketId>").description("List comments for a ticket").option("--type <type>", "all|public|internal", "all").option("--sort <order>", "Sort order (asc|desc)", "asc").action(run(async (ticketId, opts) => {
+program2.command("comments <ticketId>").description("List slim comment timeline for a ticket").option("--visibility <visibility>", "all|public|private", "all").option("--sort <order>", "Sort order (asc|desc)", "asc").action(run(async (ticketId, opts) => {
   if (!DIGITS_RE.test(ticketId)) {
     throw new CliError("invalid_args", "ticket id must be numeric", { ticketId });
   }
   const sort = parseSort(opts.sort);
-  if (!["all", "public", "internal"].includes(opts.type)) {
-    throw new CliError("invalid_args", "type must be all, public, or internal", { type: opts.type });
-  }
+  const visibility = parseVisibility(opts.visibility);
   const data = await apiGet(
     `/api/v2/tickets/${ticketId}/comments.json`,
     { sort_order: sort, per_page: 100 }
   );
-  let comments = data.comments || [];
-  if (opts.type === "public") comments = comments.filter((comment) => comment.public === true);
-  if (opts.type === "internal") comments = comments.filter((comment) => comment.public === false);
-  printJson(comments);
+  const comments = filterCommentsByVisibility(data.comments || [], visibility);
+  const authorIds = comments.map((comment) => comment.author_id).filter((authorId) => typeof authorId === "number");
+  const userMap = await fetchUsersByIds(authorIds);
+  printJson(comments.map((comment) => toSlimComment(comment, userMap)));
 }));
 function preprocessArgv(argv) {
   const firstArg = argv[2];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tplog/zendcli",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "Minimal Zendesk CLI for tickets and comments",
   "repository": {
     "type": "git",