quoxcli 0.3.1 → 0.5.0

package/lib/commands/inboxq.js

@@ -0,0 +1,147 @@
+/**
+ * `quox inboxq`: InboxQ email namespace. Today: `inboxq watch`, awaited-mail
+ * alerts (collector: /api/v1/inboxq/watches, org resolved server-side).
+ *
+ * `quox inbox` is the HITL approvals inbox and `quox watch` is fleet
+ * monitoring; neither is touched here.
+ */
+
+import { formatOutput } from '../core/output.js';
+import { QuoxApiError, QuoxError } from '../core/errors.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const ZONES = ['focus', 'fyi', 'auto', 'screened'];
+const CHANNELS = ['hitl', 'lucid', 'telegram', 'discord', 'call', 'sms'];
+const NEEDS_DESTINATION = ['telegram', 'discord', 'call', 'sms'];
+
+const isJson = (program) => program.opts().output === 'json';
+const printJson = (d) => console.log(JSON.stringify(d, null, 2));
+
+async function call(fn) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e instanceof QuoxApiError && e.status === 404) throw new QuoxError('Watch not found.', 1);
+    throw e;
+  }
+}
+
+export function describeMatch(match = {}) {
+  const parts = [];
+  if (match.from) parts.push(`from~${match.from}`);
+  if (match.subject) parts.push(`subject~${match.subject}`);
+  if (match.text) parts.push(`text~${match.text}`);
+  if (match.zone) parts.push(`zone=${match.zone}`);
+  return parts.join(' ') || '(any)';
+}
+
+export function parseNotify(csv) {
+  const list = String(csv ?? 'hitl').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (list.length === 0) throw new QuoxError(`--notify needs at least one of: ${CHANNELS.join(', ')}`, 2);
+  const bad = list.filter((c) => !CHANNELS.includes(c));
+  if (bad.length) throw new QuoxError(`Unknown --notify channel: ${bad.join(', ')}. Use: ${CHANNELS.join(', ')}`, 2);
+  return [...new Set(list)];
+}
+
+export function registerInboxqCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const inboxq = program
+    .command('inboxq')
+    .description('InboxQ email: awaited-mail watches (not the HITL approvals inbox, see `quox inbox`)');
+
+  const watch = inboxq
+    .command('watch')
+    .description('Awaited-mail alerts: get told when a matching email arrives');
+
+  watch
+    .command('add')
+    .description('Create a watch. At least one of --from, --subject, --text, --zone is required')
+    .option('--account <id>', 'mail account id; omit to watch across all your mailboxes')
+    .requiredOption('--label <text>', 'short name for this watch')
+    .option('--from <addr>', 'sender contains this text')
+    .option('--subject <text>', 'subject contains this text')
+    .option('--text <keyword>', 'message text contains this keyword')
+    .option('--zone <zone>', `only mail triaged into this zone (${ZONES.join('|')})`)
+    .option('--notify <csv>', `alert channels, comma list of ${CHANNELS.join('|')}`, 'hitl')
+    .action(async (options) => {
+      auth.requireAuth();
+      const match = {};
+      if (options.from) match.from = options.from;
+      if (options.subject) match.subject = options.subject;
+      if (options.text) match.text = options.text;
+      if (options.zone) {
+        if (!ZONES.includes(options.zone)) throw new QuoxError(`--zone must be one of: ${ZONES.join(', ')}`, 2);
+        match.zone = options.zone;
+      }
+      if (Object.keys(match).length === 0) {
+        throw new QuoxError('Give at least one of --from, --subject, --text or --zone, or the watch would match nothing in particular.', 2);
+      }
+      const notify = parseNotify(options.notify);
+      const ep = resolveEndpoint('inboxq.watches.create');
+      const data = await call(() => client.post(ep.path, {
+        service: ep.service,
+        body: { accountId: options.account, label: options.label, match, notify },
+      }));
+      if (isJson(program)) return printJson(data);
+      const w = data.watch || {};
+      console.log(`Watch ${w.id} created: "${options.label}" watches ${describeMatch(match)}; alerts via ${notify.join(', ')}.`);
+      const needs = notify.filter((c) => NEEDS_DESTINATION.includes(c));
+      if (needs.length) {
+        console.log(`Note: ${needs.join(', ')} need a destination configured, otherwise they will report unconfigured. hitl and lucid work out of the box.`);
+      }
+    });
+
+  watch
+    .command('list')
+    .description('List watches')
+    .option('--account <id>', 'only watches for this mail account')
+    .option('--json', 'print JSON')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('inboxq.watches.list');
+      const data = await call(() => client.get(ep.path, { service: ep.service }));
+      let watches = data.watches || [];
+      if (options.account) watches = watches.filter((w) => w.accountId === options.account);
+      if (options.json || isJson(program)) return printJson({ ...data, watches });
+      if (watches.length === 0) return console.log('No watches.');
+      formatOutput({
+        columns: ['id', 'label', 'matches', 'notify', 'active', 'hits'],
+        headers: ['ID', 'Label', 'Matches', 'Notify', 'Active', 'Hits'],
+        rows: watches.map((w) => ({
+          id: w.id,
+          label: w.label,
+          matches: describeMatch(w.match),
+          notify: (w.notify || []).join(','),
+          active: w.active ? 'yes' : 'no',
+          hits: w.hitCount ?? 0,
+        })),
+      }, { format: program.opts().output });
+    });
+
+  for (const [name, active, past] of [['pause', false, 'paused'], ['resume', true, 'resumed']]) {
+    watch
+      .command(name)
+      .description(`${name === 'pause' ? 'Pause' : 'Resume'} a watch`)
+      .argument('<watchId>', 'watch id')
+      .action(async (watchId) => {
+        auth.requireAuth();
+        const ep = resolveEndpoint('inboxq.watches.active', { watchId });
+        const data = await call(() => client.post(ep.path, { service: ep.service, body: { active } }));
+        if (isJson(program)) return printJson(data);
+        console.log(`Watch ${watchId} ${past}.`);
+      });
+  }
+
+  watch
+    .command('rm')
+    .description('Delete a watch')
+    .argument('<watchId>', 'watch id')
+    .action(async (watchId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('inboxq.watches.delete', { watchId });
+      const data = await call(() => client.delete(ep.path, { service: ep.service }));
+      if (isJson(program)) return printJson(data);
+      console.log(`Watch ${watchId} deleted.`);
+    });
+}