@tplog/zendcli 0.1.1 → 0.2.3

package/README.md

@@ -0,0 +1,142 @@
+# zendcli
+
+Minimal Zendesk CLI for listing tickets and reading ticket comment threads.
+
+## Install
+
+```bash
+npm install -g @tplog/zendcli
+```
+
+## Configure
+
+### Option 1: interactive setup
+
+```bash
+zend configure
+```
+
+Credentials are stored locally in:
+
+```bash
+~/.zendcli/config.json
+```
+
+The CLI writes this file with restricted permissions.
+
+### Option 2: environment variables
+
+This is the recommended option for temporary or CI usage.
+
+```bash
+export ZENDESK_SUBDOMAIN="your-subdomain"
+export ZENDESK_EMAIL="you@example.com"
+export ZENDESK_API_TOKEN="your_zendesk_api_token"
+```
+
+Environment variables take precedence over the config file.
+
+## Usage
+
+```bash
+zend --help
+zend tickets --help
+zend email --help
+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 follower
+zend follower tp@dify.ai --limit 3
+zend comments 12345
+zend comments 12345 --type public
+zend comments 12345 --json
+```
+
+## Development workflow
+
+### Daily development
+
+1. Create a feature branch from `main`
+2. Develop locally
+3. Commit as needed
+4. Push branch to GitHub
+5. Open a PR to `main`
+6. Merge after CI passes
+
+Example:
+
+```bash
+git checkout main
+git pull
+git checkout -b feat/some-change
+
+# work locally
+npm ci
+npm run build
+
+git add .
+git commit -m "feat: add some change"
+git push -u origin feat/some-change
+```
+
+## Release workflow
+
+This repository uses a safer release flow:
+
+- normal merges to `main` do **not** publish automatically
+- npm publishing happens only when a version tag is pushed
+- the release tag must match `package.json` version exactly
+
+### Publish a new version
+
+1. Make sure `main` is in the state you want to release
+2. Bump the version locally
+3. Push `main` and the new tag
+4. GitHub Actions publishes to npm
+
+```bash
+git checkout main
+git pull
+npm version patch
+git push origin main --tags
+```
+
+Or for a feature release:
+
+```bash
+npm version minor
+git push origin main --tags
+```
+
+This creates tags like `v0.1.2`, and the publish workflow verifies that the tag matches `package.json`.
+
+## CI/CD
+
+- `CI`: runs on branch pushes, PRs to `main`, and pushes to `main`
+- `Publish to npm`: runs only on `v*` tags or manual trigger
+
+## Trusted publishing
+
+The publish workflow is set up for npm trusted publishing via GitHub Actions OIDC.
+
+Recommended setup on npm:
+
+1. Go to the package settings on npm
+2. Add a Trusted Publisher for GitHub Actions
+3. Point it to:
+   - owner: `tplog`
+   - repo: `zendcli`
+   - workflow file: `publish.yml`
+
+This avoids storing long-lived npm tokens in the repository.
+
+## Security notes
+
+- Never commit real Zendesk credentials
+- Prefer environment variables for temporary use
+- If a token is ever exposed, revoke and rotate it immediately
+- Do not store npm publish credentials in the repo or in gitignored files

package/dist/cli.js

@@ -3478,37 +3478,48 @@ var import_os = require("os");
 var import_path = require("path");
 var CONFIG_DIR = (0, import_path.join)((0, import_os.homedir)(), ".zendcli");
 var CONFIG_FILE = (0, import_path.join)(CONFIG_DIR, "config.json");
+function getEnvConfig() {
+  return {
+    subdomain: process.env.ZENDESK_SUBDOMAIN,
+    email: process.env.ZENDESK_EMAIL,
+    api_token: process.env.ZENDESK_API_TOKEN
+  };
+}
 function loadConfig() {
+  const envConfig = getEnvConfig();
+  let fileConfig = {};
   if ((0, import_fs.existsSync)(CONFIG_FILE)) {
-    return JSON.parse((0, import_fs.readFileSync)(CONFIG_FILE, "utf-8"));
+    fileConfig = JSON.parse((0, import_fs.readFileSync)(CONFIG_FILE, "utf-8"));
   }
-  return {};
+  return {
+    ...fileConfig,
+    ...Object.fromEntries(Object.entries(envConfig).filter(([, value]) => value))
+  };
 }
 function saveConfig(config) {
-  (0, import_fs.mkdirSync)(CONFIG_DIR, { recursive: true });
-  (0, import_fs.writeFileSync)(CONFIG_FILE, JSON.stringify(config, null, 2));
+  (0, import_fs.mkdirSync)(CONFIG_DIR, { recursive: true, mode: 448 });
+  (0, import_fs.chmodSync)(CONFIG_DIR, 448);
+  (0, import_fs.writeFileSync)(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 384 });
+  (0, import_fs.chmodSync)(CONFIG_FILE, 384);
 }
 function getConfig() {
   const config = loadConfig();
   if (!config.subdomain || !config.email || !config.api_token) {
-    console.error("Not configured. Run: zend configure");
+    console.error("Not configured. Run: zend configure or set ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_TOKEN");
     process.exit(1);
   }
   return config;
 }
 
 // src/api.ts
-async function apiGet(path, params) {
-  const { subdomain, email, api_token } = 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));
-    }
-  }
+function getAuthHeader() {
+  const { email, api_token } = getConfig();
   const credentials = btoa(`${email}/token:${api_token}`);
-  const resp = await fetch(url.toString(), {
-    headers: { Authorization: `Basic ${credentials}` }
+  return `Basic ${credentials}`;
+}
+async function fetchJson(url) {
+  const resp = await fetch(url, {
+    headers: { Authorization: getAuthHeader() }
   });
   if (!resp.ok) {
     const body = await resp.text();
@@ -3517,29 +3528,159 @@ async function apiGet(path, params) {
   }
   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));
+    }
+  }
+  return fetchJson(url.toString());
+}
+async function apiGetUrl(url) {
+  return fetchJson(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");
-function prompt(question, defaultValue = "", hidden = false) {
+function prompt(question, defaultValue = "") {
   return new Promise((resolve) => {
     const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-    const suffix = defaultValue ? ` [${hidden ? "****" : defaultValue}]` : "";
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
     rl.question(`${question}${suffix}: `, (answer) => {
       rl.close();
       resolve(answer || defaultValue);
     });
   });
 }
+function promptHidden(question, hasDefault = false) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stderr;
+    let value = "";
+    readline.emitKeypressEvents(stdin);
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+    const suffix = hasDefault ? " [****]" : "";
+    stdout.write(`${question}${suffix}: `);
+    const onKeypress = (char, key) => {
+      if (key.name === "return" || key.name === "enter") {
+        stdout.write("\n");
+        stdin.off("keypress", onKeypress);
+        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);
+        }
+        process.exit(130);
+      }
+      if (key.name === "backspace") {
+        value = value.slice(0, -1);
+        return;
+      }
+      if (char) {
+        value += char;
+      }
+    };
+    stdin.on("keypress", onKeypress);
+  });
+}
+function parseStatusFilter(input) {
+  if (!input) return [];
+  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);
+  }
+  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]}`;
+  }
+  return query;
+}
+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();
+  }
+}
+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;
+}
+async function findFollowerTickets(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 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()));
+    }
+    for (const ticket of tickets) {
+      const followers = ticket.follower_ids || [];
+      if (followers.includes(user.id) && ticket.assignee_id !== user.id) {
+        matches.push(ticket);
+      }
+      if (matches.length >= limit) {
+        break;
+      }
+    }
+    url = data.next_page || null;
+  }
+  return matches;
+}
 program2.command("configure").description("Set up Zendesk credentials interactively").action(async () => {
   const existing = loadConfig();
   console.error("Zendesk CLI Configuration");
   console.error("\u2500".repeat(30));
   const subdomain = await prompt("Subdomain (xxx.zendesk.com)", existing.subdomain);
   const email = await prompt("Email", existing.email);
-  const api_token = await prompt("API Token", existing.api_token, true);
+  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");
+  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);
@@ -3552,13 +3693,45 @@ program2.command("tickets").description("List tickets from Zendesk, sorted by up
   if (opts.status) {
     tickets = tickets.filter((t) => t.status === opts.status);
   }
-  for (const t of tickets.slice(0, limit)) {
-    const status = (t.status || "").padEnd(8);
-    const subject = t.subject || "(no subject)";
-    console.log(`[${t.id}] ${status} ${subject}`);
-    console.log(`    priority=${t.priority ?? "-"}  type=${t.type ?? "-"}  created=${t.created_at}`);
-    console.log();
+  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);
+  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 data = await apiGet("/api/v2/search.json", {
+    query,
+    sort_by: "updated_at",
+    sort_order: opts.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()));
   }
+  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;
+  }
+  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(

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@tplog/zendcli",
-  "version": "0.1.1",
+  "version": "0.2.3",
   "description": "Minimal Zendesk CLI for tickets and comments",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tplog/zendcli.git"
+  },
+  "homepage": "https://github.com/tplog/zendcli#readme",
+  "bugs": {
+    "url": "https://github.com/tplog/zendcli/issues"
+  },
   "bin": {
     "zend": "dist/cli.js"
   },