@tplog/zendcli 0.2.3 → 1.1.0

package/README.md

@@ -30,7 +30,7 @@ This is the recommended option for temporary or CI usage.
 
 ```bash
 export ZENDESK_SUBDOMAIN="your-subdomain"
-export ZENDESK_EMAIL="you@example.com"
+export ZENDESK_EMAIL="foo@example.com"
 export ZENDESK_API_TOKEN="your_zendesk_api_token"
 ```
 
@@ -46,11 +46,11 @@ zend follower --help
 zend comments --help
 zend tickets --limit 10
 zend tickets --status open --limit 20
-zend email user@example.com
-zend email user@example.com --status unresolved
-zend email user@example.com --status open,pending
+zend email foo@example.com
+zend email foo@example.com --status unresolved
+zend email foo@example.com --status open,pending
 zend follower
-zend follower tp@dify.ai --limit 3
+zend follower foo@example.com --limit 3
 zend comments 12345
 zend comments 12345 --type public
 zend comments 12345 --json

package/dist/cli.js

@@ -3512,29 +3512,42 @@ function getConfig() {
 }
 
 // src/api.ts
-function getAuthHeader() {
+var ApiError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+function authHeader() {
   const { email, api_token } = getConfig();
   const credentials = btoa(`${email}/token:${api_token}`);
   return `Basic ${credentials}`;
 }
 async function fetchJson(url) {
-  const resp = await fetch(url, {
-    headers: { Authorization: getAuthHeader() }
-  });
+  let resp;
+  try {
+    resp = await fetch(url, {
+      headers: { Authorization: authHeader() }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Network request failed";
+    throw new ApiError(message);
+  }
   if (!resp.ok) {
     const body = await resp.text();
-    console.error(`Error ${resp.status}: ${body}`);
-    process.exit(1);
+    throw new ApiError(`HTTP ${resp.status}`, resp.status, body);
   }
   return resp.json();
 }
 async function apiGet(path, params) {
   const { subdomain } = getConfig();
   const url = new URL(`https://${subdomain}.zendesk.com${path}`);
-  if (params) {
-    for (const [key, value] of Object.entries(params)) {
-      url.searchParams.set(key, String(value));
-    }
+  for (const [key, value] of Object.entries(params || {})) {
+    url.searchParams.set(key, String(value));
   }
   return fetchJson(url.toString());
 }
@@ -3545,7 +3558,55 @@ async function apiGetUrl(url) {
 // src/cli.ts
 var program2 = new Command();
 var VALID_TICKET_STATUSES = ["new", "open", "pending", "hold", "solved", "closed"];
-program2.name("zend").description("Zendesk tickets & comments CLI").version("0.1.0");
+var KNOWN_COMMANDS = /* @__PURE__ */ new Set(["configure", "follower", "comments", "help", "email", "ticket"]);
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var DIGITS_RE = /^\d+$/;
+var CliError = class extends Error {
+  code;
+  details;
+  exitCode;
+  constructor(code, message, details = {}, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.details = details;
+    this.exitCode = exitCode;
+  }
+};
+program2.name("zend").description("Zendesk tickets CLI").version("2.0.0");
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+function fail(code, message, details = {}, exitCode = 1) {
+  printJson({ error: code, message, ...details });
+  process.exit(exitCode);
+}
+function handleError(error) {
+  if (error instanceof CliError) {
+    fail(error.code, error.message, error.details, error.exitCode);
+  }
+  if (error instanceof ApiError) {
+    if (error.status === 401) {
+      fail("auth_failed", "401 Unauthorized", { status: 401 });
+    }
+    if (error.status === 404) {
+      fail("not_found", "Resource not found", { status: 404 });
+    }
+    fail("api_error", error.body || error.message, error.status ? { status: error.status } : {});
+  }
+  const message = error instanceof Error ? error.message : "Unknown error";
+  fail("unknown_error", message);
+}
+function run(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      handleError(error);
+    }
+  };
+}
 function prompt(question, defaultValue = "") {
   return new Promise((resolve) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
@@ -3562,199 +3623,199 @@ function promptHidden(question, hasDefault = false) {
     const stdout = process.stderr;
     let value = "";
     readline.emitKeypressEvents(stdin);
-    if (stdin.isTTY) {
-      stdin.setRawMode(true);
-    }
-    const suffix = hasDefault ? " [****]" : "";
-    stdout.write(`${question}${suffix}: `);
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdout.write(`${question}${hasDefault ? " [****]" : ""}: `);
     const onKeypress = (char, key) => {
       if (key.name === "return" || key.name === "enter") {
         stdout.write("\n");
         stdin.off("keypress", onKeypress);
-        if (stdin.isTTY) {
-          stdin.setRawMode(false);
-        }
+        if (stdin.isTTY) stdin.setRawMode(false);
         resolve(value);
         return;
       }
       if (key.ctrl && key.name === "c") {
         stdout.write("\n");
         stdin.off("keypress", onKeypress);
-        if (stdin.isTTY) {
-          stdin.setRawMode(false);
-        }
+        if (stdin.isTTY) stdin.setRawMode(false);
         process.exit(130);
       }
       if (key.name === "backspace") {
         value = value.slice(0, -1);
         return;
       }
-      if (char) {
-        value += char;
-      }
+      if (char) value += char;
     };
     stdin.on("keypress", onKeypress);
   });
 }
-function parseStatusFilter(input) {
-  if (!input) return [];
+function parseStatusFilter(input = "unresolved") {
   const statuses = input.split(",").map((value) => value.trim().toLowerCase()).filter(Boolean);
   const invalid = statuses.filter((status) => status !== "unresolved" && status !== "all" && !VALID_TICKET_STATUSES.includes(status));
   if (invalid.length > 0) {
-    console.error(`Invalid status value(s): ${invalid.join(", ")}`);
-    console.error(`Allowed values: unresolved, all, ${VALID_TICKET_STATUSES.join(", ")}`);
-    process.exit(1);
+    throw new CliError("invalid_args", `Invalid status value(s): ${invalid.join(", ")}`, { input });
   }
   if (statuses.includes("all")) return [];
   if (statuses.includes("unresolved")) return ["new", "open", "pending", "hold"];
   return statuses;
 }
-function buildSearchQuery(base, rawStatus, statusFilter, canUseSearchStatus) {
-  let query = base;
-  if (rawStatus === "unresolved") {
-    query += " status<solved";
-  } else if (canUseSearchStatus && statusFilter.length === 1) {
-    query += ` status:${statusFilter[0]}`;
+function parseLimit(input = "20") {
+  const limit = Number.parseInt(input, 10);
+  if (!Number.isFinite(limit) || Number.isNaN(limit)) {
+    throw new CliError("invalid_args", "limit must be an integer", { limit: input });
   }
-  return query;
+  if (limit < 1 || limit > 100) {
+    throw new CliError("invalid_args", "limit must be between 1 and 100", { limit });
+  }
+  return limit;
 }
-function printTickets(tickets, meta) {
-  for (const t of tickets) {
-    const status = (t.status || "").padEnd(8);
-    const subject = t.subject || "(no subject)";
-    console.log(`[${t.id}] ${status} ${subject}`);
-    console.log(meta(t));
-    console.log();
+function parseSort(input = "desc") {
+  if (input !== "asc" && input !== "desc") {
+    throw new CliError("invalid_args", "sort must be asc or desc", { sort: input });
   }
+  return input;
+}
+function buildSearchQuery(base, rawStatus, statusFilter) {
+  if (rawStatus === "unresolved") return `${base} status<solved`;
+  if (statusFilter.length === 1) return `${base} status:${statusFilter[0]}`;
+  return base;
+}
+function filterStatuses(tickets, rawStatus, statusFilter) {
+  if (rawStatus === "unresolved" || statusFilter.length <= 1) return tickets;
+  return tickets.filter((ticket) => statusFilter.includes(String(ticket.status || "").toLowerCase()));
 }
 async function findUserByEmail(email) {
-  const data = await apiGet("/api/v2/users/search.json", {
-    query: email
-  });
-  const user = (data.users || []).find((item) => item.email?.toLowerCase() === email.toLowerCase()) || data.users?.[0];
-  if (!user) {
-    console.error(`No Zendesk user found for email: ${email}`);
-    process.exit(1);
-  }
-  return user;
+  const data = await apiGet("/api/v2/users/search.json", { query: email });
+  const users = data.users || [];
+  const exact = users.find((user) => user.email?.toLowerCase() === email.toLowerCase());
+  if (exact) return exact;
+  if (users[0]) return users[0];
+  throw new CliError("user_not_found", `No Zendesk user found for email: ${email}`, { email });
 }
-async function findFollowerTickets(email, rawStatus, limit, sort) {
+async function fetchFollowerTickets(email, rawStatus, limit, sort) {
   const user = await findUserByEmail(email);
   const statusFilter = parseStatusFilter(rawStatus);
-  const canUseSearchStatus = rawStatus === "unresolved" || statusFilter.length === 1;
-  let url = new URL(`https://${getConfig().subdomain}.zendesk.com/api/v2/search.json`).toString();
-  const params = new URLSearchParams({
-    query: buildSearchQuery("type:ticket", rawStatus, statusFilter, canUseSearchStatus),
-    sort_by: "updated_at",
-    sort_order: sort,
-    per_page: "100"
-  });
-  url += `?${params.toString()}`;
+  const baseUrl = new URL(`${apiBaseUrl()}/api/v2/search.json`);
+  baseUrl.searchParams.set("query", buildSearchQuery("type:ticket", rawStatus, statusFilter));
+  baseUrl.searchParams.set("sort_by", "updated_at");
+  baseUrl.searchParams.set("sort_order", sort);
+  baseUrl.searchParams.set("per_page", "100");
   const matches = [];
-  while (url && matches.length < limit) {
-    const data = await apiGetUrl(url);
-    let tickets = data.results || [];
-    if (statusFilter.length > 0 && rawStatus !== "unresolved" && !canUseSearchStatus) {
-      tickets = tickets.filter((ticket) => statusFilter.includes((ticket.status || "").toLowerCase()));
-    }
+  let nextUrl = baseUrl.toString();
+  while (nextUrl && matches.length < limit) {
+    const data = await apiGetUrl(nextUrl);
+    const tickets = filterStatuses(data.results || [], rawStatus, statusFilter);
     for (const ticket of tickets) {
-      const followers = ticket.follower_ids || [];
-      if (followers.includes(user.id) && ticket.assignee_id !== user.id) {
+      if ((ticket.follower_ids || []).includes(user.id) && ticket.assignee_id !== user.id) {
         matches.push(ticket);
       }
-      if (matches.length >= limit) {
-        break;
-      }
+      if (matches.length >= limit) break;
     }
-    url = data.next_page || null;
+    nextUrl = data.next_page || null;
   }
   return matches;
 }
-program2.command("configure").description("Set up Zendesk credentials interactively").action(async () => {
+function apiBaseUrl() {
+  const { subdomain } = getConfig();
+  return `https://${subdomain}.zendesk.com`;
+}
+program2.command("configure").description("Set up Zendesk credentials interactively").action(run(async () => {
   const existing = loadConfig();
-  console.error("Zendesk CLI Configuration");
-  console.error("\u2500".repeat(30));
+  process.stderr.write("Zendesk CLI Configuration\n");
+  process.stderr.write(`${"\u2500".repeat(30)}
+`);
   const subdomain = await prompt("Subdomain (xxx.zendesk.com)", existing.subdomain);
   const email = await prompt("Email", existing.email);
   const tokenInput = await promptHidden("API Token", Boolean(existing.api_token));
   const api_token = tokenInput || existing.api_token || "";
   saveConfig({ subdomain, email, api_token });
-  console.error("\nSaved to ~/.zendcli/config.json with restricted permissions (0600)");
-  console.error("Environment variables also work: ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_TOKEN");
-});
-program2.command("tickets").description("List tickets from Zendesk, sorted by updated_at").option("--status <status>", "Filter by status (new|open|pending|hold|solved|closed)").option("--limit <n>", "Max tickets to return", "20").option("--sort <order>", "Sort order (asc|desc)", "desc").action(async (opts) => {
-  const limit = parseInt(opts.limit, 10);
-  const data = await apiGet("/api/v2/tickets.json", {
-    per_page: Math.min(limit, 100),
-    sort_order: opts.sort,
-    sort_by: "updated_at"
-  });
-  let tickets = data.tickets || [];
-  if (opts.status) {
-    tickets = tickets.filter((t) => t.status === opts.status);
+  printJson({ ok: true });
+}));
+var TICKET_SUMMARY_FIELDS = [
+  "id",
+  "subject",
+  "description",
+  "status",
+  "priority",
+  "created_at",
+  "updated_at",
+  "tags",
+  "requester_id",
+  "assignee_id",
+  "collaborator_ids",
+  "follower_ids",
+  "organization_id",
+  "group_id",
+  "type",
+  "via",
+  "url"
+];
+function pickTicketFields(ticket) {
+  const result = {};
+  for (const key of TICKET_SUMMARY_FIELDS) {
+    if (key in ticket) result[key] = ticket[key];
   }
-  printTickets(tickets.slice(0, limit), (ticket) => {
-    return `    priority=${ticket.priority ?? "-"}  type=${ticket.type ?? "-"}  created=${ticket.created_at}`;
-  });
-});
-program2.command("email <email>").description("Find tickets for a requester email").option("--status <status>", "Filter status: unresolved|all|new|open|pending|hold|solved|closed or comma-separated list", "unresolved").option("--limit <n>", "Max tickets to return", "20").option("--sort <order>", "Sort order (asc|desc)", "desc").option("--json", "Output raw JSON").action(async (email, opts) => {
-  const limit = parseInt(opts.limit, 10);
+  return result;
+}
+program2.command("ticket <id>").description("Get a single ticket").option("--raw", "Output full API response without field filtering").action(run(async (id, opts) => {
+  if (!DIGITS_RE.test(id)) {
+    throw new CliError("invalid_args", "ticket id must be numeric", { id });
+  }
+  try {
+    const data = await apiGet(`/api/v2/tickets/${id}.json`);
+    if (!data.ticket) {
+      throw new CliError("not_found", `Ticket ${id} not found`, { id: Number(id) });
+    }
+    printJson(opts.raw ? data.ticket : pickTicketFields(data.ticket));
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) {
+      fail("not_found", `Ticket ${id} not found`, { id: Number(id) });
+    }
+    throw error;
+  }
+}));
+program2.command("email <email>").description("Find tickets for an assignee email").option("--status <status>", "unresolved|all|new|open|pending|hold|solved|closed or comma-separated list", "unresolved").option("--limit <n>", "Max tickets to return", "20").option("--sort <order>", "Sort order (asc|desc)", "desc").action(run(async (email, opts) => {
+  const limit = parseLimit(opts.limit);
+  const sort = parseSort(opts.sort);
   const statusFilter = parseStatusFilter(opts.status);
-  const canUseSearchStatus = opts.status === "unresolved" || statusFilter.length === 1;
-  const query = buildSearchQuery(`type:ticket requester:${email}`, opts.status, statusFilter, canUseSearchStatus);
+  const query = buildSearchQuery(`type:ticket assignee:${email}`, opts.status, statusFilter);
   const data = await apiGet("/api/v2/search.json", {
     query,
     sort_by: "updated_at",
-    sort_order: opts.sort,
+    sort_order: sort,
     per_page: 100
   });
-  let tickets = data.results || [];
-  if (statusFilter.length > 0 && opts.status !== "unresolved" && !canUseSearchStatus) {
-    tickets = tickets.filter((ticket) => statusFilter.includes((ticket.status || "").toLowerCase()));
+  const tickets = filterStatuses(data.results || [], opts.status, statusFilter).slice(0, limit);
+  printJson(tickets);
+}));
+program2.command("follower <email>").description("Find tickets where the user is a follower but not the assignee").option("--status <status>", "unresolved|all|new|open|pending|hold|solved|closed or comma-separated list", "unresolved").option("--limit <n>", "Max tickets to return", "20").option("--sort <order>", "Sort order (asc|desc)", "desc").action(run(async (email, opts) => {
+  const limit = parseLimit(opts.limit);
+  const sort = parseSort(opts.sort);
+  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) => {
+  if (!DIGITS_RE.test(ticketId)) {
+    throw new CliError("invalid_args", "ticket id must be numeric", { ticketId });
   }
-  tickets = tickets.slice(0, limit);
-  if (opts.json) {
-    console.log(JSON.stringify(tickets, null, 2));
-    return;
-  }
-  printTickets(tickets, (ticket) => {
-    return `    priority=${ticket.priority ?? "-"}  type=${ticket.type ?? "-"}  requester=${email}  updated=${ticket.updated_at}`;
-  });
-});
-program2.command("follower [email]").description("Find tickets where the user is a follower but not the assignee").option("--status <status>", "Filter status: unresolved|all|new|open|pending|hold|solved|closed or comma-separated list", "unresolved").option("--limit <n>", "Max tickets to return", "20").option("--sort <order>", "Sort order (asc|desc)", "desc").option("--json", "Output raw JSON").action(async (email, opts) => {
-  const targetEmail = email || getConfig().email;
-  const limit = parseInt(opts.limit, 10);
-  const tickets = await findFollowerTickets(targetEmail, opts.status, limit, opts.sort);
-  if (opts.json) {
-    console.log(JSON.stringify(tickets, null, 2));
-    return;
+  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 });
   }
-  printTickets(tickets, (ticket) => {
-    return `    priority=${ticket.priority ?? "-"}  type=${ticket.type ?? "-"}  follower=${targetEmail}  assignee=${ticket.assignee_id ?? "-"}  updated=${ticket.updated_at}`;
-  });
-});
-program2.command("comments <ticketId>").description("List comments/thread for a ticket (public=customer-facing, internal=agents only)").option("--type <type>", "Filter: all|public|internal", "all").option("--sort <order>", "Sort order (asc|desc)", "asc").option("--json", "Output raw JSON").action(async (ticketId, opts) => {
   const data = await apiGet(
     `/api/v2/tickets/${ticketId}/comments.json`,
-    { sort_order: opts.sort, per_page: 100 }
+    { sort_order: sort, per_page: 100 }
   );
   let comments = data.comments || [];
-  if (opts.type === "public") {
-    comments = comments.filter((c) => c.public === true);
-  } else if (opts.type === "internal") {
-    comments = comments.filter((c) => c.public === false);
-  }
-  if (opts.json) {
-    console.log(JSON.stringify(comments, null, 2));
-    return;
-  }
-  for (const c of comments) {
-    const label = c.public ? "PUBLIC" : "INTERNAL";
-    const via = c.via?.channel ?? "?";
-    console.log(`--- [${label}] id=${c.id}  author=${c.author_id}  via=${via}  ${c.created_at} ---`);
-    const body = (c.plain_body || c.body || "").trim();
-    console.log(body);
-    console.log();
-  }
-});
+  if (opts.type === "public") comments = comments.filter((comment) => comment.public === true);
+  if (opts.type === "internal") comments = comments.filter((comment) => comment.public === false);
+  printJson(comments);
+}));
+function preprocessArgv(argv) {
+  const firstArg = argv[2];
+  if (!firstArg || firstArg.startsWith("-") || KNOWN_COMMANDS.has(firstArg)) return argv;
+  if (EMAIL_RE.test(firstArg)) return [...argv.slice(0, 2), "email", ...argv.slice(2)];
+  if (DIGITS_RE.test(firstArg)) return [...argv.slice(0, 2), "ticket", ...argv.slice(2)];
+  return argv;
+}
+process.argv = preprocessArgv(process.argv);
 program2.parse();

package/package.json

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