nansen-cli 1.43.1 → 1.44.0

package/src/cli.js

@@ -12,8 +12,12 @@ import { buildLimitOrderCommands } from './limit-order.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
 import { buildAgentCommands } from './commands/agent.js';
 import { buildMcpCommands } from './commands/mcp.js';
-import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './commands/research.js';
+import { buildCompletionCommands } from './commands/completion.js';
+import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS, RESEARCH_SUBCOMMANDS } from './commands/research.js';
+import { buildPagination, parseSort } from './query-options.js';
+export { buildPagination, parseSort };
 import { resolveAddress, isEnsName } from './ens.js';
+import { compareSemver } from './semver.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
 import { getAuthStatus, runDoctorChecks, runConnectivityChecks, formatDoctorReport } from './doctor.js';
@@ -54,14 +58,6 @@ export function resolveBooleanOption(options, flags, key) {
   return undefined;
 }
 
-export function buildPagination(options) {
-  if (!options.limit && !options.page) return undefined;
-  return {
-    page: Math.max(1, parseInt(options.page, 10) || 1),
-    per_page: options.limit,
-  };
-}
-
 // ============= Field Filtering =============
 
 /**
@@ -168,18 +164,15 @@ export function compactSchema(schema) {
   };
 }
 
-/**
- * Compare two semver strings. Returns 1 if a > b, -1 if a < b, 0 if equal.
- */
-function compareSemver(a, b) {
-  const parse = v => v.replace(/^v/, '').split('.').map(Number);
-  const [aM, am, ap] = parse(a);
-  const [bM, bm, bp] = parse(b);
-  if (aM !== bM) return aM > bM ? 1 : -1;
-  if (am !== bm) return am > bm ? 1 : -1;
-  if (ap !== bp) return ap > bp ? 1 : -1;
-  return 0;
-}
+// Long options that never consume the next argument. The shell-completion
+// generator needs the same list to tell an option's value apart from a
+// subcommand, so it lives here rather than inline in parseArgs.
+export const VALUELESS_FLAGS = new Set([
+  'pretty', 'help', 'version', 'table', 'no-retry', 'cache', 'no-cache', 'stream',
+  'enrich', 'full', 'human', 'enabled', 'disabled', 'expert', 'json', 'offline',
+  'no-simulate', 'no-verify-outcome', 'no-revoke-excessive-allowance', 'dry-run',
+  'send-api-key',
+]);
 
 export function parseArgs(args) {
   const result = { _: [], flags: {}, options: {} };
@@ -191,7 +184,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline' || key === 'no-simulate' || key === 'no-verify-outcome' || key === 'no-revoke-excessive-allowance' || key === 'dry-run') {
+      if (VALUELESS_FLAGS.has(key)) {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -460,22 +453,6 @@ export function parseDateOption(dateOption, days = 30) {
   return { from, to };
 }
 
-// Parse simple sort syntax: "field:direction" or "field" (defaults to DESC)
-export function parseSort(sortOption, orderByOption) {
-  // If --order-by is provided, use it (full JSON control)
-  if (orderByOption) return orderByOption;
-  
-  // If no --sort, return undefined
-  if (!sortOption) return undefined;
-  
-  // Parse --sort field:direction or --sort field
-  const parts = sortOption.split(':');
-  const field = parts[0];
-  const direction = (parts[1] || 'desc').toUpperCase();
-  
-  return [{ field, direction }];
-}
-
 // Enrich transfers with Nansen labels for from/to addresses
 async function enrichTransfers(result, apiInstance, chain) {
   const transfers = result?.data?.results || result?.transfers || result?.data || [];
@@ -746,6 +723,7 @@ COMMANDS:
   logout      Remove saved API key
   doctor      Diagnostics: auth, wallets, caches, connectivity (--offline --json)
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
+  completion  Shell completions: bash, zsh, fish
   cache       clear
   changelog   --since <version> to filter
 
@@ -785,7 +763,7 @@ Labels: Fund, Smart Trader, 30D/90D/180D Smart Trader, Smart HL Perps Trader
 Docs: https://docs.nansen.ai
 Skills: npx skills add nansen-ai/nansen-cli (agent-optimised docs per command group)
 
-Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send the order side and Hyperliquid order id. Disable: DO_NOT_TRACK=1
+Telemetry: anonymous usage stats (commands, timing, errors). Perp order/close additionally send each leg's side, outcome, order id, shared submission id, and a SHA-256 wallet identifier. Raw wallet, price, size, and exchange error text are not sent. Disable: DO_NOT_TRACK=1
 `;
 
 // Usage text for the `trade` command group. Shared by the trade handler and the
@@ -1132,6 +1110,15 @@ export function buildCommands(deps = {}) {
       }
       const since = _options.since;
       if (since) {
+        // compareSemver treats a missing trailing component as 0, so accept
+        // "1", "1.43", and "1.43.0" alike here — but anything that isn't
+        // digits-and-dots (e.g. "abc") needs a clear error instead of
+        // silently comparing as if it were version 0.0.0, which would show
+        // every entry rather than flag the typo.
+        if (!/^v?\d+(\.\d+){0,2}$/.test(String(since))) {
+          log(`Invalid --since value "${since}": expected a version like 1.43 or 1.43.0.`);
+          return;
+        }
         // Show only entries from the given version onwards
         const lines = content.split('\n');
         const filtered = [];
@@ -1530,7 +1517,7 @@ export function buildCommands(deps = {}) {
       };
 
       if (!handlers[subcommand]) {
-        return { error: `Unknown subcommand: ${subcommand}`, available: Object.keys(handlers) };
+        throw new NansenError(`Unknown perp analytics subcommand: ${subcommand}. Available: screener, leaderboard`, ErrorCode.UNKNOWN);
       }
 
       return handlers[subcommand]();
@@ -1587,7 +1574,7 @@ export function buildCommands(deps = {}) {
       const maxUniqueTraders24h = options['max-unique-traders-24h'] != null ? Number(options['max-unique-traders-24h']) : undefined;
       const minVolume24hr = options['min-volume-24hr'] != null ? Number(options['min-volume-24hr']) : undefined;
       const maxVolume24hr = options['max-volume-24hr'] != null ? Number(options['max-volume-24hr']) : undefined;
-      const negRisk = options['neg-risk'] != null ? options['neg-risk'] === 'true' : undefined;
+      const negRisk = resolveBooleanOption(options, flags, 'neg-risk');
       const minOpenInterest = options['min-open-interest'] != null ? Number(options['min-open-interest']) : undefined;
       const maxOpenInterest = options['max-open-interest'] != null ? Number(options['max-open-interest']) : undefined;
       const endDateBefore = options['end-date-before'];
@@ -1631,32 +1618,33 @@ export function buildCommands(deps = {}) {
   // it, so it has to be taken exactly once, here.
   const perpAnalytics = cmds['perp'];
 
-  const researchHistorical = buildResearchCommands(deps).research;
+  const researchSub = buildResearchCommands(deps).research;
 
   cmds['research'] = async (args, apiInstance, flags, options) => {
     const rawCategory = args[0];
     if (!rawCategory || rawCategory === 'help') {
       return {
         categories: [...RESEARCH_CATEGORIES],
+        subcommands: [...RESEARCH_SUBCOMMANDS],
         historical: [...RESEARCH_HISTORICAL_SUBCOMMANDS],
         aliases: RESEARCH_CATEGORY_ALIASES,
         description: 'Research and analytics commands',
         example: 'nansen research smart-money netflow --chain solana'
       };
     }
-    if (RESEARCH_HISTORICAL_SUBCOMMANDS.has(rawCategory)) {
-      return researchHistorical(args, apiInstance, flags, options);
+    if (RESEARCH_SUBCOMMANDS.has(rawCategory)) {
+      return researchSub(args, apiInstance, flags, options);
     }
     const category = RESEARCH_CATEGORY_ALIASES[rawCategory] || rawCategory;
     if (!RESEARCH_CATEGORIES.has(category)) {
-      throw new NansenError(`Unknown research category: ${rawCategory}. Available: ${[...RESEARCH_CATEGORIES, ...RESEARCH_HISTORICAL_SUBCOMMANDS].join(', ')}`, ErrorCode.UNKNOWN);
+      throw new NansenError(`Unknown research category: ${rawCategory}. Available: ${[...RESEARCH_CATEGORIES, ...RESEARCH_SUBCOMMANDS].join(', ')}`, ErrorCode.UNKNOWN);
     }
     // `research perp` reaches only the analytics half (screener/leaderboard) —
-    // the trading subcommands live at the top level. Routing its help through
-    // cmds['perp'] printed the trading help, advertising order/close/leverage
-    // from a command that can't run them.
-    if (category === 'perp' && (!args[1] || args[1] === 'help')) {
-      return perpAnalytics(['help'], apiInstance, flags, options);
+    // the trading subcommands live at the top level. Use the captured handler
+    // for every subcommand because cmds['perp'] is replaced below by the
+    // combined top-level trading dispatcher.
+    if (category === 'perp') {
+      return perpAnalytics(args.slice(1), apiInstance, flags, options);
     }
     return cmds[category](args.slice(1), apiInstance, flags, options);
   };
@@ -1877,7 +1865,9 @@ export async function runCLI(rawArgs, deps = {}) {
   // contract covers the background update-check fetch and telemetry too,
   // not just the command's own requests.
   const isMcpUsage = command === 'mcp' && (subcommand !== 'verify' || flags.help || flags.h);
-  const isOfflineCommand = command === 'auth' || (command === 'doctor' && flags.offline) || isMcpUsage;
+  // `completion` renders from the checked-in schema — no network, and its
+  // stdout is piped straight into a shell, so keep the update check out of it.
+  const isOfflineCommand = command === 'auth' || (command === 'doctor' && flags.offline) || isMcpUsage || command === 'completion';
   const trackSucceeded = isOfflineCommand ? async () => {} : trackCommandSucceeded;
   const trackFailed = isOfflineCommand ? async () => {} : trackCommandFailed;
 
@@ -1899,7 +1889,7 @@ export async function runCLI(rawArgs, deps = {}) {
 
   // mcp prints its own output via `log`; runCLI callers inject their stdout
   // sink as `output`, so map it across (an explicit `log` dep still wins).
-  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...buildMcpCommands({ ...deps, log: deps.log ?? output }), ...commandOverrides };
+  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...buildMcpCommands({ ...deps, log: deps.log ?? output }), ...buildCompletionCommands({ ...deps, log: deps.log ?? output }), ...commandOverrides };
 
   if (flags.version || flags.v) {
     output(VERSION);