nansen-cli 1.17.0 → 1.19.0

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": {

package/src/telemetry.js

@@ -0,0 +1,237 @@
+/**
+ * Lightweight CLI telemetry.
+ *
+ * Sends anonymous usage events so we can understand which commands are used,
+ * how long they take, and where errors occur.  Events are fire-and-forget —
+ * failures are silently ignored and never block the CLI.
+ *
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const { version: cliVersion } = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+);
+
+const TELEMETRY_URL =
+  'https://bi-data-sources.nansen.ai/events-service-68ifmnpsx2uq7cgab8dw/v2/event';
+
+const TIMEOUT_MS = 2000;
+
+// ─── opt-out ──────────────────────────────────────────────
+
+export const TELEMETRY_DISABLED =
+  process.env.DO_NOT_TRACK === '1' || process.env.NANSEN_NO_TELEMETRY === '1';
+
+// ─── environment ──────────────────────────────────────────
+
+/**
+ * Infer prod vs dev from NANSEN_BASE_URL env var.
+ * Only engineers pointing at a local/staging API will have this set.
+ */
+function getEventSource() {
+  const baseUrl = process.env.NANSEN_BASE_URL || '';
+  return baseUrl && !baseUrl.includes('api.nansen.ai') ? 'cli_dev' : 'cli_prod';
+}
+
+// ─── system info ──────────────────────────────────────────
+
+const SYSTEM_NAMES = { Darwin: 'macos', Linux: 'linux', Windows_NT: 'windows' };
+
+function getSystemName() {
+  return SYSTEM_NAMES[os.type()] || os.type().toLowerCase();
+}
+
+// ─── identity ──────────────────────────────────────────────
+
+const TELEMETRY_ID_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.nansen',
+  'telemetry-id'
+);
+
+/**
+ * Get or create a persistent random anonymous_id stored in ~/.nansen/telemetry-id.
+ */
+let _anonymousId;
+export function getAnonymousId() {
+  if (_anonymousId === undefined) {
+    try {
+      _anonymousId = fs.readFileSync(TELEMETRY_ID_FILE, 'utf8').trim();
+    } catch {
+      _anonymousId = crypto.randomUUID();
+      try {
+        fs.mkdirSync(path.dirname(TELEMETRY_ID_FILE), { recursive: true });
+        fs.writeFileSync(TELEMETRY_ID_FILE, _anonymousId, 'utf8');
+      } catch { /* best-effort persist */ }
+    }
+  }
+  return _anonymousId;
+}
+
+// ─── session ───────────────────────────────────────────────
+
+const SESSION_FILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.nansen',
+  'session'
+);
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+/**
+ * Get or create a session ID. The session rotates after 30 min of inactivity.
+ * Callers can override via NANSEN_SESSION_ID env var.
+ */
+let _sessionId;
+export function getSessionId() {
+  if (_sessionId !== undefined) return _sessionId;
+
+  if (process.env.NANSEN_SESSION_ID) {
+    _sessionId = process.env.NANSEN_SESSION_ID;
+    return _sessionId;
+  }
+
+  const now = Date.now();
+  try {
+    const raw = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8'));
+    if (raw.id && raw.ts && now - raw.ts < SESSION_TIMEOUT_MS) {
+      _sessionId = raw.id;
+      // touch timestamp, but only if >1 min elapsed to reduce writes
+      if (now - raw.ts > 60_000) {
+        try { fs.writeFileSync(SESSION_FILE, JSON.stringify({ id: _sessionId, ts: now }), 'utf8'); } catch { /* best-effort touch */ }
+      }
+      return _sessionId;
+    }
+  } catch { /* missing or corrupt → new session */ }
+
+  _sessionId = crypto.randomUUID();
+  try {
+    fs.mkdirSync(path.dirname(SESSION_FILE), { recursive: true });
+    fs.writeFileSync(SESSION_FILE, JSON.stringify({ id: _sessionId, ts: now }), 'utf8');
+  } catch { /* best-effort */ }
+  return _sessionId;
+}
+
+// ─── send ──────────────────────────────────────────────────
+
+/**
+ * Send a telemetry event. Fire-and-forget — never throws.
+ */
+function sendEvent(event) {
+  if (TELEMETRY_DISABLED) return;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  timer.unref();
+
+  fetch(TELEMETRY_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(event),
+    signal: controller.signal,
+  })
+    .catch(() => {}) // swallow errors
+    .finally(() => clearTimeout(timer));
+}
+
+// ─── context ───────────────────────────────────────────────
+
+function buildContext() {
+  return {
+    client_type: 'nansen-cli',
+    client_version: cliVersion,
+    system_name: getSystemName(),
+    system_version: os.release(),
+    node_version: process.version,
+  };
+}
+
+// ─── public API ────────────────────────────────────────────
+
+/**
+ * Convert a command string like "smart-money netflow" to a path like "/smart-money/netflow".
+ */
+function commandToPath(command) {
+  return '/' + command.replace(/\s+/g, '/');
+}
+
+/**
+ * Track a CLI command that completed successfully.
+ *
+ * @param {object} opts
+ * @param {string} opts.command  - Full command string, e.g. "smart-money netflow"
+ * @param {number} opts.duration_ms - Wall-clock execution time
+ * @param {boolean} [opts.from_cache] - Whether result was served from cache
+ * @param {string[]} [opts.flags] - Flag names used (no values), e.g. ["--chain", "--pretty"]
+ * @param {string|null} [opts.chain] - Chain name if specified, e.g. "ethereum", "solana"
+ */
+export function trackCommandSucceeded({
+  command,
+  duration_ms,
+  from_cache = false,
+  flags = [],
+  chain = null,
+}) {
+  sendEvent({
+    event: 'cli_command_succeeded',
+    event_source: getEventSource(),
+    event_id: crypto.randomUUID(),
+    user_id: null,
+    anonymous_id: getAnonymousId(),
+    session_id: getSessionId(),
+    timestamp: new Date().toISOString(),
+    path: commandToPath(command),
+    properties: {
+      latency: duration_ms / 1000,
+      from_cache,
+      flags,
+      ...(chain ? { chain } : {}),
+    },
+    context: buildContext(),
+  });
+}
+
+/**
+ * Track a CLI command that failed.
+ *
+ * @param {object} opts
+ * @param {string} opts.command - Full command string
+ * @param {number} opts.duration_ms - Wall-clock execution time
+ * @param {string} opts.error_code - Structured error code (from ErrorCode or custom)
+ * @param {number|null} [opts.status] - HTTP status if the error came from the API
+ * @param {string[]} [opts.flags] - Flag names used
+ * @param {string|null} [opts.chain] - Chain name if specified
+ */
+export function trackCommandFailed({
+  command,
+  duration_ms,
+  error_code,
+  status = null,
+  flags = [],
+  chain = null,
+}) {
+  sendEvent({
+    event: 'cli_command_failed',
+    event_source: getEventSource(),
+    event_id: crypto.randomUUID(),
+    user_id: null,
+    anonymous_id: getAnonymousId(),
+    session_id: getSessionId(),
+    timestamp: new Date().toISOString(),
+    path: commandToPath(command),
+    properties: {
+      latency: duration_ms / 1000,
+      error_code,
+      status,
+      flags,
+      ...(chain ? { chain } : {}),
+    },
+    context: buildContext(),
+  });
+}

package/src/update-check.js

@@ -7,7 +7,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { spawn } from 'child_process';
+import childProcess from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -119,7 +119,7 @@ export function scheduleUpdateCheck() {
       req.setTimeout(5000, () => req.destroy());
     `;
 
-    const child = spawn(process.execPath, ['-e', script], {
+    const child = childProcess.spawn(process.execPath, ['-e', script], {
       detached: true,
       stdio: 'ignore'
     });