nansen-cli 1.17.0 → 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,8 @@ 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
@@ -693,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)
@@ -762,6 +778,76 @@ export function buildCommands(deps = {}) {
       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');
@@ -811,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');
     },
 
@@ -1448,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);
@@ -1485,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);
@@ -1495,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}`];
@@ -1504,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 };
@@ -1531,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 };
@@ -1565,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 };
     }
@@ -1573,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 };
     }
@@ -1583,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)
@@ -1590,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 };
     }
@@ -1597,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/schema.json

@@ -568,6 +568,129 @@
         }
       }
     },
+    "alerts": {
+      "description": "Smart alert management \u2014 create, update, toggle, delete alerts",
+      "subcommands": {
+        "list": {
+          "description": "List all alerts",
+          "returns": [
+            "id",
+            "name",
+            "type",
+            "timeWindow",
+            "isEnabled",
+            "channels",
+            "data",
+            "description"
+          ]
+        },
+        "create": {
+          "description": "Create a new alert",
+          "options": {
+            "name": {
+              "type": "string",
+              "required": true,
+              "description": "Alert name"
+            },
+            "type": {
+              "type": "string",
+              "required": true,
+              "description": "Alert type (e.g. sm-token-flows, common-token-transfer)"
+            },
+            "chains": {
+              "type": "string",
+              "description": "Comma-separated chains (e.g. ethereum,solana). Merged into data."
+            },
+            "telegram": {
+              "type": "string",
+              "description": "Telegram chat ID for notifications"
+            },
+            "slack": {
+              "type": "string",
+              "description": "Slack webhook URL for notifications"
+            },
+            "discord": {
+              "type": "string",
+              "description": "Discord webhook URL for notifications"
+            },
+            "data": {
+              "type": "string",
+              "description": "Alert config JSON. --chains is merged on top."
+            },
+            "description": {
+              "type": "string",
+              "description": "Optional description"
+            },
+            "disabled": {
+              "type": "boolean",
+              "description": "Create alert in disabled state"
+            }
+          }
+        },
+        "update": {
+          "description": "Update an existing alert. Usage: nansen alerts update <id> [options]",
+          "options": {
+            "name": {
+              "type": "string",
+              "description": "Alert name"
+            },
+            "type": {
+              "type": "string",
+              "description": "Alert type"
+            },
+            "chains": {
+              "type": "string",
+              "description": "Comma-separated chains. Merged into data."
+            },
+            "telegram": {
+              "type": "string",
+              "description": "Telegram chat ID"
+            },
+            "slack": {
+              "type": "string",
+              "description": "Slack webhook URL"
+            },
+            "discord": {
+              "type": "string",
+              "description": "Discord webhook URL"
+            },
+            "data": {
+              "type": "string",
+              "description": "Alert config JSON. --chains merged on top."
+            },
+            "description": {
+              "type": "string",
+              "description": "Description"
+            },
+            "enabled": {
+              "type": "boolean",
+              "description": "Enable alert"
+            },
+            "disabled": {
+              "type": "boolean",
+              "description": "Disable alert"
+            }
+          }
+        },
+        "toggle": {
+          "description": "Enable or disable an alert. Usage: nansen alerts toggle <id> --enabled|--disabled",
+          "options": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Enable alert"
+            },
+            "disabled": {
+              "type": "boolean",
+              "description": "Disable alert"
+            }
+          }
+        },
+        "delete": {
+          "description": "Delete an alert. Usage: nansen alerts delete <id>",
+          "options": {}
+        }
+      }
+    },
     "trade": {
       "description": "DEX trading commands",
       "subcommands": {
@@ -596,7 +719,7 @@
             },
             "wallet": {
               "type": "string",
-              "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required — run `nansen wallet create` if you haven't set one up yet."
+              "description": "Wallet name (or \"walletconnect\"/\"wc\" for WalletConnect, EVM only). A configured wallet is required \u2014 run `nansen wallet create` if you haven't set one up yet."
             }
           },
           "prerequisites": [
@@ -663,6 +786,46 @@
     },
     "account": {
       "description": "Show API key status, plan, and remaining credits. Does not consume credits."
+    },
+    "web": {
+      "description": "Web search and fetch commands",
+      "subcommands": {
+        "search": {
+          "description": "Search the web for one or more queries in parallel",
+          "options": {
+            "query": {
+              "description": "Search query (can be repeated for multiple queries)"
+            },
+            "num-results": {
+              "description": "Number of results per query (1-20, default 10)",
+              "default": 10
+            }
+          },
+          "examples": [
+            "nansen web search \"bitcoin price\"",
+            "nansen web search \"solana news\" --num-results 5",
+            "nansen web search --query \"btc\" --query \"eth\"",
+            "nansen web search \"btc\" --query \"eth\"  # positional + flag merged"
+          ]
+        },
+        "fetch": {
+          "description": "Fetch and analyze content from one or more URLs using AI",
+          "options": {
+            "url": {
+              "description": "URL to fetch (can be repeated for multiple URLs)"
+            },
+            "question": {
+              "description": "Question to answer about the URL content",
+              "required": true
+            }
+          },
+          "examples": [
+            "nansen web fetch https://nansen.ai --question \"What does Nansen do?\"",
+            "nansen web fetch --url https://a.com --url https://b.com --question \"Compare these\"",
+            "nansen web fetch https://a.com --url https://b.com --question \"Diff?\"  # positional + flag merged"
+          ]
+        }
+      }
     }
   },
   "globalOptions": {