unbound-cli 1.14.0 → 1.15.0

package/src/commands/download.js

@@ -0,0 +1,245 @@
+const config = require('../config');
+const output = require('../output');
+const downloads = require('../lib/downloads');
+
+const { KINDS, MAX_EXPORT_ROWS, RETENTION_HOURS } = downloads;
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    throw new Error('Not logged in. Run `unbound login` first.');
+  }
+}
+
+const KIND_LIST = Object.entries(KINDS)
+  .map(([kind, meta]) => `  ${kind.padEnd(23)} ${meta.summary}`)
+  .join('\n');
+
+const AGENT_HELP = `
+AGENTS / SCRIPTING
+  A CSV export is prepared by a background worker, so it is three steps. This
+  command does all three and blocks until the file is on disk:
+
+    1. POST   starts a job and returns its ID
+    2. GET    polls the job until it is completed
+    3. GET    signs a short-lived URL and streams the file down
+
+  Exit code is 0 on success and 1 on any error. Diagnostics go to stderr, so
+  stdout carries only the CSV and is safe to pipe.
+
+  Check before you commit — this counts rows without starting anything:
+
+    $ unbound download start logs-export --check --last 7d --json
+    {"row_count":18204,"limit":25000,"exceeds_limit":false,"exact":true}
+
+  A selection over ${MAX_EXPORT_ROWS.toLocaleString()} rows is refused up front with the real count, so
+  narrow the range and retry rather than paging.
+
+  If you stop waiting, the job keeps running. Fetch it within ${RETENTION_HOURS} hours:
+
+    $ unbound download get <job-id> -o out.csv
+
+  Only 3 exports may be preparing at once per organization; a 4th returns an
+  error telling you to wait. Do not poll by re-running the export.
+`;
+
+const FILTER_HELP = `
+TIME RANGE
+  Omit it and the server applies its own default window. --start/--end may be at
+  most 90 days apart, and cannot start earlier than 90 days ago.
+
+FILTERS
+  Repeat --filter with the same key to pass a list; each is sent as its own
+  value, which is how the server reads list filters:
+
+    --filter tool_types=CLAUDE_CODE --filter tool_types=CURSOR
+
+  An unknown filter KEY is silently ignored, so a typo widens the export rather
+  than failing — 'tool_type=CURSOR' returns every tool. An invalid VALUE for a
+  known key IS rejected, with the supported values listed. Run --check first and
+  confirm the count moved.
+`;
+
+/** `--last 7d` / `--last 24h` -> an absolute window the server understands. */
+function resolveLast(value) {
+  const match = String(value).trim().match(/^(\d+)\s*([dh])$/i);
+  if (!match) {
+    throw new Error(`Invalid --last "${value}". Use a number followed by d or h, e.g. 7d or 24h.`);
+  }
+  const amount = Number(match[1]);
+  if (amount < 1) throw new Error('--last must be at least 1.');
+  const hours = match[2].toLowerCase() === 'd' ? amount * 24 : amount;
+  const end = new Date();
+  const start = new Date(end.getTime() - hours * 3600 * 1000);
+  return { start, end };
+}
+
+function buildQueryString(opts) {
+  const params = new URLSearchParams();
+
+  if (opts.last && (opts.start || opts.end)) {
+    throw new Error('Use --last or --start/--end, not both.');
+  }
+  if (Boolean(opts.start) !== Boolean(opts.end)) {
+    throw new Error('--start and --end must be used together.');
+  }
+
+  if (opts.last) {
+    const { start, end } = resolveLast(opts.last);
+    params.set('start_date', start.toISOString());
+    params.set('end_date', end.toISOString());
+  } else if (opts.start) {
+    params.set('start_date', opts.start);
+    params.set('end_date', opts.end);
+  }
+
+  if (opts.search) params.set('search', opts.search);
+
+  // Repeated keys are appended, not replaced: every list filter on the server
+  // reads getlist(), so collapsing duplicates would silently drop all but one.
+  for (const entry of opts.filter || []) {
+    const index = String(entry).indexOf('=');
+    if (index <= 0) {
+      throw new Error(`Invalid --filter "${entry}". Use key=value, e.g. --filter tool_types=CURSOR.`);
+    }
+    params.append(entry.slice(0, index).trim(), entry.slice(index + 1));
+  }
+
+  return params.toString();
+}
+
+async function runDownload(kind, opts) {
+  const query = buildQueryString(opts);
+
+  if (opts.check) {
+    const result = await downloads.checkCount(kind, query);
+    if (opts.json) {
+      output.json(result);
+      return;
+    }
+    const rows = Number(result.row_count);
+    if (!Number.isFinite(rows)) {
+      output.info('This export does not report a row count up front.');
+      return;
+    }
+    if (result.exceeds_limit) {
+      output.warn(
+        `${rows.toLocaleString()} rows, over the ${Number(result.limit).toLocaleString()}-row limit. ` +
+        'Narrow the range or add filters before exporting.'
+      );
+      return;
+    }
+    output.info(`${rows.toLocaleString()} row(s) would be exported.`);
+    return;
+  }
+
+  if (opts.wait === false) {
+    const job = await downloads.startJob(kind, query);
+    if (opts.json) {
+      output.json(job);
+      return;
+    }
+    output.success(`Export started. ${downloads.fetchHint(job.id)}`);
+    return;
+  }
+
+  await downloads.runExport(kind, query, { output: opts.output });
+}
+
+function register(program) {
+  // A group with no arguments and no options of its own. Commander binds a
+  // repeated flag on the parent, so `-o` declared on both here and on `get`
+  // would leave the subcommand's value undefined and silently write to stdout.
+  const group = program
+    .command('download')
+    .description('Export org data as CSV (Logs, Tasks, Users, Tool Use).')
+    .addHelpText('after', `
+KINDS
+${KIND_LIST}
+
+Examples:
+  $ unbound download kinds
+  $ unbound download start logs-export --last 7d
+  $ unbound download start logs-export --check --last 90d --json
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6
+
+Admin role required. Exports are kept for ${RETENTION_HOURS} hours.
+`);
+
+  group
+    .command('kinds')
+    .description('List what can be exported, and the filters each kind accepts.')
+    .option('--json', 'Machine-readable output')
+    .action((opts) => {
+      if (opts.json) {
+        output.json(Object.entries(KINDS).map(([kind, meta]) => ({ kind, ...meta })));
+        return;
+      }
+      for (const [kind, meta] of Object.entries(KINDS)) {
+        console.log(`${kind}\n  ${meta.summary}\n  filters: ${meta.filters.join(', ')}\n`);
+      }
+    });
+
+  const command = group
+    .command('start <kind>')
+    .description('Start an export and wait for the file.')
+    .option('--last <window>', 'Relative range, e.g. 7d or 24h')
+    .option('--start <date>', 'Range start, YYYY-MM-DD (use with --end)')
+    .option('--end <date>', 'Range end, YYYY-MM-DD (use with --start)')
+    .option('--search <text>', 'Free-text filter (logs kinds only)')
+    .option('--filter <key=value>', 'Server-side filter, repeatable', (value, previous) => (previous || []).concat(value))
+    .option('-o, --output <file>', 'Write to a file instead of the server-chosen name')
+    .option('--check', 'Print how many rows would be exported, then exit')
+    .option('--json', 'Machine-readable output')
+    .option('--no-wait', 'Start the export and print its job ID instead of waiting')
+    .addHelpText('after', `
+KINDS
+${KIND_LIST}
+
+Examples:
+  $ unbound download start logs-export --last 7d
+  $ unbound download start logs-export --last 24h --filter tool_types=CLAUDE_CODE -o today.csv
+  $ unbound download start logs-tasks-export --start 2026-07-01 --end 2026-07-31
+  $ unbound download start users-export --last 30d
+  $ unbound download start analytics-export --filter dataset=terminal-runs --last 7d
+  $ unbound download start logs-export --check --last 90d --json
+
+Admin role required. Exports are kept for ${RETENTION_HOURS} hours.
+${FILTER_HELP}${AGENT_HELP}`)
+    .action(async (kind, opts) => {
+      try {
+        requireLogin();
+        await runDownload(kind, opts);
+      } catch (err) {
+        output.error(downloads.describeError(err, `${kind} export`));
+        process.exitCode = 1;
+      }
+    });
+
+  group
+    .command('get <job-id>')
+    .description('Download an export that was already started, by its job ID.')
+    .option('-o, --output <file>', 'Write to a file instead of the server-chosen name')
+    .addHelpText('after', `
+Exports run in the background. If you interrupted the wait, or used --no-wait,
+this fetches the finished file. If the job is still running, it waits for it.
+
+Exports are kept for ${RETENTION_HOURS} hours.
+
+Examples:
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6 -o july.csv
+`)
+    .action(async (jobId, opts) => {
+      try {
+        requireLogin();
+        await downloads.fetchExisting(jobId, { output: opts.output });
+      } catch (err) {
+        output.error(downloads.describeError(err, 'export', { byJobId: true }));
+        process.exitCode = 1;
+      }
+    });
+
+  return command;
+}
+
+module.exports = { register, buildQueryString, resolveLast };

package/src/index.js

@@ -155,6 +155,18 @@ TOOL CONNECTIONS
   $ unbound tools connect <type>           Connect a new tool
   $ unbound tools approved                 List approved tool types
 
+ANALYTICS (Admin/Manager; CSV export is Admin-only)
+  $ unbound analytics tool-use terminal     Terminal commands agents ran
+  $ unbound analytics tool-use mcp-servers  MCP servers seen (find --server values here)
+  $ unbound analytics tool-use mcp-actions --server Notion
+                                           MCP tool calls for one service
+  $ unbound analytics tool-use unsanctioned Blocked/warned unsanctioned MCP usage
+
+  Every dataset takes --format table|json|csv, -o <file>, --limit/--offset,
+  --time-window or --start/--end, and filters (--tool --user --risk --policy).
+  csv exports every matching row, not just the page.
+  See "unbound analytics tool-use --help" for the JSON contract used by agents.
+
 CHAT (Admin/Manager)
   $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
   $ unbound chat -m "show cost by provider for the last 30 days"
@@ -196,6 +208,8 @@ require('./commands/policy').register(program);
 require('./commands/users').register(program);
 require('./commands/user-groups').register(program);
 require('./commands/tools').register(program);
+require('./commands/analytics').register(program);
+require('./commands/download').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);

package/src/lib/analytics-query.js

@@ -0,0 +1,216 @@
+/**
+ * Flag parsing and query-string construction for `unbound analytics tool-use`.
+ * Pure functions — no network, no process state — so they are unit-testable.
+ */
+
+const TIME_WINDOWS = [
+  'ONE_DAY',
+  'THREE_DAYS',
+  'SEVEN_DAYS',
+  'FOURTEEN_DAYS',
+  'THIRTY_DAYS',
+  'THREE_MONTHS',
+];
+
+const FORMATS = ['table', 'json', 'csv'];
+
+const RISK_LEVELS = ['Low', 'Medium', 'High'];
+
+const INITIATORS = {
+  user: 'USER_INTENTIONAL',
+  agent: 'AGENT_INITIATED',
+  unknown: 'UNKNOWN',
+};
+
+// The backend rejects a custom range wider than this.
+const MAX_RANGE_DAYS = 90;
+
+const DEFAULT_TIME_WINDOW = 'THIRTY_DAYS';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 1000;
+// Lower for the table: past roughly a screenful nobody reads the rows, they
+// scroll past them. json is parsed rather than read, so it keeps the full cap.
+const MAX_TABLE_LIMIT = 100;
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function parseList(value) {
+  if (value === undefined || value === null) return [];
+  const items = Array.isArray(value) ? value : String(value).split(',');
+  return items.map((v) => String(v).trim()).filter(Boolean);
+}
+
+function resolveFormat(opts) {
+  if (opts.json && opts.format && opts.format !== 'json') {
+    throw new Error(`Cannot combine --json with --format ${opts.format}.`);
+  }
+  const format = opts.json ? 'json' : (opts.format || 'table');
+  if (!FORMATS.includes(format)) {
+    throw new Error(`Invalid --format "${format}". Must be one of: ${FORMATS.join(', ')}.`);
+  }
+  return format;
+}
+
+function resolveWindow(opts) {
+  const hasStart = Boolean(opts.start);
+  const hasEnd = Boolean(opts.end);
+
+  if (hasStart !== hasEnd) {
+    throw new Error('--start and --end must be used together.');
+  }
+
+  if (hasStart) {
+    if (opts.timeWindow) {
+      throw new Error('Cannot combine --time-window with --start/--end. Pick one.');
+    }
+    for (const [flag, value] of [['--start', opts.start], ['--end', opts.end]]) {
+      if (!DATE_RE.test(value)) {
+        throw new Error(`Invalid ${flag} "${value}". Expected YYYY-MM-DD.`);
+      }
+    }
+    const start = new Date(`${opts.start}T00:00:00Z`);
+    const end = new Date(`${opts.end}T00:00:00Z`);
+    // Round-tripped, not just checked for NaN: Date rolls an impossible day
+    // into the next month, so 2026-02-30 parses happily as March 2.
+    const isRealDate = (value, parsed) =>
+      !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+    if (!isRealDate(opts.start, start) || !isRealDate(opts.end, end)) {
+      throw new Error('--start and --end must be real calendar dates (YYYY-MM-DD).');
+    }
+    if (start > end) {
+      throw new Error('--start must be on or before --end.');
+    }
+    const spanDays = Math.round((end - start) / 86400000);
+    if (spanDays > MAX_RANGE_DAYS) {
+      throw new Error(`Date range is ${spanDays} days; the maximum is ${MAX_RANGE_DAYS}.`);
+    }
+    return { start_date: opts.start, end_date: opts.end };
+  }
+
+  const timeWindow = (opts.timeWindow || DEFAULT_TIME_WINDOW).toUpperCase().replace(/-/g, '_');
+  if (!TIME_WINDOWS.includes(timeWindow)) {
+    throw new Error(
+      `Invalid --time-window "${opts.timeWindow}". Must be one of: ${TIME_WINDOWS.join(', ')}.`
+    );
+  }
+  return { time_window: timeWindow };
+}
+
+function resolveLimit(opts, format = 'json') {
+  if (opts.limit === undefined) return DEFAULT_LIMIT;
+  const limit = Number(opts.limit);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error(`Invalid --limit "${opts.limit}". Must be a positive integer.`);
+  }
+  const max = format === 'table' ? MAX_TABLE_LIMIT : MAX_LIMIT;
+  if (limit > max) {
+    throw new Error(
+      `--limit cannot exceed ${max} for ${format} output. ` +
+      (format === 'table'
+        ? `Use --format json for up to ${MAX_LIMIT}, or --format csv to export everything.`
+        : 'Use --format csv to export everything.')
+    );
+  }
+  return limit;
+}
+
+function resolveOffset(opts) {
+  if (opts.offset === undefined) return 0;
+  const offset = Number(opts.offset);
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error(`Invalid --offset "${opts.offset}". Must be zero or a positive integer.`);
+  }
+  return offset;
+}
+
+function resolveRiskLevels(opts) {
+  const wanted = parseList(opts.risk);
+  return wanted.map((raw) => {
+    const match = RISK_LEVELS.find((level) => level.toLowerCase() === raw.toLowerCase());
+    if (!match) {
+      throw new Error(`Invalid --risk "${raw}". Must be one of: ${RISK_LEVELS.join(', ')}.`);
+    }
+    return match;
+  });
+}
+
+function resolveInitiators(opts) {
+  const wanted = parseList(opts.initiator);
+  return wanted.map((raw) => {
+    const mapped = INITIATORS[raw.toLowerCase()];
+    if (!mapped) {
+      throw new Error(
+        `Invalid --initiator "${raw}". Must be one of: ${Object.keys(INITIATORS).join(', ')}.`
+      );
+    }
+    return mapped;
+  });
+}
+
+/**
+ * Turn parsed commander options into the export endpoint's query object.
+ * Repeated keys are represented as arrays; buildQueryString expands them.
+ */
+function buildQuery(opts, { format, extra = {} } = {}) {
+  const query = {
+    format: format === 'table' ? 'json' : format,
+    ...resolveWindow(opts),
+    ...extra,
+  };
+
+  if (query.format === 'json') {
+    // `format` is the caller's intent; query.format is what the server speaks,
+    // and the table asks the server for json. The cap follows the intent.
+    query.limit = resolveLimit(opts, format);
+    const offset = resolveOffset(opts);
+    if (offset) query.offset = offset;
+  }
+
+  const lists = {
+    tool_types: parseList(opts.tool).map((t) => t.toUpperCase().replace(/-/g, '_')),
+    user_ids: parseList(opts.user),
+    policy_ids: parseList(opts.policy),
+    command_families: parseList(opts.family),
+    server: parseList(opts.server),
+    risk_levels: resolveRiskLevels(opts),
+    intent_attribution: resolveInitiators(opts),
+  };
+
+  for (const [key, values] of Object.entries(lists)) {
+    if (values.length) query[key] = values;
+  }
+
+  return query;
+}
+
+function buildQueryString(query) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item));
+    } else {
+      params.append(key, String(value));
+    }
+  }
+  return params.toString();
+}
+
+module.exports = {
+  DEFAULT_LIMIT,
+  DEFAULT_TIME_WINDOW,
+  FORMATS,
+  INITIATORS,
+  MAX_LIMIT,
+  MAX_TABLE_LIMIT,
+  MAX_RANGE_DAYS,
+  RISK_LEVELS,
+  TIME_WINDOWS,
+  buildQuery,
+  buildQueryString,
+  parseList,
+  resolveFormat,
+  resolveLimit,
+  resolveOffset,
+  resolveWindow,
+};