@jacebenson/jsn 4.2.1 → 4.2.3

package/src/commands/instance.js

@@ -0,0 +1,362 @@
+import { declareCapabilities } from '../capabilities.js';
+
+// The report separates activity in the selected window from current totals.
+// Missing or protected tables stay visible as unavailable instead of aborting
+// the whole report.
+const DATA_VOLUME = [
+  ['Task records', 'task'],
+  ['Incidents', 'incident'],
+  ['Catalog tasks', 'sc_task'],
+  ['Requested items', 'sc_req_item'],
+  ['Requests', 'sc_request'],
+  ['Problems', 'problem'],
+  ['Change requests', 'change_request'],
+  ['CMDB CI records', 'cmdb_ci'],
+];
+const DATA_VOLUME_CONCURRENCY = 2;
+const DATA_VOLUME_TIMEOUT = 120000;
+
+const CONFIGURED_AUTOMATION = [
+  ['Scripted REST APIs', 'sys_ws_definition'],
+  ['Scripted REST operations', 'sys_ws_operation'],
+  ['Inbound email actions', 'sysevent_in_email_action'],
+  ['SOAP messages', 'sys_soap_message'],
+  ['Scheduled scripts', 'sysauto_script'],
+  ['Async business rules', 'sys_script', 'when=async'],
+];
+
+declareCapabilities('instance', {});
+
+function nextDate(date) {
+  const next = new Date(`${date}T00:00:00Z`);
+  if (Number.isNaN(next.getTime())) return '';
+  next.setUTCDate(next.getUTCDate() + 1);
+  return next.toISOString().slice(0, 10);
+}
+
+export function buildActivityQuery({ query, since, until } = {}) {
+  if (query) return String(query);
+  const clauses = [];
+  if (since) clauses.push(`sys_created_on>=${since}`);
+  if (until) clauses.push(`sys_created_on<${nextDate(until) || until}`);
+  if (clauses.length) return clauses.join('^');
+  return 'sys_created_on>=javascript:gs.daysAgoStart(1)';
+}
+
+function addQuery(base, extra) {
+  return [base, extra].filter(Boolean).join('^');
+}
+
+function numeric(value) {
+  const number = Number(String(value ?? '').replaceAll(',', ''));
+  return Number.isFinite(number) ? number : null;
+}
+
+function groupField(group, field) {
+  return group?.groupby_fields?.find(item => item?.field === field)?.value || 'unknown';
+}
+
+function groupCount(group) {
+  return numeric(group?.stats?.count ?? group?.count) ?? 0;
+}
+
+function metricValue(stats, metric, field) {
+  const value = stats?.[metric];
+  return numeric(typeof value === 'object' ? value?.[field] : value);
+}
+
+async function safeCount(sdk, label, table, query = '', options = {}) {
+  try {
+    return { label, table, query, count: await sdk.aggregateCount(table, query, options) };
+  } catch (err) {
+    const message = err.message || 'request failed';
+    const deadline = options.timeout && message === 'Request timed out'
+      ? ` after ${Math.round(options.timeout / 1000)} seconds`
+      : '';
+    return { label, table, query, count: null, unavailable: `${message}${deadline}` };
+  }
+}
+
+async function mapWithConcurrency(items, limit, worker) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  const run = async () => {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await worker(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
+  return results;
+}
+
+async function safeAggregate(sdk, label, table, options) {
+  try {
+    const result = await sdk.aggregate(table, options);
+    return {
+      label,
+      table,
+      groups: Array.isArray(result?.groups) ? result.groups : (Array.isArray(result?.stats) ? result.stats : []),
+      stats: result?.stats && !Array.isArray(result.stats) ? result.stats : null,
+    };
+  } catch (err) {
+    return { label, table, groups: [], stats: null, unavailable: err.message || 'request failed' };
+  }
+}
+
+function safeStatsResult(result) {
+  const stats = result.stats || result.groups[0]?.stats || {};
+  return {
+    avg_ms: metricValue(stats, 'avg', 'response_time'),
+    max_ms: metricValue(stats, 'max', 'response_time'),
+    ...(result.unavailable ? { unavailable: result.unavailable } : {}),
+  };
+}
+
+function buildDateList(since, until) {
+  if (!since || !until || !nextDate(until)) return [];
+  const dates = [];
+  let current = since;
+  for (let i = 0; i < 366 && current && current <= until; i += 1) {
+    dates.push(current);
+    current = nextDate(current);
+  }
+  return dates;
+}
+
+function formatCount(value) {
+  if (value == null) return 'unavailable';
+  return Number(value).toLocaleString('en-US');
+}
+
+export function formatDuration(ms) {
+  if (ms == null) return 'unavailable';
+  if (ms >= 3600000) return `${(ms / 3600000).toFixed(1)} hours`;
+  if (ms >= 60000) return `${(ms / 60000).toFixed(1)} minutes`;
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)} seconds`;
+  return `${Math.round(ms * 100) / 100} ms`;
+}
+
+function formatMetricRows(rows) {
+  return rows.map(row => `  ${row.label}: ${formatCount(row.count)}${row.unavailable ? ` (${row.unavailable})` : ''}`);
+}
+
+function formatFlowRows(flow) {
+  const lines = [`  Flow executions: ${formatCount(flow.total_count)}`];
+  for (const row of flow.states) lines.push(`  ${row.state}: ${formatCount(row.count)}`);
+  if (flow.unavailable) lines.push(`  Unavailable: ${flow.unavailable}`);
+  return lines;
+}
+
+function formatTransactions(transactions) {
+  const lines = [`  Total transactions: ${formatCount(transactions.total_count)}`];
+  if (transactions.types.length) {
+    for (const row of transactions.types) {
+      lines.push('');
+      lines.push(`  ${row.type}`);
+      lines.push(`    Count: ${formatCount(row.count)}`);
+      lines.push(`    Average response: ${formatDuration(row.avg_response_time_ms)}`);
+      lines.push(`    Maximum response: ${formatDuration(row.max_response_time_ms)}`);
+    }
+  } else {
+    lines.push('  (no transaction types)');
+  }
+  if (transactions.unavailable) lines.push(`  Unavailable: ${transactions.unavailable}`);
+  return lines;
+}
+
+function formatDailyFlows(rows) {
+  if (!rows.length) return [];
+  return [
+    '',
+    '  Daily flow executions',
+    '  Date          Count',
+    ...rows.map(row => `  ${row.date}  ${formatCount(row.count)}`),
+  ];
+}
+
+function formatDailyImports(rows) {
+  if (!rows.length) return [];
+  return [
+    '',
+    '  Daily import activity',
+    '  Date          Import sets  Import rows',
+    ...rows.map(row => `  ${row.date}  ${formatCount(row.import_sets).padStart(11)}  ${formatCount(row.import_rows).padStart(12)}`),
+  ];
+}
+
+export function formatInstanceGlance(data) {
+  const lines = [
+    'INSTANCE AT A GLANCE',
+    `Instance: ${data.context.instance_url}`,
+    `Activity window: ${data.window.since || 'last 24 hours'} through ${data.window.until || 'now'}`,
+    'Configuration and data totals: current',
+    '',
+    '1. INBOUND AUTOMATION',
+    ...formatMetricRows(data.inbound_automation.metrics),
+    '  Scripted REST separation: not separated from other REST transactions',
+    '',
+    '2. ASYNCHRONOUS AUTOMATION',
+    ...formatFlowRows(data.asynchronous_automation),
+    `  Async business rules configured: ${formatCount(data.asynchronous_automation.async_business_rules_configured)}`,
+    ...formatDailyFlows(data.asynchronous_automation.daily_flow_executions),
+    '',
+    '3. SCHEDULED WORK',
+    `  Scheduled scripts configured: ${formatCount(data.scheduled_work.scheduled_scripts_configured)}`,
+    `  Scheduler transactions: ${formatCount(data.scheduled_work.scheduler_transactions)}`,
+    `  Average scheduler transaction time: ${formatDuration(data.scheduled_work.scheduler_transaction_time.avg_ms)}`,
+    `  Maximum scheduler transaction time: ${formatDuration(data.scheduled_work.scheduler_transaction_time.max_ms)}`,
+    `  Import sets: ${formatCount(data.scheduled_work.import_sets)}`,
+    `  Import rows: ${formatCount(data.scheduled_work.import_rows)}`,
+    ...formatDailyImports(data.scheduled_work.daily_import_activity),
+    '',
+    '4. QUERY AND SECURITY CONTROLS',
+    ...formatMetricRows(data.query_and_security_controls),
+    '',
+    '5. DATA VOLUME',
+    ...formatMetricRows(data.data_volume),
+    '',
+    '6. TRANSACTION DETAIL',
+    ...formatTransactions(data.transactions),
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+function summarizeTransactions(groups) {
+  return groups.map(group => {
+    const stats = group?.stats || {};
+    return {
+      type: groupField(group, 'type'),
+      count: groupCount(group),
+      avg_response_time_ms: metricValue(stats, 'avg', 'response_time'),
+      max_response_time_ms: metricValue(stats, 'max', 'response_time'),
+    };
+  });
+}
+
+function stateRows(groups) {
+  return groups.map(group => ({ state: groupField(group, 'state'), count: groupCount(group) }));
+}
+
+function datesFor(argv) {
+  return argv.daily === false ? [] : buildDateList(argv.since, argv.until);
+}
+
+export function instanceCmd(wrap) {
+  return {
+    command: 'instance [subcommand]',
+    aliases: ['overview'],
+    describe: 'Inspect the current ServiceNow instance',
+    builder: y => y.command({
+      command: 'glance',
+      aliases: ['at-a-glance', 'summary'],
+      describe: 'Show a readable instance health and activity report',
+      builder: yargs => yargs
+        .option('query', { type: 'string', describe: 'Encoded query for activity metrics' })
+        .option('since', { type: 'string', describe: 'Activity start date (YYYY-MM-DD)' })
+        .option('until', { type: 'string', describe: 'Activity end date (YYYY-MM-DD)' })
+        .option('daily', { type: 'boolean', default: true, describe: 'Include daily flow and import rows when dates are supplied' }),
+      handler: wrap(async (argv, app) => {
+        app.requireInstance();
+        const query = buildActivityQuery(argv);
+        const dailyDates = datesFor(argv);
+        const schedulerQuery = addQuery(query, 'urlLIKEscheduler');
+        const [
+          dataVolume,
+          configured,
+          flowTotal,
+          flowStates,
+          transactions,
+          restTransactions,
+          tableApi,
+          graphql,
+          inboundEmail,
+          soap,
+          schedulerTransactions,
+          schedulerStats,
+          asyncBusinessRules,
+          beforeQueryRules,
+          scriptedAcls,
+          readAcls,
+          writeAcls,
+          deleteAcls,
+          createAcls,
+          executeAcls,
+          importSets,
+          importRows,
+          dailyFlows,
+          dailyImportSets,
+          dailyImportRows,
+        ] = await Promise.all([
+          mapWithConcurrency(DATA_VOLUME, DATA_VOLUME_CONCURRENCY, ([label, table]) => safeCount(app.sdk, label, table, '', { timeout: DATA_VOLUME_TIMEOUT })),
+          Promise.all(CONFIGURED_AUTOMATION.map(([label, table, tableQuery]) => safeCount(app.sdk, label, table, tableQuery))),
+          safeCount(app.sdk, 'flow_executions', 'sys_flow_context', query),
+          safeAggregate(app.sdk, 'flow_states', 'sys_flow_context', { query, groupBy: ['state'], count: true }),
+          safeAggregate(app.sdk, 'transactions', 'syslog_transaction', { query, groupBy: ['type'], count: true, averageFields: ['response_time'], maximumFields: ['response_time'] }),
+          safeCount(app.sdk, 'REST transactions', 'syslog_transaction', addQuery(query, 'type=rest')),
+          safeCount(app.sdk, 'Table API URL matches', 'syslog_transaction', addQuery(query, 'urlLIKE/api/now/table/')),
+          safeCount(app.sdk, 'GraphQL URL matches', 'syslog_transaction', addQuery(query, 'urlLIKEgraphql')),
+          safeCount(app.sdk, 'Inbound email records', 'sys_email', addQuery(query, 'type=received')),
+          safeCount(app.sdk, 'SOAP URL matches', 'syslog_transaction', addQuery(query, 'urlLIKEsoap')),
+          safeCount(app.sdk, 'Scheduler transactions', 'syslog_transaction', schedulerQuery),
+          safeAggregate(app.sdk, 'scheduler_transaction_time', 'syslog_transaction', { query: schedulerQuery, averageFields: ['response_time'], maximumFields: ['response_time'] }),
+          safeCount(app.sdk, 'async_business_rules_configured', 'sys_script', 'when=async'),
+          safeCount(app.sdk, 'Scripted before-query business rules', 'sys_script', 'when=before^action_query=true'),
+          safeCount(app.sdk, 'Scripted access controls', 'sys_security_acl', 'scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'Scripted read ACLs', 'sys_security_acl', 'operation=read^scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'Scripted write ACLs', 'sys_security_acl', 'operation=write^scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'Scripted delete ACLs', 'sys_security_acl', 'operation=delete^scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'Scripted create ACLs', 'sys_security_acl', 'operation=create^scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'Scripted execute ACLs', 'sys_security_acl', 'operation=execute^scriptISNOTEMPTY'),
+          safeCount(app.sdk, 'import_sets', 'sys_import_set', query),
+          safeCount(app.sdk, 'import_rows', 'sys_import_set_row', query),
+          Promise.all(dailyDates.map(date => safeCount(app.sdk, 'flow_executions', 'sys_flow_context', buildActivityQuery({ since: date, until: date })))),
+          Promise.all(dailyDates.map(date => safeCount(app.sdk, 'import_sets', 'sys_import_set', buildActivityQuery({ since: date, until: date })))),
+          Promise.all(dailyDates.map(date => safeCount(app.sdk, 'import_rows', 'sys_import_set_row', buildActivityQuery({ since: date, until: date })))),
+        ]);
+
+        const inboundMetrics = [restTransactions, tableApi, graphql, inboundEmail, soap];
+        const data = {
+          window: { query, since: argv.since || null, until: argv.until || null },
+          inbound_automation: {
+            metrics: inboundMetrics,
+            configured: configured.slice(0, 4),
+          },
+          asynchronous_automation: {
+            total_count: flowTotal.count,
+            states: stateRows(flowStates.groups),
+            async_business_rules_configured: asyncBusinessRules.count,
+            daily_flow_executions: dailyDates.map((date, index) => ({ date, count: dailyFlows[index].count })),
+          },
+          scheduled_work: {
+            scheduled_scripts_configured: configured.find(row => row.label === 'Scheduled scripts')?.count ?? null,
+            scheduler_transactions: schedulerTransactions.count,
+            scheduler_transaction_time: safeStatsResult(schedulerStats),
+            import_sets: importSets.count,
+            import_rows: importRows.count,
+            daily_import_activity: dailyDates.map((date, index) => ({ date, import_sets: dailyImportSets[index].count, import_rows: dailyImportRows[index].count })),
+          },
+          query_and_security_controls: [beforeQueryRules, scriptedAcls, readAcls, writeAcls, deleteAcls, createAcls, executeAcls],
+          data_volume: dataVolume,
+          transactions: {
+            total_count: transactions.groups.reduce((total, group) => total + groupCount(group), 0),
+            types: summarizeTransactions(transactions.groups),
+            ...(transactions.unavailable ? { unavailable: transactions.unavailable } : {}),
+          },
+          context: { instance_url: app.getEffectiveInstance(), timezone: 'UTC' },
+        };
+        app.ok({ ...data, _formatted: formatInstanceGlance(data) }, {
+          summary: `Instance glance for ${app.getEffectiveInstance()}`,
+        });
+      }),
+    }),
+    handler: wrap(async (_argv, app) => {
+      app.ok({
+        command: 'instance',
+        subcommands: ['glance'],
+        _formatted: 'Run "jsn instance glance" for an instance report.\n',
+      }, { summary: 'Instance inspection commands' });
+    }),
+  };
+}

package/src/commands/platform.js

@@ -0,0 +1,127 @@
+function numberOrString(value) {
+  const n = Number(value);
+  return value !== '' && Number.isFinite(n) ? n : value;
+}
+
+function tagText(xml, tag) {
+  const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = xml.match(new RegExp(`<${escaped}>([^<]*)</${escaped}>`));
+  return match ? match[1].trim() : undefined;
+}
+
+function tagAttributes(xml, tag) {
+  const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = xml.match(new RegExp(`<${escaped}\\b([^>]*)\\/>`));
+  if (!match) return undefined;
+  const attrs = {};
+  for (const [, key, value] of match[1].matchAll(/([\w.-]+)="([^"]*)"/g)) attrs[key] = numberOrString(value);
+  return attrs;
+}
+
+function statsForWindow(xml, parent, window) {
+  const parentMatch = xml.match(new RegExp(`<${parent}>([\\s\\S]*?)</${parent}>`));
+  if (!parentMatch) return undefined;
+  return tagAttributes(parentMatch[1], window);
+}
+
+export function parseNodeStatsXml(xml) {
+  const source = String(xml || '');
+  const result = {};
+  const root = source.match(/<xmlstats\b([^>]*)>/);
+  const rootAttrs = {};
+  for (const [, key, value] of (root?.[1] || '').matchAll(/([\w.-]+)="([^"]*)"/g)) rootAttrs[key] = value;
+  if (rootAttrs.created) result.created = rootAttrs.created;
+
+  const queueLength = tagText(source, 'queue.length');
+  const queueAge = tagText(source, 'queue.age');
+  if (queueLength !== undefined || queueAge !== undefined) {
+    result.queue = {};
+    if (queueLength !== undefined) result.queue.length = numberOrString(queueLength);
+    if (queueAge !== undefined) result.queue.age = numberOrString(queueAge);
+  }
+
+  const activeSessions = tagText(source, 'servlet.active.sessions');
+  if (activeSessions !== undefined) result.active_sessions = numberOrString(activeSessions);
+  const memoryPressure = tagText(source, 'memory_pressure');
+  if (memoryPressure !== undefined) result.memory_pressure = memoryPressure;
+
+  result.semaphores = [];
+  for (const match of source.matchAll(/<semaphores\b([^>]*)\/>/g)) {
+    const attrs = {};
+    for (const [, key, value] of match[1].matchAll(/([\w.-]+)="([^"]*)"/g)) {
+      if (['name', 'available', 'borrowed', 'queue_depth', 'queue_depth_limit', 'maximum_concurrency'].includes(key)) attrs[key] = numberOrString(value);
+    }
+    if (attrs.name) result.semaphores.push(attrs);
+  }
+
+  const daily = statsForWindow(source, 'all_transactions', 'daily');
+  if (daily) {
+    result.transactions = { daily: {} };
+    for (const key of ['count', 'mean', 'median', 'ninetypercent', 'max']) {
+      if (daily[key] !== undefined) result.transactions.daily[key] = daily[key];
+    }
+  }
+  return result;
+}
+
+function displayValue(value) {
+  if (value && typeof value === 'object') return value.display_value ?? value.value ?? '';
+  return value ?? '';
+}
+
+function valueOf(value) {
+  return value && typeof value === 'object' ? value.value : value;
+}
+
+export function selectClusterRows(rows, nodeId, allNodes) {
+  if (!nodeId || allNodes) return rows;
+  return rows.filter(row => valueOf(row.sys_id) === nodeId);
+}
+
+function formatHealth(nodes) {
+  const lines = ['NODE STATUS  TYPE             QUEUE  AGE  SESSIONS  DEFAULT SEM  DB'];
+  lines.push('-----------  ---------------  -----  ---  --------  -----------  --');
+  for (const node of nodes) {
+    const sem = node.stats.semaphores.find(s => s.name === 'Default');
+    const db = node.stats.transactions?.daily;
+    lines.push(`${String(displayValue(node.status) || '?').padEnd(11)}  ${String(displayValue(node.node_type) || '?').padEnd(15)}  ${String(node.stats.queue?.length ?? '-').padStart(5)}  ${String(node.stats.queue?.age ?? '-').padStart(3)}  ${String(node.stats.active_sessions ?? '-').padStart(8)}  ${sem ? `${sem.borrowed}/${sem.maximum_concurrency}`.padStart(11) : '-'.padStart(11)}  ${db ? `${db.mean} ms` : '-'}`);
+  }
+  if (nodes.length === 0) lines.push('(no nodes)');
+  return `${lines.join('\n')}\n`;
+}
+
+export function platformCmd(wrap) {
+  return {
+    command: 'platform',
+    describe: 'Inspect read-only platform health and node statistics',
+    builder: (y) => y.command({
+      command: 'health',
+      describe: 'Show cluster, queue, semaphore, and node health',
+      builder: (y) => y
+        .option('node', {
+          type: 'string',
+          describe: 'Inspect one sys_cluster_state record by sys_id',
+        })
+        .option('all-nodes', {
+          type: 'boolean',
+          default: false,
+          describe: 'Explicitly inspect every cluster node (the default)',
+        }),
+      handler: wrap(async (argv, app) => {
+        app.requireInstance();
+        const cluster = await app.sdk.list('sys_cluster_state', {
+          sysparm_fields: 'sys_id,status,node_type,node_stats',
+          sysparm_limit: '100',
+        });
+        const nodes = [];
+        for (const row of selectClusterRows(cluster, argv.node, argv.allNodes)) {
+          const id = typeof row.node_stats === 'object' ? row.node_stats.value : row.node_stats;
+          if (!id) continue;
+          const stats = await app.sdk.get('sys_cluster_node_stats', id);
+          nodes.push({ sys_id: valueOf(row.sys_id), status: row.status, node_type: row.node_type, stats: parseNodeStatsXml(stats?.stats || '') });
+        }
+        app.ok({ table: 'sys_cluster_state', node_count: nodes.length, nodes, _formatted: formatHealth(nodes), security: { raw_xml: 'excluded', sensitive_fields: 'excluded' }, context: { instance_url: app.getEffectiveInstance() } }, { summary: `Platform health: ${nodes.length} node(s)` });
+      }),
+    }),
+  };
+}

package/src/commands/records.js

@@ -351,6 +351,50 @@ export function recordsCmd(wrap) {
             })
             .demandCommand(1, 'Specify an attachment action: list, get, or add'),
         })
+        .command({
+          command: 'aggregate',
+          describe: 'Run ServiceNow Stats API aggregation with optional grouping',
+          builder: (y) => y
+            .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
+            .option('query', { type: 'string', describe: 'Encoded query to constrain the aggregation' })
+            .option('group-by', { type: 'string', describe: 'Comma-separated fields to group by' })
+            .option('count', { type: 'boolean', default: true, describe: 'Include record counts' })
+            .option('avg-fields', { type: 'string', describe: 'Comma-separated fields to average' })
+            .option('sum-fields', { type: 'string', describe: 'Comma-separated fields to sum' })
+            .option('min-fields', { type: 'string', describe: 'Comma-separated fields for minimum values' })
+            .option('max-fields', { type: 'string', describe: 'Comma-separated fields for maximum values' })
+            .option('order-by', { type: 'string', describe: 'Comma-separated fields to order by' }),
+          handler: wrap(async (argv, app) => {
+            app.requireInstance();
+            const split = (value) => value ? value.split(',').map(v => v.trim()).filter(Boolean) : [];
+            const options = {
+              query: argv.query || '',
+              groupBy: split(argv['group-by']),
+              count: argv.count !== false,
+              averageFields: split(argv['avg-fields']),
+              sumFields: split(argv['sum-fields']),
+              minimumFields: split(argv['min-fields']),
+              maximumFields: split(argv['max-fields']),
+              orderBy: split(argv['order-by']),
+            };
+            const result = await app.sdk.aggregate(argv.table, options);
+            app.ok({
+              table: argv.table,
+              query: options.query,
+              group_by: options.groupBy,
+              aggregate: {
+                count: options.count,
+                average_fields: options.averageFields,
+                sum_fields: options.sumFields,
+                minimum_fields: options.minimumFields,
+                maximum_fields: options.maximumFields,
+                order_by: options.orderBy,
+              },
+              ...result,
+              context: { instance_url: app.getEffectiveInstance() },
+            }, { summary: `Aggregated ${argv.table}${options.groupBy.length ? ` by ${options.groupBy.join(', ')}` : ''}` });
+          }),
+        })
         .command({
           command: 'bulk',
           describe: 'Bulk-update records matching a query. Dry-run by default — pass --execute to commit',
@@ -480,7 +524,8 @@ export function recordsCmd(wrap) {
       console.log('  create                Create a record');
       console.log('  update                Update a record');
       console.log('  delete                Delete a record');
-      console.log('  inspect               Inspect table schema and statistics');
+      console.log('  aggregate              Run Stats API aggregation with optional grouping');
+      console.log('  inspect                Inspect table schema and statistics');
       console.log('');
       console.log('Run "jsn records <command> --help" for details.');
     },

package/src/commands/transactions.js

@@ -0,0 +1,100 @@
+export function normalizeTransactionQuery(query) {
+  const raw = String(query || '').trim();
+  if (!raw) return 'sys_created_on>=javascript:gs.daysAgoStart(1)';
+  return raw.replace(/(^|\^)sys_created_on=(\d{4}-\d{2}-\d{2})(?=\^|$)/g, (_, prefix, date) => {
+    const nextDay = new Date(`${date}T00:00:00Z`);
+    nextDay.setUTCDate(nextDay.getUTCDate() + 1);
+    const next = nextDay.toISOString().slice(0, 10);
+    return `${prefix}sys_created_on>=${date}^sys_created_on<${next}`;
+  });
+}
+
+function displayMetric(value) {
+  if (value == null) return '-';
+  const rounded = Math.round(value * 100) / 100;
+  return `${rounded} ms`;
+}
+
+function formatTransactionTable(types) {
+  const lines = [
+    'CLASS       TYPE           COUNT  AVG       MIN       MAX',
+    '----------  -------------  -----  --------  --------  --------',
+  ];
+  for (const row of types) {
+    const value = (metric) => displayMetric(row[metric]);
+    lines.push(`${row.class.padEnd(10)}  ${row.type.padEnd(13)}  ${String(row.count).padStart(5)}  ${value('avg_response_time_ms').padEnd(8)}  ${value('min_response_time_ms').padEnd(8)}  ${value('max_response_time_ms')}`);
+  }
+  if (types.length === 0) lines.push('(no transactions)');
+  return `${lines.join('\n')}\n`;
+}
+
+export function classifyTransactionType(type, url = '') {
+  const normalized = String(type || '').toLowerCase();
+  const path = String(url || '').toLowerCase();
+  if (normalized === 'scheduler' || path.startsWith('job:')) return 'job';
+  if (['rest', 'batch_rest'].includes(normalized)) return 'api';
+  if (['form', 'list'].includes(normalized)) return 'ui';
+  if (['export', 'instance_scan'].includes(normalized)) return 'background';
+  return 'unknown';
+}
+
+function numericValue(value) {
+  const n = Number(String(value ?? '').replaceAll(',', ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+function groupValue(group, field) {
+  return group?.groupby_fields?.find(item => item?.field === field)?.value || '';
+}
+
+function metricValue(stats, metric, field) {
+  const value = stats?.[metric];
+  return typeof value === 'object' ? numericValue(value[field]) : numericValue(value);
+}
+
+function summarizeGroup(group) {
+  const type = groupValue(group, 'type') || 'unknown';
+  const stats = group?.stats || {};
+  return {
+    type,
+    class: classifyTransactionType(type),
+    count: numericValue(stats.count) ?? 0,
+    avg_response_time_ms: metricValue(stats, 'avg', 'response_time'),
+    min_response_time_ms: metricValue(stats, 'min', 'response_time'),
+    max_response_time_ms: metricValue(stats, 'max', 'response_time'),
+  };
+}
+
+export function transactionsCmd(wrap) {
+  return {
+    command: 'transactions',
+    describe: 'Summarize syslog_transaction response times by transaction type',
+    builder: (y) => y
+      .option('query', { type: 'string', describe: 'Encoded query; date-only sys_created_on equality expands to the full day' })
+      .option('order-by', { type: 'string', describe: 'Stats API order-by fields' }),
+    handler: wrap(async (argv, app) => {
+      app.requireInstance();
+      const query = normalizeTransactionQuery(argv.query);
+      const result = await app.sdk.aggregate('syslog_transaction', {
+        query,
+        groupBy: ['type'],
+        count: true,
+        averageFields: ['response_time'],
+        minimumFields: ['response_time'],
+        maximumFields: ['response_time'],
+        orderBy: argv['order-by'] || '',
+      });
+      const groups = Array.isArray(result.groups) ? result.groups : [];
+      const types = groups.map(summarizeGroup);
+      app.ok({
+        table: 'syslog_transaction',
+        query,
+        group_by: ['type'],
+        response_time_unit: 'ms',
+        types,
+        _formatted: formatTransactionTable(types),
+        context: { instance_url: app.getEffectiveInstance() },
+      }, { summary: `Transactions by type: ${types.length} type(s)` });
+    }),
+  };
+}