nansen-cli 1.16.1 → 1.18.0

package/src/cli.js

@@ -6,9 +6,11 @@
 import { NansenAPI, NansenError, ErrorCode, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir, validateAddress, sleep } from './api.js';
 import { buildWalletCommands } from './wallet.js';
 import { buildTradingCommands } from './trading.js';
+import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
+import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
 import * as readline from 'readline';
 
@@ -163,19 +165,29 @@ 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') {
+      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') {
         result.flags[key] = true;
-      } else if (next && !next.startsWith('-')) {
+      } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
         // but keep numeric strings as strings to avoid precision loss
         // and scientific notation for large integers (e.g. 1e+21).
+        let parsedValue;
         try {
           const parsed = JSON.parse(next);
-          result.options[key] = typeof parsed === 'number' ? next : parsed;
+          parsedValue = typeof parsed === 'number' ? next : parsed;
         } catch {
-          result.options[key] = next;
+          parsedValue = next;
         }
         i++;
+        // Accumulate repeated options into arrays (supports repeatable flags like --token, --subject)
+        if (key in result.options) {
+          if (!Array.isArray(result.options[key])) {
+            result.options[key] = [result.options[key]];
+          }
+          result.options[key].push(parsedValue);
+        } else {
+          result.options[key] = parsedValue;
+        }
       } else {
         result.flags[key] = true;
       }
@@ -226,7 +238,7 @@ export function formatTable(data) {
   // Get columns from first record, prioritize common useful fields
   const priorityFields = ['token_symbol', 'token_name', 'symbol', 'name', 'address', 'label', 'chain', 'value_usd', 'amount', 'pnl_usd', 'price_usd', 'volume_usd', 'net_flow_usd', 'timestamp', 'block_timestamp'];
   const allKeys = [...new Set(records.flatMap(r => Object.keys(r)))];
-  
+
   // Sort: priority fields first, then alphabetically
   const columns = allKeys.sort((a, b) => {
     const aIdx = priorityFields.indexOf(a);
@@ -250,12 +262,12 @@ export function formatTable(data) {
   // Build table
   const separator = '─';
   const lines = [];
-  
+
   // Header
   const header = columns.map((col, i) => col.padEnd(widths[i])).join(' │ ');
   lines.push(header);
   lines.push(widths.map(w => separator.repeat(w)).join('─┼─'));
-  
+
   // Rows
   for (const record of records.slice(0, 50)) { // Limit to 50 rows
     const row = columns.map((col, i) => {
@@ -670,6 +682,9 @@ COMMANDS:
   research    smart-money, profiler, token, search, perp, portfolio, points
   trade       quote, execute
   wallet      create, list, show, export, default, delete, forget-password
+  alerts      list, create, update, toggle, delete
+  web         search, fetch
+  account     Show API key status, plan, and remaining credits
   login       Save API key (--api-key <key> or NANSEN_API_KEY env var)
   logout      Remove saved API key
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
@@ -692,6 +707,8 @@ 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 collected. Disable: DO_NOT_TRACK=1
 `;
 
 // Helper to prompt for input (exported for mocking)
@@ -757,6 +774,80 @@ export function buildCommands(deps = {}) {
   } = deps;
 
   const cmds = {
+    'account': async (_args, apiInstance, _flags, _options) => {
+      return apiInstance.getAccount();
+    },
+
+    'web': async (args, apiInstance, flags, options) => {
+      const subcommand = args[0] || 'help';
+      const subArgs = args.slice(1);
+
+      const handlers = {
+        'search': async () => {
+          // Accept queries as positional args or --query (repeated)
+          let queries = subArgs.length > 0 ? subArgs : [];
+          if (options.query) {
+            const fromOption = Array.isArray(options.query) ? options.query : [options.query];
+            queries = queries.concat(fromOption);
+          }
+          queries = queries.filter(q => q.trim());
+          if (queries.length === 0) {
+            throw new NansenError('At least one query is required. Usage: nansen web search "bitcoin price" --num-results 5', ErrorCode.MISSING_PARAM);
+          }
+          let numResults;
+          if (options['num-results'] !== undefined) {
+            const numResultsRaw = parseInt(options['num-results'], 10);
+            if (Number.isNaN(numResultsRaw)) {
+              // Non-numeric — fall back to API default
+              numResults = undefined;
+            } else if (numResultsRaw >= 1 && numResultsRaw <= 20) {
+              numResults = numResultsRaw;
+            } else {
+              throw new NansenError('--num-results must be between 1 and 20', ErrorCode.INVALID_PARAMS);
+            }
+          }
+          return apiInstance.webSearch({ queries, numResults });
+        },
+
+        'fetch': async () => {
+          // Accept URLs as positional args or --url (repeated)
+          let urls = subArgs.length > 0 ? subArgs : [];
+          if (options.url) {
+            const fromOption = Array.isArray(options.url) ? options.url : [options.url];
+            urls = urls.concat(fromOption);
+          }
+          if (urls.length === 0) {
+            throw new NansenError('At least one URL is required. Usage: nansen web fetch https://example.com --question "What is this about?"', ErrorCode.MISSING_PARAM);
+          }
+          for (const u of urls) {
+            try { new URL(u); } catch {
+              throw new NansenError(`Invalid URL: "${u}". URLs must include a scheme, e.g. https://example.com`, ErrorCode.INVALID_PARAMS);
+            }
+          }
+          if (!options.question || !options.question.trim()) {
+            throw new NansenError('--question is required and cannot be blank. Usage: nansen web fetch https://example.com --question "What is this about?"', ErrorCode.MISSING_PARAM);
+          }
+          return apiInstance.webFetch({ urls, question: options.question });
+        },
+
+        'help': async () => ({
+          subcommands: ['search', 'fetch'],
+          description: 'Web search and fetch commands',
+          examples: [
+            'nansen web search "bitcoin price"',
+            'nansen web search "solana news" --num-results 5',
+            'nansen web fetch https://nansen.ai --question "What does Nansen do?"',
+          ],
+        }),
+      };
+
+      if (!handlers[subcommand]) {
+        throw new NansenError(`Unknown web subcommand: ${subcommand}. Available: search, fetch`, ErrorCode.UNKNOWN);
+      }
+
+      return handlers[subcommand]();
+    },
+
     'login': async (args, apiInstance, flags, options) => {
       if (flags.help || flags.h) {
         log('nansen login - Save your Nansen API key\n');
@@ -806,13 +897,48 @@ export function buildCommands(deps = {}) {
         return;
       }
 
+      // Verify API key before saving
+      const NansenAPIClass = _NansenAPIClass;
+      const testApi = new NansenAPIClass(apiKey.trim(), undefined, {
+        retry: { maxRetries: 2 },
+        cache: { enabled: false }
+      });
+
+      let accountInfo;
+      try {
+        accountInfo = await testApi.getAccount();
+      } catch (error) {
+        if (error.code === ErrorCode.UNAUTHORIZED) {
+          log(JSON.stringify({
+            error: 'INVALID_API_KEY',
+            message: 'The API key is not valid.',
+            resolution: ['Check your key at https://app.nansen.ai/api']
+          }));
+        } else {
+          log(JSON.stringify({
+            error: 'VERIFICATION_FAILED',
+            message: `Could not verify API key: ${error.message}`,
+            resolution: ['Check your internet connection', 'Try again']
+          }));
+        }
+        exit(1);
+        return;
+      }
+
+      // Key is valid - now save
       saveConfigFn({
         apiKey: apiKey.trim(),
         baseUrl: 'https://api.nansen.ai'
       });
 
       log(`✓ Saved to ${getConfigFileFn()}\n`);
-      log('You can now use the Nansen CLI. Try:');
+      if (accountInfo?.plan) {
+        log(`Plan: ${accountInfo.plan}`);
+      }
+      if (accountInfo?.credits_remaining !== undefined) {
+        log(`Credits remaining: ${accountInfo.credits_remaining}`);
+      }
+      log('\nYou can now use the Nansen CLI. Try:');
       log('  nansen research token screener --chain solana --pretty');
     },
 
@@ -1443,7 +1569,7 @@ export async function runCLI(rawArgs, deps = {}) {
     if (updateNotification) errorOutput(updateNotification);
   };
 
-  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...commandOverrides };
+  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...commandOverrides };
 
   if (flags.version || flags.v) {
     output(VERSION);
@@ -1480,8 +1606,8 @@ export async function runCLI(rawArgs, deps = {}) {
         }
       }
       // First try subcommand help
-      // Skip for 'trade' — its handlers show their own rich usage when required args are missing
-      if (command && subcommand && command !== 'trade') {
+      // Skip for 'trade'/'alerts' — their handlers show their own rich usage
+      if (command && subcommand && command !== 'trade' && command !== 'alerts') {
         const subHelp = generateSubcommandHelp(command, subcommand);
         if (subHelp) {
           output(subHelp);
@@ -1490,8 +1616,8 @@ export async function runCLI(rawArgs, deps = {}) {
         }
       }
       // Then try command-level help (list subcommands)
-      // Skip for 'trade' — let the handler show its own usage
-      const cmdSchemaLookup = command !== 'trade' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
+      // Skip for 'trade'/'alerts' — let the handler show its own usage
+      const cmdSchemaLookup = command !== 'trade' && command !== 'alerts' && (SCHEMA.commands[command] || SCHEMA.commands.research.subcommands[command]);
       if (command && cmdSchemaLookup) {
         const cmdSchema = cmdSchemaLookup;
         const lines = [`${command} — ${cmdSchema.description}`];
@@ -1499,6 +1625,19 @@ export async function runCLI(rawArgs, deps = {}) {
           lines.push('Subcommands: ' + Object.keys(cmdSchema.subcommands).join(', '));
           lines.push(`Use: nansen ${command} <subcommand> --help`);
         }
+        if (cmdSchema.options) {
+          const params = Object.entries(cmdSchema.options).map(([name, opt]) => {
+            const parts = [`--${name}`];
+            if (opt.required) parts[0] += '*';
+            if (opt.default !== undefined) parts.push(`(default: ${opt.default})`);
+            if (opt.description) parts.push(`— ${opt.description}`);
+            return parts.join(' ');
+          });
+          lines.push(`\nOptions (* required):\n  ${params.join('\n  ')}`);
+        }
+        if (cmdSchema.examples?.length) {
+          lines.push(`\nExamples:\n  ${cmdSchema.examples.join('\n  ')}`);
+        }
         output(lines.join('\n'));
         notify();
         return { type: 'command-help', command };
@@ -1526,13 +1665,22 @@ export async function runCLI(rawArgs, deps = {}) {
     }
   }
 
+  // ── Telemetry setup ──
+  const startTime = Date.now();
+  const fullCommand = subcommand ? `${command} ${subcommand}` : command;
+  const flagNames = Object.keys(flags).filter(k => flags[k]).map(k => `--${k}`);
+  const optionNames = Object.keys(options).map(k => `--${k}`);
+  const usedFlags = [...flagNames, ...optionNames];
+  const chain = options.chain || null;
+
   if (!commands[command]) {
-    const errorData = { 
+    const errorData = {
       error: `Unknown command: ${command}`,
       available: Object.keys(commands)
     };
     const formatted = formatOutput(errorData, { pretty, table });
     output(formatted.text);
+    trackCommandFailed({ command: fullCommand, duration_ms: Date.now() - startTime, error_code: 'UNKNOWN_COMMAND', flags: usedFlags, chain });
     notify();
     exit(1);
     return { type: 'error', data: errorData };
@@ -1560,6 +1708,7 @@ export async function runCLI(rawArgs, deps = {}) {
 
     // Commands that handle their own output return undefined
     if (result === undefined) {
+      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       notify();
       return { type: 'no-output', command };
     }
@@ -1568,6 +1717,7 @@ export async function runCLI(rawArgs, deps = {}) {
     if (command === 'schema') {
       const formatted = formatOutput(result, { pretty, table: false });
       output(formatted.text);
+      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });
       notify();
       return { type: 'schema', data: result };
     }
@@ -1578,6 +1728,13 @@ export async function runCLI(rawArgs, deps = {}) {
       result = filterFields(result, fields);
     }
 
+    // Alerts list with --table uses custom table format
+    if (command === 'alerts' && subcommand === 'list' && table) {
+      output(formatAlertsTable(result));
+      notify();
+      return { type: 'success', data: result };
+    }
+
     // Output in requested format
     if (stream) {
       // Stream mode: output each record as a JSON line (NDJSON)
@@ -1585,6 +1742,7 @@ export async function runCLI(rawArgs, deps = {}) {
       if (streamOutput) {
         output(streamOutput);
       }
+      trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
       notify();
       return { type: 'stream', data: result };
     }
@@ -1592,12 +1750,21 @@ export async function runCLI(rawArgs, deps = {}) {
     const successData = { success: true, data: result };
     const formatted = formatOutput(successData, { pretty, table, csv });
     output(formatted.text);
+    trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, from_cache: !!result?.fromCache, flags: usedFlags, chain });
     notify();
     return { type: csv ? 'csv' : 'success', data: result };
   } catch (error) {
     const errorData = formatError(error);
     const formatted = formatOutput(errorData, { pretty, table, csv });
     output(formatted.text);
+    trackCommandFailed({
+      command: fullCommand,
+      duration_ms: Date.now() - startTime,
+      error_code: error.code || 'UNKNOWN',
+      status: error.status || null,
+      flags: usedFlags,
+      chain,
+    });
     notify();
     exit(1);
     return { type: 'error', data: errorData };

package/src/rpc-urls.js

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for chain RPC endpoints.
+ *
+ * Both trading.js and transfer.js read from here so that:
+ *   (a) adding a new chain only requires one edit, and
+ *   (b) env-var overrides work consistently across all commands.
+ *
+ * Override env vars:
+ *   NANSEN_EVM_RPC        Custom Ethereum RPC (also used as generic EVM fallback)
+ *   NANSEN_BASE_RPC       Custom Base RPC
+ *   NANSEN_SOLANA_RPC     Custom Solana RPC
+ *
+ * Backward-compat aliases (deprecated — prefer the forms above):
+ *   NANSEN_RPC_BASE       Old name for NANSEN_BASE_RPC; trading.js previously read this
+ *                         but transfer.js never did, so the two commands were inconsistent.
+ *                         Both forms are now accepted here so existing .env files keep
+ *                         working while new code uses the standardised NANSEN_BASE_RPC name.
+ */
+
+const DEFAULT_EVM_RPC    = 'https://eth.public-rpc.com';
+const DEFAULT_BASE_RPC   = 'https://mainnet.base.org';
+const DEFAULT_SOLANA_RPC = 'https://api.mainnet-beta.solana.com';
+
+export const CHAIN_RPCS = {
+  ethereum: process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,
+  evm:      process.env.NANSEN_EVM_RPC    || DEFAULT_EVM_RPC,   // generic EVM fallback
+  base:     process.env.NANSEN_BASE_RPC   || process.env.NANSEN_RPC_BASE || DEFAULT_BASE_RPC,
+  solana:   process.env.NANSEN_SOLANA_RPC || DEFAULT_SOLANA_RPC,
+};