nansen-cli 1.34.0 → 1.35.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.35.0
+
+### Minor Changes
+
+- [#469](https://github.com/nansen-ai/nansen-cli/pull/469) [`85b1934`](https://github.com/nansen-ai/nansen-cli/commit/85b1934ae25ed02d1726de8ebe92ea41a98f4454) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's credit and rate-limit response headers.
+
+  Failed calls now report quota state in their error details: an out-of-credits error carries your actual remaining balance, and a rate-limited error carries the limit, what is left, and how long the window needs to drain. Previously the only credit figure the CLI could show was the static per-endpoint estimate published in the API reference — a quote, not what you were charged.
+
+  A warning goes to stderr when your balance will not cover another call of the size just made, so it never interferes with the JSON on stdout.
+
+  Successful responses carry the same numbers under an exported `RESPONSE_META` symbol, and the client exposes `lastResponseMeta`. Both are additive: the JSON each command prints is unchanged.
+
+- [#470](https://github.com/nansen-ai/nansen-cli/pull/470) [`8159300`](https://github.com/nansen-ai/nansen-cli/commit/81593008f829cc83f1d4a6ee9e5c1a10237a9553) Thanks [@gulshngill](https://github.com/gulshngill)! - Surface the API's request id.
+
+  Failed calls now carry `details.requestId` — the value that identifies the call end to end. Quote it when reporting a problem; previously nothing identifying a failed request ever reached the user, which made server errors effectively unreportable. Successful responses expose it alongside the credit and rate-limit figures under the `RESPONSE_META` symbol.
+
+  Absent on deployments that do not send the header yet, in which case the field is simply omitted.
+
 ## 1.34.0
 
 ### Minor Changes

package/README.md

@@ -177,17 +177,28 @@ nansen research smart-money netflow --chain solana --fields token_symbol,net_flo
 
 ```json
 { "success": true,  "data": <api_response> }
-{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401 }
+{ "success": false, "error": "message", "code": "ERROR_CODE", "status": 401, "details": { ... } }
 ```
 
 **Critical error codes:**
 
 | Code | Action |
 |------|--------|
-| `CREDITS_EXHAUSTED` | Stop all API calls immediately. Check [app.nansen.ai](https://app.nansen.ai). |
+| `CREDITS_EXHAUSTED` | Stop all API calls immediately. `details.credits.remaining` is your actual balance. Top up at [app.nansen.ai/api](https://app.nansen.ai/api). |
 | `UNAUTHORIZED` | Wrong or missing key. Re-auth. |
-| `RATE_LIMITED` | Auto-retried by CLI. |
+| `RATE_LIMITED` | Auto-retried by CLI. `details.rateLimit.resetSeconds` is how long the window needs to drain. |
 | `UNSUPPORTED_FILTER` | Remove the filter and retry. |
+| `SERVER_ERROR` | Not your fault. Quote `details.requestId` when reporting it. |
+
+**Error metadata.** When the API reports them, `details` carries:
+
+| Field | Meaning |
+|-------|---------|
+| `requestId` | Identifies this call end to end. Quote it in any support report. Opaque — do not parse it. |
+| `credits` | `used`, `remaining` |
+| `rateLimit` | `limit`, `remaining`, `resetSeconds` |
+
+Any field may be absent or `null`, meaning unknown — never assume zero. A low-balance warning goes to **stderr**, so stdout stays pure JSON.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/scripts/postinstall.js

@@ -41,9 +41,19 @@ function hasTTY() {
   return process.stdin.isTTY && process.stderr.isTTY;
 }
 
+// npx is a .cmd shim on Windows, and Node refuses to spawn .cmd/.bat without a
+// shell (CVE-2024-27980). Go through cmd.exe explicitly rather than enabling
+// `shell: true`, which would hand the whole command line to the shell parser.
+const IS_WIN = process.platform === "win32";
+
+function npxInvocation(args) {
+  return IS_WIN ? ["cmd.exe", ["/c", "npx", ...args]] : ["npx", args];
+}
+
 function hasNpx() {
   try {
-    execFileSync("npx", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
+    const [cmd, cmdArgs] = npxInvocation(["--version"]);
+    execFileSync(cmd, cmdArgs, { stdio: "ignore", shell: false });
     return true;
   } catch {
     return false;
@@ -86,7 +96,7 @@ function prompt(question) {
 
 function runCommand(cmd, args) {
   return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    const child = spawn(cmd, args, { stdio: "inherit", shell: false });
     child.on("close", (code) => resolve(code === 0));
     child.on("error", () => resolve(false));
   });
@@ -113,7 +123,7 @@ async function installSkill() {
   }
 
   log(`Installing Nansen skill...`);
-  const ok = await runCommand("npx", ["-y", "skills", "add", SKILL_REPO]);
+  const ok = await runCommand(...npxInvocation(["-y", "skills", "add", SKILL_REPO]));
   if (!ok) {
     log(`${YELLOW}Skill installation failed. You can retry with: npx skills add ${SKILL_REPO}${RESET}`);
   }

package/src/api.js

@@ -8,6 +8,16 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { EVM_CHAINS } from './chain-ids.js';
 import { getAnonymousId, TELEMETRY_DISABLED } from './telemetry.js';
+import { readResponseMeta } from './response-meta.js';
+
+/**
+ * Key for the credit/rate-limit metadata attached to a successful response.
+ *
+ * A symbol on purpose: JSON.stringify and Object.keys both skip it, so the JSON
+ * every command prints is byte-for-byte unchanged while callers that want the
+ * numbers can still read them off the returned object.
+ */
+export const RESPONSE_META = Symbol('nansenResponseMeta');
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -465,6 +475,15 @@ export class NansenAPI {
       ttl: options.cache?.ttl ?? DEFAULT_CACHE_TTL
     };
     this.defaultHeaders = options.defaultHeaders || {};
+    /**
+     * Credit/rate-limit metadata from the most recent response, or null.
+     *
+     * Survives any reshaping a command handler does to the response body, which
+     * the RESPONSE_META symbol on the returned object does not. Last write wins
+     * when a handler makes several calls — the freshest balance, which is what a
+     * low-credit warning wants.
+     */
+    this.lastResponseMeta = null;
   }
 
   static cleanBody(body) {
@@ -520,7 +539,11 @@ export class NansenAPI {
         }
       } catch { /* balance check is best-effort */ }
     }
-    return await paidResponse.json();
+    const data = await paidResponse.json();
+    const meta = readResponseMeta(paidResponse);
+    this.lastResponseMeta = meta;
+    if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+    return data;
   }
 
   async request(endpoint, body = {}, options = {}) {
@@ -581,11 +604,17 @@ export class NansenAPI {
         data = await response.json();
       } catch (_err) {
         // Non-JSON response (rare, usually server errors)
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         const error = new NansenError(
           `Invalid response from API (status ${response.status})`,
           response.status >= 500 ? ErrorCode.SERVER_ERROR : ErrorCode.UNKNOWN,
           response.status,
-          { body: await response.text().catch(() => null), attempt: attempt + 1 }
+          {
+            body: await response.text().catch(() => null),
+            attempt: attempt + 1,
+            ...(meta?.requestId && { requestId: meta.requestId })
+          }
         );
         
         if (shouldRetry && attempt < maxRetries && response.status >= 500) {
@@ -702,10 +731,23 @@ export class NansenAPI {
           }
         }
 
+        // Quota state and the request id belong on the error above all: an
+        // out-of-credits or rate-limited failure is exactly when the caller
+        // needs the numbers, and a 5xx is worthless to support without the id.
+        // formatError() surfaces details, so this needs no plumbing.
+        //
+        // On a retried call this is the LAST attempt's id — each attempt gets
+        // its own server-side id, and the last one is the failure worth
+        // reporting.
+        const meta = readResponseMeta(response);
+        this.lastResponseMeta = meta;
         lastError = new NansenError(message, code, response.status, {
           ...data,
           attempt: attempt + 1,
-          retryAfterMs
+          retryAfterMs,
+          ...(meta?.requestId && { requestId: meta.requestId }),
+          ...(meta?.credits && { credits: meta.credits }),
+          ...(meta?.rateLimit && { rateLimit: meta.rateLimit })
         });
         
         // Retry on specific status codes
@@ -722,12 +764,21 @@ export class NansenAPI {
       if (attempt > 0) {
         data._meta = { ...(data._meta || {}), retriedAttempts: attempt };
       }
-      
+
       // Cache successful response
       if (useCache) {
         setCachedResponse(endpoint, body, data);
       }
-      
+
+      // Attach after caching so the cache stores the payload alone — quota
+      // numbers are per-response and would be stale on a cache hit.
+      // Guarded: a response body can be a primitive, which cannot take a property.
+      const meta = readResponseMeta(response);
+      this.lastResponseMeta = meta;
+      if (meta) {
+        if (data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
+      }
+
       return data;
     }
     

package/src/cli.js

@@ -14,6 +14,7 @@ import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
 import { getUpdateNotification, getUpgradeNotice, scheduleUpdateCheck } from './update-check.js';
 import { refreshCostMapIfStale, getCostForEndpoint } from './cost-cache.js';
+import { creditWarning, noticeWarnings } from './response-meta.js';
 import { trackCommandSucceeded, trackCommandFailed } from './telemetry.js';
 import { createRequire } from 'module';
 import * as readline from 'readline';
@@ -1854,6 +1855,14 @@ export async function runCLI(rawArgs, deps = {}) {
     const api = new NansenAPIClass(undefined, undefined, { retry: retryOptions, cache: cacheOptions, defaultHeaders });
     let result = await commands[command](subArgs, api, flags, options);
 
+    // Credit balance warning, from the headers on the call just made. Goes to
+    // stderr so it never contaminates the JSON on stdout that agents parse.
+    // Placed before every return path below so it fires for operational
+    // commands too, which print their own output and return undefined.
+    const lowCredits = creditWarning(api.lastResponseMeta);
+    if (lowCredits) errorOutput(lowCredits);
+    for (const notice of noticeWarnings(api.lastResponseMeta)) errorOutput(notice);
+
     // Commands that handle their own output return undefined
     if (result === undefined) {
       await trackCommandSucceeded({ command: fullCommand, duration_ms: Date.now() - startTime, flags: usedFlags, chain });

package/src/response-meta.js

@@ -0,0 +1,123 @@
+/**
+ * Request-id, credit, rate-limit, and notice metadata, read from Nansen API
+ * response headers.
+ *
+ * The API reports what a call actually cost, what quota is left, and an id that
+ * identifies the call end to end. Until now the CLI dropped those headers on the
+ * floor and showed only the static per-endpoint estimate published in the
+ * OpenAPI spec (see cost-cache.js), which is a quote rather than a charge.
+ *
+ * readResponseMeta(response) — parse the headers, or null if none are present
+ * creditWarning(meta)        — stderr warning string when the balance is short, else null
+ *
+ * Every header is optional. Some auth rails charge no credits, some responses
+ * are served before quota is resolved, and older deployments may send neither
+ * the rate-limit triplet nor the request id — so a missing header means
+ * "unknown", never zero.
+ */
+
+/** Header names, as documented in the API reference. */
+const CREDITS_USED = 'x-nansen-credits-used';
+const CREDITS_REMAINING = 'x-nansen-credits-remaining';
+const RATE_LIMIT = 'x-ratelimit-limit';
+const RATE_REMAINING = 'x-ratelimit-remaining';
+const RATE_RESET = 'x-ratelimit-reset';
+const UPGRADE_HINT = 'x-nansen-upgrade-hint';
+const PLAN_NOTICE = 'x-nansen-plan-notice';
+const API_KEY_NOTICE = 'x-nansen-api-key-notice';
+const REQUEST_ID = 'x-request-id';
+
+/**
+ * Read a header as a non-negative integer, or null when absent/unparseable.
+ * Tolerates any header bag with a .get() — a real Headers, or a Map in tests.
+ */
+function intHeader(response, name) {
+  const raw = stringHeader(response, name);
+  if (raw === null) return null;
+  const value = Number.parseInt(raw, 10);
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Read a header as a trimmed non-empty string, or null when absent.
+ * Tolerates any header bag with a .get() — a real Headers, or a Map in tests.
+ */
+function stringHeader(response, name) {
+  const raw = response?.headers?.get?.(name);
+  if (raw == null) return null;
+  const value = String(raw).trim();
+  return value === '' ? null : value;
+}
+
+/**
+ * Extract request-id, credit, rate-limit, and notice metadata from a fetch Response.
+ * Returns null when the response carries none of it, so callers can skip
+ * attaching an object full of nulls.
+ */
+export function readResponseMeta(response) {
+  const used = intHeader(response, CREDITS_USED);
+  const remaining = intHeader(response, CREDITS_REMAINING);
+  const limit = intHeader(response, RATE_LIMIT);
+  const rateRemaining = intHeader(response, RATE_REMAINING);
+  const resetSeconds = intHeader(response, RATE_RESET);
+  const upgradeHint = stringHeader(response, UPGRADE_HINT);
+  const planNotice = stringHeader(response, PLAN_NOTICE);
+  const apiKeyNotice = stringHeader(response, API_KEY_NOTICE);
+  const requestId = stringHeader(response, REQUEST_ID);
+
+  const meta = {};
+  if (requestId !== null) {
+    // The single value that identifies this call to Nansen support. Opaque —
+    // never parse it or assume a format.
+    meta.requestId = requestId;
+  }
+  if (used !== null || remaining !== null) {
+    meta.credits = { used, remaining };
+  }
+  if (limit !== null || rateRemaining !== null || resetSeconds !== null) {
+    // resetSeconds is a delta in seconds — how long the tripped window needs to
+    // drain — not a wall-clock timestamp.
+    meta.rateLimit = { limit, remaining: rateRemaining, resetSeconds };
+  }
+  if (upgradeHint !== null || planNotice !== null || apiKeyNotice !== null) {
+    meta.notices = {
+      ...(upgradeHint !== null && { upgradeHint }),
+      ...(planNotice !== null && { planNotice }),
+      ...(apiKeyNotice !== null && { apiKeyNotice }),
+    };
+  }
+  return Object.keys(meta).length > 0 ? meta : null;
+}
+
+/**
+ * Yield notice strings for any server-set advisory headers.
+ * Each yields a `⚠️  <message>` line for stderr.
+ * Order: apiKeyNotice (most urgent) → upgradeHint → planNotice.
+ */
+export function noticeWarnings(meta) {
+  const notices = meta?.notices;
+  if (!notices) return [];
+  const out = [];
+  if (notices.apiKeyNotice) out.push(`⚠️  ${notices.apiKeyNotice}`);
+  if (notices.upgradeHint) out.push(`ℹ️  ${notices.upgradeHint}`);
+  if (notices.planNotice) out.push(`ℹ️  ${notices.planNotice}`);
+  return out;
+}
+
+/**
+ * Warn only when the remaining balance will not cover another call of the size
+ * just made.
+ */
+export function creditWarning(meta) {
+  const credits = meta?.credits;
+  if (!credits) return null;
+  const { used, remaining } = credits;
+  if (remaining === null) return null;
+  if (remaining === 0) {
+    return '⚠️  Out of API credits. Top up at https://app.nansen.ai/api';
+  }
+  if (used !== null && used > 0 && remaining < used) {
+    return `⚠️  ${remaining} API credit${remaining === 1 ? '' : 's'} left — less than this call cost (${used}). Top up at https://app.nansen.ai/api`;
+  }
+  return null;
+}