nansen-cli 1.1.1 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/nansen-cli.svg)](https://www.npmjs.com/package/nansen-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-342%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-323%20passing-brightgreen.svg)]()
 [![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)]()
 
 > **Built by agents, for agents.** We prioritize the best possible AI agent experience.
@@ -137,6 +137,15 @@ nansen schema smart-money --pretty
 
 Returns command definitions, option types/defaults, supported chains, and smart money labels.
 
+### `cache` - Cache Management
+
+Manage the local response cache.
+
+```bash
+# Clear all cached responses
+nansen cache clear
+```
+
 ## Options
 
 | Option | Description |
@@ -144,6 +153,10 @@ Returns command definitions, option types/defaults, supported chains, and smart
 | `--pretty` | Format JSON output for readability |
 | `--table` | Format output as human-readable table |
 | `--fields <list>` | Comma-separated fields to include (reduces response size) |
+| `--cache` | Enable response caching |
+| `--no-cache` | Bypass cache for this request |
+| `--cache-ttl <s>` | Cache TTL in seconds (default: 300) |
+| `--stream` | Output as JSON lines (NDJSON) for incremental processing |
 | `--chain <chain>` | Blockchain to query |
 | `--chains <json>` | Multiple chains as JSON array |
 | `--limit <n>` | Number of results |
@@ -191,13 +204,6 @@ This CLI is built specifically for AI agents. Every design decision prioritizes
 }
 ```
 
-**Roadmap** (see [TODO.md](TODO.md)):
-- ~~Rate limit handling with auto-retry~~ ✅
-- ~~Structured error codes for programmatic handling~~ ✅
-- ~~Schema discovery endpoint (`nansen schema`)~~ ✅
-- ~~Field filtering to reduce response size~~ ✅
-- Response caching and batch queries
-
 ## Examples
 
 ```bash

package/TODO.md

@@ -2,36 +2,14 @@
 
 > **Built by agents, for agents.** We prioritize improvements that create the best possible AI agent experience.
 
-## Medium Priority
+## P2 - Nice to Have
 
-### Response Caching
-- [ ] Add optional local cache (SQLite or file-based)
-- [ ] Configurable TTL (default 60-300s)
-- [ ] `--no-cache` flag to bypass
-- [ ] `--cache-ttl` flag to override
-
-### Batch Queries
-- [ ] Support multiple addresses: `--addresses '[...]'`
-- [ ] Support multiple tokens: `--tokens '[...]'`
-- [ ] Reduce N calls to 1 call
-
-## Test Quality
-
-### Remaining Items
-- [ ] Test config priority chain (ENV > ~/.nansen > local config.json) — needs `loadConfig()` exported
+### Test Coverage Gaps
+- [ ] Test config priority chain (ENV > ~/.nansen > local) — needs `loadConfig()` exported
 - [ ] Add snapshot tests for `--help` output
 - [ ] Document magic test addresses (e.g. Binance hot wallet)
 - [ ] Test Bitcoin address validation
 - [ ] Test stdin pipe mode for API key input
-- [ ] Remove duplicated `parseArgs` in unit.test.js (now exported from cli.js)
-- [ ] Reduce cli.test.js subprocess tests to ~10 smoke tests
-
-## Nice to Have
-
-### Streaming Output
-- [ ] `--stream` flag for large result sets
-- [ ] Output as JSON lines (newline-delimited JSON)
-- [ ] Enable incremental processing by agents
 
 ### Shell Completions
 - [ ] Bash completions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Command-line interface for Nansen API - designed for AI agents",
   "main": "src/index.js",
   "type": "module",

package/src/api.js

@@ -145,6 +145,93 @@ export function deleteConfig() {
   return false;
 }
 
+// ============= Response Cache =============
+
+const CACHE_DIR = path.join(CONFIG_DIR, 'cache');
+const DEFAULT_CACHE_TTL = 300; // 5 minutes
+
+import crypto from 'crypto';
+
+/**
+ * Generate cache key from endpoint and request body
+ */
+function getCacheKey(endpoint, body) {
+  const data = JSON.stringify({ endpoint, body });
+  return crypto.createHash('md5').update(data).digest('hex');
+}
+
+/**
+ * Get cached response if valid
+ */
+export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL) {
+  const cacheKey = getCacheKey(endpoint, body);
+  const cacheFile = path.join(CACHE_DIR, `${cacheKey}.json`);
+  
+  if (!fs.existsSync(cacheFile)) {
+    return null;
+  }
+  
+  try {
+    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    const age = (Date.now() - cached.timestamp) / 1000;
+    
+    if (ttlSeconds <= 0 || age > ttlSeconds) {
+      // Cache expired or TTL is 0, delete it
+      fs.unlinkSync(cacheFile);
+      return null;
+    }
+    
+    return { ...cached.data, _meta: { ...cached.data._meta, fromCache: true, cacheAge: Math.round(age) } };
+  } catch (e) {
+    // Invalid cache file, delete it
+    try { fs.unlinkSync(cacheFile); } catch {}
+    return null;
+  }
+}
+
+/**
+ * Save response to cache
+ */
+export function setCachedResponse(endpoint, body, data) {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { mode: 0o700, recursive: true });
+  }
+  
+  const cacheKey = getCacheKey(endpoint, body);
+  const cacheFile = path.join(CACHE_DIR, `${cacheKey}.json`);
+  
+  const cached = {
+    timestamp: Date.now(),
+    endpoint,
+    data
+  };
+  
+  fs.writeFileSync(cacheFile, JSON.stringify(cached), { mode: 0o600 });
+}
+
+/**
+ * Clear all cached responses
+ */
+export function clearCache() {
+  if (fs.existsSync(CACHE_DIR)) {
+    const files = fs.readdirSync(CACHE_DIR);
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        fs.unlinkSync(path.join(CACHE_DIR, file));
+      }
+    }
+    return files.length;
+  }
+  return 0;
+}
+
+/**
+ * Get cache directory path
+ */
+export function getCacheDir() {
+  return CACHE_DIR;
+}
+
 // ============= Address Validation =============
 
 const ADDRESS_PATTERNS = {
@@ -299,6 +386,10 @@ export class NansenAPI {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl;
     this.retryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
+    this.cacheOptions = { 
+      enabled: options.cache?.enabled ?? false,
+      ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
+    };
   }
 
   async request(endpoint, body = {}, options = {}) {
@@ -306,6 +397,17 @@ export class NansenAPI {
     const { maxRetries, baseDelayMs, maxDelayMs, retryOnStatus } = this.retryOptions;
     const shouldRetry = options.retry !== false; // Allow disabling retry per-request
     
+    // Check cache first (if enabled and not bypassed)
+    const useCache = options.cache !== false && this.cacheOptions.enabled;
+    const cacheTtl = options.cacheTtl ?? this.cacheOptions.ttl;
+    
+    if (useCache) {
+      const cached = getCachedResponse(endpoint, body, cacheTtl);
+      if (cached) {
+        return cached;
+      }
+    }
+    
     let lastError;
     
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -383,6 +485,12 @@ export class NansenAPI {
       if (attempt > 0) {
         data._meta = { ...(data._meta || {}), retriedAttempts: attempt };
       }
+      
+      // Cache successful response
+      if (useCache) {
+        setCachedResponse(endpoint, body, data);
+      }
+      
       return data;
     }
     

package/src/cli.js

@@ -3,7 +3,7 @@
  * Extracted from index.js for coverage
  */
 
-import { NansenAPI, saveConfig, deleteConfig, getConfigFile } from './api.js';
+import { NansenAPI, saveConfig, deleteConfig, getConfigFile, clearCache, getCacheDir } from './api.js';
 import * as readline from 'readline';
 
 // ============= Schema Definition =============
@@ -278,7 +278,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'table' || key === 'no-retry') {
+      if (key === 'pretty' || key === 'help' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream') {
         result.flags[key] = true;
       } else if (next && !next.startsWith('-')) {
         // Try to parse as JSON first
@@ -411,6 +411,34 @@ export function formatError(error) {
   };
 }
 
+/**
+ * Format data as JSON lines (NDJSON) for streaming output
+ * Each record is output as a separate JSON line
+ */
+export function formatStream(data) {
+  // Extract array of records from various response shapes
+  let records = [];
+  if (Array.isArray(data)) {
+    records = data;
+  } else if (data?.data && Array.isArray(data.data)) {
+    records = data.data;
+  } else if (data?.results && Array.isArray(data.results)) {
+    records = data.results;
+  } else if (data?.data?.results && Array.isArray(data.data.results)) {
+    records = data.data.results;
+  } else if (typeof data === 'object' && data !== null) {
+    // Single object - output as single line
+    records = [data];
+  }
+
+  if (records.length === 0) {
+    return '';
+  }
+
+  // Output each record as a separate JSON line
+  return records.map(record => JSON.stringify(record)).join('\n');
+}
+
 // 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)
@@ -439,6 +467,7 @@ COMMANDS:
   login          Save your API key (interactive)
   logout         Remove saved API key
   schema         Output JSON schema for all commands (for agent introspection)
+  cache          Cache management (clear)
   smart-money    Smart Money analytics (netflow, dex-trades, holdings, dcas, historical-holdings)
   profiler       Wallet profiling (balance, labels, transactions, pnl, perp-positions, perp-trades)
   token          Token God Mode (screener, holders, flows, trades, pnl, perp-trades, perp-positions)
@@ -459,6 +488,10 @@ GLOBAL OPTIONS:
   --symbol       Token symbol (for perp endpoints)
   --no-retry     Disable automatic retry on rate limits/errors
   --retries <n>  Max retry attempts (default: 3)
+  --cache        Enable response caching (default: off)
+  --no-cache     Disable cache for this request
+  --cache-ttl <s> Cache TTL in seconds (default: 300)
+  --stream       Output as JSON lines (NDJSON) for incremental processing
 
 EXAMPLES:
   # Get Smart Money netflow on Solana
@@ -620,6 +653,35 @@ export function buildCommands(deps = {}) {
       return SCHEMA;
     },
 
+    'cache': async (args, apiInstance, flags, options) => {
+      const subcommand = args[0] || 'help';
+      
+      const handlers = {
+        'clear': () => {
+          const count = clearCache();
+          log(`✓ Cleared ${count} cached responses`);
+          log(`  Cache dir: ${getCacheDir()}`);
+        },
+        'help': () => {
+          log('Cache Management\n');
+          log('USAGE:');
+          log('  nansen cache clear    Clear all cached responses\n');
+          log('CACHE OPTIONS (for any command):');
+          log('  --cache               Enable caching for this session');
+          log('  --no-cache            Bypass cache for this request');
+          log('  --cache-ttl <seconds> Set cache TTL (default: 300)');
+        }
+      };
+      
+      if (!handlers[subcommand]) {
+        log(`Unknown cache subcommand: ${subcommand}`);
+        handlers['help']();
+        return;
+      }
+      
+      return handlers[subcommand]();
+    },
+
     'smart-money': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const chain = options.chain || 'solana';
@@ -763,7 +825,7 @@ export function buildCommands(deps = {}) {
 }
 
 // Commands that don't require API authentication
-export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema'];
+export const NO_AUTH_COMMANDS = ['login', 'logout', 'help', 'schema', 'cache'];
 
 // Run CLI with given args (returns result, allows custom output/exit handlers)
 export async function runCLI(rawArgs, deps = {}) {
@@ -781,6 +843,7 @@ export async function runCLI(rawArgs, deps = {}) {
   const subArgs = positional.slice(1);
   const pretty = flags.pretty || flags.p;
   const table = flags.table || flags.t;
+  const stream = flags.stream || flags.s;
 
   const commands = { ...buildCommands(deps), ...commandOverrides };
 
@@ -820,7 +883,13 @@ export async function runCLI(rawArgs, deps = {}) {
       ? { maxRetries: 0 } 
       : { maxRetries: options.retries !== undefined ? options.retries : 3 };
     
-    const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions });
+    // Configure cache options
+    const cacheOptions = {
+      enabled: flags['cache'] && !flags['no-cache'],
+      ttl: options['cache-ttl'] !== undefined ? options['cache-ttl'] : 300
+    };
+    
+    const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions });
     let result = await commands[command](subArgs, api, flags, options);
     
     // Apply field filtering if --fields is specified
@@ -829,6 +898,16 @@ export async function runCLI(rawArgs, deps = {}) {
       result = filterFields(result, fields);
     }
     
+    // Output in requested format
+    if (stream) {
+      // Stream mode: output each record as a JSON line (NDJSON)
+      const streamOutput = formatStream(result);
+      if (streamOutput) {
+        output(streamOutput);
+      }
+      return { type: 'stream', data: result };
+    }
+    
     const successData = { success: true, data: result };
     const formatted = formatOutput(successData, { pretty, table });
     output(formatted.text);