nansen-cli 1.46.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +129 -14
  3. package/docs/browser-login.md +117 -0
  4. package/package.json +11 -2
  5. package/scripts/postinstall.js +35 -30
  6. package/skills/nansen-agent-guide/SKILL.md +13 -2
  7. package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
  8. package/skills/nansen-dca-tracker/SKILL.md +10 -2
  9. package/skills/nansen-defi-positions/SKILL.md +5 -2
  10. package/skills/nansen-exit-signals/SKILL.md +10 -2
  11. package/skills/nansen-fund-tracker/SKILL.md +10 -2
  12. package/skills/nansen-general-search/SKILL.md +10 -2
  13. package/skills/nansen-holder-analysis/SKILL.md +10 -2
  14. package/skills/nansen-limit-orders/SKILL.md +6 -3
  15. package/skills/nansen-perp-screener/SKILL.md +10 -2
  16. package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
  17. package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
  18. package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
  19. package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
  20. package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
  21. package/skills/nansen-prediction-markets/SKILL.md +10 -2
  22. package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
  23. package/skills/nansen-smart-alerts/SKILL.md +9 -4
  24. package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
  25. package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
  26. package/skills/nansen-smart-money-trend/SKILL.md +10 -2
  27. package/skills/nansen-token-research/SKILL.md +10 -2
  28. package/skills/nansen-token-screener/SKILL.md +14 -4
  29. package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
  30. package/skills/nansen-trading/SKILL.md +8 -2
  31. package/skills/nansen-wallet-batch/SKILL.md +10 -2
  32. package/skills/nansen-wallet-clustering/SKILL.md +10 -2
  33. package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
  34. package/skills/nansen-wallet-keychain-migration/SKILL.md +5 -2
  35. package/skills/nansen-wallet-manager/SKILL.md +11 -9
  36. package/skills/nansen-wallet-profiler/SKILL.md +10 -2
  37. package/skills/nansen-web-fetcher/SKILL.md +5 -2
  38. package/skills/nansen-web-searcher/SKILL.md +5 -2
  39. package/src/api.js +202 -104
  40. package/src/auth-browser.js +16 -0
  41. package/src/auth-credentials.js +73 -0
  42. package/src/auth-device.js +242 -0
  43. package/src/auth-key-input.js +46 -0
  44. package/src/auth-login.js +90 -0
  45. package/src/auth-state.js +487 -0
  46. package/src/auth-store-native.js +20 -0
  47. package/src/auth-store-worker.js +64 -0
  48. package/src/auth-store.js +140 -0
  49. package/src/auto-paginate.js +272 -0
  50. package/src/bridge.js +126 -21
  51. package/src/cache-inspect.js +345 -0
  52. package/src/cli.js +470 -197
  53. package/src/commands/agent.js +15 -7
  54. package/src/commands/completion.js +2 -15
  55. package/src/commands/mcp.js +20 -18
  56. package/src/cost-cache.js +16 -2
  57. package/src/debug.js +348 -0
  58. package/src/doctor.js +22 -45
  59. package/src/hl-action.js +41 -13
  60. package/src/mcp-client-config.js +169 -0
  61. package/src/mcp-client-config.json +17 -0
  62. package/src/mcp-verify.js +6 -5
  63. package/src/perp.js +41 -0
  64. package/src/privy.js +12 -12
  65. package/src/response-meta.js +56 -1
  66. package/src/rpc-urls.js +9 -11
  67. package/src/schema.json +185 -8
  68. package/src/semver.js +23 -4
  69. package/src/swap-simulation.js +35 -30
  70. package/src/telemetry.js +20 -0
  71. package/src/trading.js +266 -29
  72. package/src/transfer.js +53 -6
  73. package/src/update-check.js +9 -1
  74. package/src/wallet.js +107 -17
  75. package/src/walletconnect-trading.js +24 -5
  76. package/src/x402-svm.js +123 -64
  77. package/src/x402.js +46 -14
@@ -4,20 +4,20 @@
4
4
  */
5
5
 
6
6
  import crypto from 'crypto';
7
- import { NansenError, ErrorCode, statusToErrorCode, telemetryHeaders, packageVersion } from '../api.js';
7
+ import { NansenError, ErrorCode, statusToErrorCode, browserSessionError, browserSessionResponseMeta, telemetryHeaders, packageVersion } from '../api.js';
8
8
  import { getCostForEndpoint } from '../cost-cache.js';
9
9
  import { readResponseMeta } from '../response-meta.js';
10
10
 
11
11
  /**
12
12
  * Build standard request headers, matching apiInstance.request() conventions.
13
13
  */
14
- function buildHeaders(apiInstance) {
14
+ async function buildHeaders(apiInstance) {
15
15
  return {
16
16
  'Content-Type': 'application/json',
17
17
  'X-Client-Type': 'nansen-cli',
18
18
  'X-Client-Version': packageVersion,
19
19
  ...telemetryHeaders(),
20
- ...(apiInstance.apiKey ? { 'apikey': apiInstance.apiKey } : {}),
20
+ ...await apiInstance.requestCredentials(),
21
21
  ...(apiInstance.defaultHeaders || {}),
22
22
  };
23
23
  }
@@ -242,7 +242,7 @@ EXAMPLES:
242
242
  }
243
243
 
244
244
  // ── Auth guard ──
245
- if (!apiInstance.apiKey) {
245
+ if (apiInstance.selection?.kind === 'anonymous') {
246
246
  throw new NansenError(
247
247
  'Not logged in. Run: nansen login',
248
248
  ErrorCode.UNAUTHORIZED,
@@ -252,12 +252,15 @@ EXAMPLES:
252
252
  }
253
253
 
254
254
  // ── Request (no retry — SSE streams are not idempotent) ──
255
+ const sessionAuth = apiInstance.selection?.kind === 'session';
255
256
  const url = `${apiInstance.baseUrl}${endpoint}`;
256
257
  const body = {
257
258
  text: question,
258
259
  conversation_id: conversationId,
259
260
  };
260
261
 
262
+ const requestHeaders = await buildHeaders(apiInstance);
263
+
261
264
  // ── Timeout ──
262
265
  const timeoutMs = expert ? 300_000 : 120_000; // 5min expert, 2min fast
263
266
  const controller = new AbortController();
@@ -271,7 +274,7 @@ EXAMPLES:
271
274
  // forwards custom credential headers (apikey) across a cross-origin
272
275
  // redirect, handing the key to whatever host the response points at.
273
276
  redirect: 'error',
274
- headers: buildHeaders(apiInstance),
277
+ headers: requestHeaders,
275
278
  body: JSON.stringify(body),
276
279
  signal: controller.signal,
277
280
  });
@@ -286,10 +289,10 @@ EXAMPLES:
286
289
  );
287
290
  }
288
291
  throw new NansenError(
289
- `Network error: ${err.message}`,
292
+ sessionAuth ? 'Agent network request failed. Retry after checking connectivity.' : `Network error: ${err.message}`,
290
293
  ErrorCode.NETWORK_ERROR,
291
294
  null,
292
- { originalError: err.message },
295
+ sessionAuth ? {} : { originalError: err.message },
293
296
  );
294
297
  }
295
298
 
@@ -303,6 +306,10 @@ EXAMPLES:
303
306
  serverDetail = errData.detail || errData.message;
304
307
  } catch { /* ignore parse failure */ }
305
308
  }
309
+ if (sessionAuth) {
310
+ const safe = browserSessionError(response.status, errData);
311
+ throw new NansenError(safe.message, safe.code, response.status, browserSessionResponseMeta(response));
312
+ }
306
313
  const meta = readResponseMeta(response);
307
314
  throwApiError(
308
315
  serverDetail || `Agent returned ${response.status}`,
@@ -324,6 +331,7 @@ EXAMPLES:
324
331
  { detail: `${modeName} mode timeout (${timeoutMs / 1000}s)` },
325
332
  );
326
333
  }
334
+ if (sessionAuth) throw new NansenError('Agent stream failed. The selected browser session was not replaced.', err.code || ErrorCode.NETWORK_ERROR, err.status || null);
327
335
  throw err;
328
336
  };
329
337
 
@@ -19,28 +19,15 @@ const { version: VERSION } = require('../../package.json');
19
19
  export const COMPLETION_SHELLS = ['bash', 'zsh', 'fish'];
20
20
 
21
21
  /**
22
- * Commands the CLI dispatches that schema.json does not describe. Adding them
23
- * to schema.json instead would change `nansen logout --help` (the schema help
24
- * path runs before the hand-written text), so they are declared here.
22
+ * Commands the CLI dispatches that schema.json does not describe. They retain
23
+ * their hand-written help; the schema help path otherwise takes precedence.
25
24
  * completion.test.js fails if a new top-level command appears in neither place.
26
25
  */
27
26
  export const UNSCHEMA_COMMANDS = {
28
- login: {
29
- description: 'Save your Nansen API key',
30
- options: {
31
- 'api-key': { type: 'string', description: 'API key (recorded in shell history — prefer --human)' },
32
- human: { type: 'boolean', description: 'Prompt for the key interactively' },
33
- },
34
- },
35
- logout: { description: 'Remove the saved API key' },
36
27
  schema: {
37
28
  description: 'Print the JSON schema for every command',
38
29
  options: { full: { type: 'boolean', description: 'Verbose schema instead of the compact listing' } },
39
30
  },
40
- cache: {
41
- description: 'API response cache maintenance',
42
- subcommands: { clear: { description: 'Clear all cached responses' } },
43
- },
44
31
  changelog: {
45
32
  description: 'Show release history',
46
33
  options: { since: { type: 'string', description: 'Only show versions at or above this one' } },
@@ -8,22 +8,27 @@
8
8
 
9
9
  import { CommandError } from '../api.js';
10
10
  import { DEFAULT_MCP_URL, formatMcpVerifyReport, runMcpVerifyChecks } from '../mcp-verify.js';
11
+ import { MCP_CLIENT_CONFIG, buildHttpEntry, buildStdioEntry, mcpRemoteSpec } from '../mcp-client-config.js';
11
12
  import fs from 'fs';
12
13
  import os from 'os';
13
14
  import path from 'path';
14
15
 
16
+ // All values below come from src/mcp-client-config.json (API-322), the one
17
+ // maintained source that the README, the GitBook page and the .dxt manifest
18
+ // are generated from. Edit that file, not these constants.
19
+
15
20
  // Hosted Nansen MCP server (streamable HTTP, auth via NANSEN-API-KEY header).
16
- // Deliberately a constant: a user-supplied URL would let `install` write the
17
- // API key into a config that sends it to an arbitrary host. NANSEN_BASE_URL
18
- // (REST dev override) intentionally does not affect this.
19
- export const NANSEN_MCP_URL = 'https://mcp.nansen.ai/ra/mcp';
21
+ // Deliberately not user-configurable: a user-supplied URL would let `install`
22
+ // write the API key into a config that sends it to an arbitrary host.
23
+ // NANSEN_BASE_URL (REST dev override) intentionally does not affect this.
24
+ export const NANSEN_MCP_URL = MCP_CLIENT_CONFIG.endpoint;
20
25
 
21
26
  // Claude Desktop's config only supports stdio servers, so it bridges through
22
27
  // mcp-remote. Pinned exact so `npx -y` never auto-pulls a compromised future
23
- // release; bump deliberately.
24
- export const MCP_REMOTE_PIN = 'mcp-remote@0.2.1';
28
+ // release; bump deliberately (see AGENTS.md > MCP client config).
29
+ export const MCP_REMOTE_PIN = mcpRemoteSpec();
25
30
 
26
- const SERVER_KEY = 'nansen';
31
+ const SERVER_KEY = MCP_CLIENT_CONFIG.serverKey;
27
32
 
28
33
  // House idiom (see src/api.js CONFIG_DIR): env first so tests can point HOME
29
34
  // at a temp dir; os.homedir() as last resort.
@@ -49,8 +54,8 @@ OPTIONS:
49
54
  --send-api-key Authorize sending your saved API key to a custom --url
50
55
  (an https:// or loopback host). Not needed for --api-key.
51
56
 
52
- The API key is taken from \`nansen login\` / NANSEN_API_KEY. Re-run install after
53
- rotating your key to update the entry. Other clients: https://docs.nansen.ai/mcp/connecting`;
57
+ The API key is taken from \`nansen login --human\` / NANSEN_API_KEY. Re-run install after
58
+ rotating your key to update the entry. Other clients: ${MCP_CLIENT_CONFIG.docsUrl}`;
54
59
 
55
60
  /**
56
61
  * Resolve the client's config file path for this platform.
@@ -83,16 +88,17 @@ export function buildServerEntry(client, apiKey) {
83
88
  switch (client) {
84
89
  case 'claude-code':
85
90
  // "type" is required — a url without type is treated as broken stdio and skipped
86
- return { type: 'http', url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
91
+ return buildHttpEntry(apiKey, { withType: true });
87
92
  case 'cursor':
88
- return { url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
93
+ return buildHttpEntry(apiKey);
89
94
  case 'claude-desktop':
90
95
  // Header name and value must be one arg. mcp-remote parses with
91
96
  // /^([A-Za-z0-9_-]+):\s*(.*)$/, so whitespace after the colon is trimmed;
92
97
  // what breaks it is an empty value.
93
98
  // The ${NANSEN_API_KEY} placeholder is NOT shell syntax: mcp-remote itself
94
99
  // substitutes ${VAR} in header values from its process env — see
95
- // mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576
100
+ // mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576 (re-check this
101
+ // behavior before a pin bump; see AGENTS.md > MCP client config)
96
102
  // (`value.replace(/\$\{([^}]+)}/g, ...)`, logging "Replacing ${...} with
97
103
  // environment value in header"). Claude Desktop injects the `env` block
98
104
  // into the spawned npx process, mcp-remote expands the reference, and the
@@ -100,11 +106,7 @@ export function buildServerEntry(client, apiKey) {
100
106
  // the exact written config connects to prod with the substitution logged.
101
107
  // Do NOT "fix" this by inlining the key into args.
102
108
  // No --allow-http: the URL is HTTPS.
103
- return {
104
- command: 'npx',
105
- args: ['-y', MCP_REMOTE_PIN, NANSEN_MCP_URL, '--header', 'NANSEN-API-KEY:${NANSEN_API_KEY}'],
106
- env: { NANSEN_API_KEY: apiKey },
107
- };
109
+ return buildStdioEntry(apiKey);
108
110
  default:
109
111
  throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
110
112
  }
@@ -356,7 +358,7 @@ export function buildMcpCommands(deps = {}) {
356
358
  // install
357
359
  const apiKey = apiInstance?.apiKey;
358
360
  if (!apiKey) {
359
- throw new CommandError('Not logged in. Run: nansen login', 'NOT_LOGGED_IN');
361
+ throw new CommandError('MCP installation requires an API key. Set NANSEN_API_KEY or run nansen login --human. Browser sessions are not exported to MCP clients.', 'API_KEY_REQUIRED');
360
362
  }
361
363
 
362
364
  // Deliberate asymmetry with uninstall --dry-run (which previews even an
package/src/cost-cache.js CHANGED
@@ -14,6 +14,14 @@ const CACHE_FILE = path.join(CONFIG_DIR, 'cost-map.json');
14
14
  const STALE_MS = 24 * 60 * 60 * 1000; // 24 hours
15
15
  const OPENAPI_URL = 'https://api.nansen.ai/openapi.json';
16
16
 
17
+ /** How long a fetched cost map stays fresh. */
18
+ export const COST_MAP_TTL_MS = STALE_MS;
19
+
20
+ /** Absolute path of the cost map cache file, for `nansen cache stats` and `clear`. */
21
+ export function getCostMapFile() {
22
+ return CACHE_FILE;
23
+ }
24
+
17
25
  /**
18
26
  * Write `data` to `file` atomically: write to a unique temp file in the same
19
27
  * directory, then rename over the target. rename(2) is atomic on POSIX, so a
@@ -55,7 +63,13 @@ export function getCostForEndpoint(endpoint) {
55
63
  export function creditsCharged(meta, endpoint) {
56
64
  const charged = meta?.credits?.cost;
57
65
  if (charged != null) return { cost: charged, source: 'header' };
58
- const estimate = endpoint ? getCostForEndpoint(endpoint) : null;
66
+ let estimate = endpoint ? getCostForEndpoint(endpoint) : null;
67
+ const livePages = meta?.pagination?.livePages;
68
+ if (estimate != null && Number.isSafeInteger(livePages) && livePages > 1) {
69
+ estimate = Object.fromEntries(
70
+ Object.entries(estimate).map(([plan, cost]) => [plan, typeof cost === 'number' ? cost * livePages : cost])
71
+ );
72
+ }
59
73
  if (estimate != null) return { estimate, source: 'estimate' };
60
74
  return null;
61
75
  }
@@ -69,7 +83,7 @@ export async function refreshCostMapIfStale() {
69
83
  try {
70
84
  if (fs.existsSync(CACHE_FILE)) {
71
85
  const { fetchedAt } = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
72
- if (fetchedAt && Date.now() - fetchedAt < STALE_MS) return;
86
+ if (Number.isFinite(fetchedAt) && fetchedAt !== 0 && Date.now() - fetchedAt < STALE_MS) return;
73
87
  }
74
88
 
75
89
  const controller = new AbortController();
package/src/debug.js ADDED
@@ -0,0 +1,348 @@
1
+ /**
2
+ * Opt-in HTTP request tracing for the CLI.
3
+ *
4
+ * Turned on by the global `--debug` flag (which calls setDebugEnabled) or by
5
+ * `NANSEN_DEBUG=1` in the environment. The generic `DEBUG` variable is not
6
+ * consulted: other packages commonly use it, and enabling HTTP tracing must
7
+ * always be an explicit Nansen choice.
8
+ *
9
+ * Everything is written to **stderr**, never stdout. stdout carries the JSON
10
+ * or CSV that callers pipe into other programs, and a trace line in that
11
+ * stream would corrupt it.
12
+ *
13
+ * Nothing here ever prints a credential. Request and response bodies are never
14
+ * traced at all, header values are never traced, URLs go through redactUrl(),
15
+ * and every value handed to trace() goes through redact() first. Redaction is
16
+ * deliberately over-eager: an over-redacted value costs one support round
17
+ * trip, a leaked one costs a key rotation.
18
+ */
19
+
20
+ /** Placeholder written in place of anything that might be a credential. */
21
+ export const REDACTED = '[redacted]';
22
+
23
+ /** Longest traced value; anything longer is cut and marked. */
24
+ export const MAX_VALUE_LENGTH = 200;
25
+
26
+ /**
27
+ * Field/parameter/header names whose value is never safe to print.
28
+ * Matches substrings, so `apikey`, `X-Api-Key`, `authorization`,
29
+ * `payment-signature` and `token_address` are all covered — the last one is
30
+ * not a secret, but fail-closed is the right side to err on here.
31
+ */
32
+ const SECRET_NAME = /key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private/i;
33
+
34
+ /**
35
+ * A credential carried inline in a header-ish string, e.g. `Bearer eyJ...`.
36
+ * Two copies on purpose: a /g regex carries lastIndex between .test() calls,
37
+ * so the matcher and the replacer must not be the same object.
38
+ */
39
+ // Only `Bearer`/`Basic` introduce an inline credential in text we trace. `Payment`
40
+ // and `Signature` are ordinary English words here, and header-name matching plus the
41
+ // value-shape rules below already cover a real payment signature — keeping them in
42
+ // this pattern only garbled prose like "payment was transmitted".
43
+ // The value must look like a credential (8+ chars) so "Bearer token" stays readable.
44
+ // Keep this matcher stateless (no /g): looksLikeSecretValue calls .test() on
45
+ // it, while INLINE_SCHEME_ALL below is the separate global replacement copy.
46
+ const INLINE_SCHEME = /\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/i;
47
+ const INLINE_SCHEME_ALL = new RegExp(INLINE_SCHEME.source, 'gi');
48
+
49
+ /** Request ids and other UUIDs are identifiers, not secrets — keep them readable. */
50
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
51
+
52
+ /** Private-key shaped: 32 bytes of hex, with or without the 0x prefix. */
53
+ const HEX_32_BYTES = /^(0x)?[0-9a-fA-F]{64}$/;
54
+
55
+ /**
56
+ * BIP-39 shaped: 12–24 lowercase words. Intentionally covers non-standard
57
+ * counts between the valid BIP-39 sizes too; over-redacting prose is safer
58
+ * than letting a malformed or partially copied recovery phrase through.
59
+ */
60
+ const MNEMONIC = /^([a-z]{3,10} ){11,23}[a-z]{3,10}$/;
61
+
62
+ /** JWT shaped: three dot-separated base64url segments starting with a JSON header. */
63
+ const JWT = /^ey[\w-]{8,}\.[\w-]{4,}\.[\w-]+$/;
64
+
65
+ /** Base58 secret-key shaped (Solana keypairs are ~88 chars; addresses are ≤44). */
66
+ const LONG_BASE58 = /^[1-9A-HJ-NP-Za-km-z]{80,}$/;
67
+
68
+ /**
69
+ * Long opaque blob — an encoded payment payload, an API key, a session token.
70
+ * The 64-character floor keeps public identifiers readable: EVM addresses are
71
+ * 42 characters and base58 mint addresses at most 44.
72
+ */
73
+ const LONG_OPAQUE = /^[A-Za-z0-9_\-+/=.]{64,}$/;
74
+
75
+ /**
76
+ * Credential-shaped substrings inside otherwise useful diagnostic prose.
77
+ *
78
+ * IMPORTANT: every module-level /g regex in this block, plus
79
+ * INLINE_SCHEME_ALL above, is replacement-only. Use these only with
80
+ * String.prototype.replace — never RegExp.test() or RegExp.exec(), whose
81
+ * stateful lastIndex would make results depend on earlier trace calls. Add a
82
+ * separate non-/g matcher (as INLINE_SCHEME does) if matching is ever needed.
83
+ */
84
+ const EMBEDDED_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
85
+ const EMBEDDED_NAMED_SECRET = /\b([\w-]*(?:key|token|secret|signature|password|passphrase|mnemonic|seed|auth|credential|cookie|private)[\w-]*)\s*([=:])\s*([^\s,;]+)/gi;
86
+ const EMBEDDED_HEX_32_BYTES = /(?<![0-9a-fA-F])(?:0x)?[0-9a-fA-F]{64}(?![0-9a-fA-F])/g;
87
+ const EMBEDDED_JWT = /\bey[\w-]{8,}\.[\w-]{4,}\.[\w-]+\b/g;
88
+ // NOTE: This intentionally also hides public long identifiers in error prose
89
+ // (for example Solana transaction signatures and block hashes). See README
90
+ // "Debugging"; do not loosen the threshold without auditing credential leaks.
91
+ const EMBEDDED_LONG_OPAQUE = /(?<![A-Za-z0-9_\-+/=.])[A-Za-z0-9_\-+/=.]{64,}(?![A-Za-z0-9_\-+/=.])/g;
92
+
93
+ let forcedEnabled = null;
94
+ let writer = null;
95
+
96
+ /**
97
+ * Force tracing on or off for the process, overriding the environment.
98
+ * Pass undefined to hand control back to NANSEN_DEBUG.
99
+ */
100
+ export function setDebugEnabled(enabled) {
101
+ forcedEnabled = enabled === undefined ? null : Boolean(enabled);
102
+ }
103
+
104
+ /** Replace the stderr sink. Pass undefined to restore it. Tests only. */
105
+ export function setDebugWriter(fn) {
106
+ writer = typeof fn === 'function' ? fn : null;
107
+ }
108
+
109
+ function envEnabled(value) {
110
+ if (value === undefined || value === null) return false;
111
+ const normalized = String(value).trim().toLowerCase();
112
+ if (normalized === '') return false;
113
+ return !['0', 'false', 'no', 'off'].includes(normalized);
114
+ }
115
+
116
+ export function isDebugEnabled() {
117
+ if (forcedEnabled !== null) return forcedEnabled;
118
+ return envEnabled(process.env.NANSEN_DEBUG);
119
+ }
120
+
121
+ /** Cut a value to MAX_VALUE_LENGTH, marking that it was cut. */
122
+ export function truncate(value, max = MAX_VALUE_LENGTH) {
123
+ const text = String(value);
124
+ if (text.length <= max) return text;
125
+ return `${text.slice(0, max)}…(+${text.length - max} more)`;
126
+ }
127
+
128
+ /** Whether a field, query parameter, or header name names a credential. */
129
+ export function isSecretName(name) {
130
+ return SECRET_NAME.test(String(name ?? ''));
131
+ }
132
+
133
+ /**
134
+ * Whether a value looks like a credential regardless of what it is called —
135
+ * a private key, a mnemonic, a JWT, an encoded payment payload.
136
+ */
137
+ export function looksLikeSecretValue(value) {
138
+ if (typeof value !== 'string') return false;
139
+ const text = value.trim();
140
+ if (text === '' || UUID.test(text)) return false;
141
+ return (
142
+ HEX_32_BYTES.test(text) ||
143
+ MNEMONIC.test(text) ||
144
+ JWT.test(text) ||
145
+ LONG_BASE58.test(text) ||
146
+ LONG_OPAQUE.test(text) ||
147
+ INLINE_SCHEME.test(text)
148
+ );
149
+ }
150
+
151
+ function redactString(value) {
152
+ // Delegate only when the whole value is a URL. URL-prefixed diagnostic
153
+ // prose must still pass through the embedded Bearer/JWT/secret scrubbers.
154
+ if (/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value)) return redactUrl(value);
155
+ // Drop inline credentials first, keeping the scheme label ("Bearer …") so
156
+ // the trace still says what kind of credential was in play. Doing this
157
+ // before the shape checks keeps the surrounding prose readable.
158
+ const neutralized = value
159
+ .replace(EMBEDDED_URL, match => redactUrl(match))
160
+ .replace(INLINE_SCHEME_ALL, (_match, kind) => `${kind} ${REDACTED}`)
161
+ .replace(EMBEDDED_NAMED_SECRET, (_match, name, separator) => `${name}${separator}${REDACTED}`)
162
+ .replace(EMBEDDED_HEX_32_BYTES, REDACTED)
163
+ .replace(EMBEDDED_JWT, REDACTED)
164
+ .replace(EMBEDDED_LONG_OPAQUE, REDACTED);
165
+ if (neutralized !== value) return truncate(neutralized);
166
+ return looksLikeSecretValue(neutralized) ? REDACTED : truncate(neutralized);
167
+ }
168
+
169
+ /**
170
+ * Redact a string, array, or (possibly nested) object for tracing.
171
+ * Values under a secret-looking key are replaced wholesale; every other value
172
+ * is still checked for credential-shaped content and truncated.
173
+ */
174
+ export function redact(value, seen = new WeakSet()) {
175
+ if (value === null || value === undefined) return value;
176
+ if (typeof value === 'string') return redactString(value);
177
+ if (typeof value === 'number' || typeof value === 'boolean') return value;
178
+ if (typeof value === 'bigint') return `${value}`;
179
+ if (ArrayBuffer.isView(value)) {
180
+ return `[${value.constructor?.name || 'TypedArray'} ${value.byteLength} bytes]`;
181
+ }
182
+ if (value instanceof ArrayBuffer) return `[ArrayBuffer ${value.byteLength} bytes]`;
183
+ if (Array.isArray(value)) return value.map((item) => redact(item, seen));
184
+ if (typeof value === 'object') {
185
+ if (seen.has(value)) return '[circular]';
186
+ seen.add(value);
187
+ const out = {};
188
+ for (const [key, item] of Object.entries(value)) {
189
+ out[key] = isSecretName(key) ? REDACTED : redact(item, seen);
190
+ }
191
+ return out;
192
+ }
193
+ return truncate(String(value));
194
+ }
195
+
196
+ /**
197
+ * Redact a URL: drop any userinfo and fragment, sanitize path segments, blank out query values
198
+ * whose parameter is credential-named, and blank out any remaining value that
199
+ * looks like a credential. Path segments that look credential-related are
200
+ * withheld because reset/session/payment credentials are often put there.
201
+ */
202
+ export function redactUrl(raw) {
203
+ const text = String(raw ?? '');
204
+ let url;
205
+ try {
206
+ url = new URL(text);
207
+ } catch {
208
+ // Not parseable (a relative path, or a malformed URL). Fall back to a
209
+ // textual pass over the query string so nothing leaks from the odd case.
210
+ const queryIndex = text.indexOf('?');
211
+ if (queryIndex === -1) return truncate(text);
212
+ const base = text.slice(0, queryIndex);
213
+ const query = text.slice(queryIndex + 1);
214
+ return truncate(`${base}?${redactQueryText(query)}`);
215
+ }
216
+
217
+ const parts = [];
218
+ for (const [key, value] of url.searchParams.entries()) {
219
+ const safe = isSecretName(key) || looksLikeSecretValue(value);
220
+ parts.push(`${encodeURIComponent(key)}=${safe ? REDACTED : encodeURIComponent(value)}`);
221
+ }
222
+
223
+ const credentials = url.username || url.password ? `${REDACTED}@` : '';
224
+ const query = parts.length ? `?${parts.join('&')}` : '';
225
+ const path = url.pathname.split('/').map((segment) => {
226
+ let decoded = segment;
227
+ try { decoded = decodeURIComponent(segment); } catch { /* keep raw text */ }
228
+ // Short path names describe API resources (`token-screener`, `auth`)
229
+ // rather than naming a value, so SECRET_NAME alone would hide the endpoint
230
+ // users need to diagnose. Long secret-named or credential-shaped dynamic
231
+ // segments still fail closed.
232
+ return looksLikeSecretValue(decoded) || (decoded.length >= 32 && isSecretName(decoded))
233
+ ? REDACTED
234
+ : segment;
235
+ }).join('/');
236
+ return truncate(`${url.protocol}//${credentials}${url.host}${path}${query}`);
237
+ }
238
+
239
+ function redactQueryText(query) {
240
+ return query
241
+ .split('&')
242
+ .map((pair) => {
243
+ const index = pair.indexOf('=');
244
+ if (index === -1) return pair;
245
+ const key = pair.slice(0, index);
246
+ const value = pair.slice(index + 1);
247
+ let decoded = value;
248
+ try { decoded = decodeURIComponent(value); } catch { /* keep malformed encoding readable */ }
249
+ if (isSecretName(key)) return `${key}=${REDACTED}`;
250
+ const safe = redactString(decoded);
251
+ return `${key}=${safe === decoded ? value : safe}`;
252
+ })
253
+ .join('&');
254
+ }
255
+
256
+ /**
257
+ * Redact a header bag (plain object, Map, or fetch Headers) down to names
258
+ * only. Header values are never traced: even the innocuous ones carry nothing
259
+ * worth the risk of a rule that misses one. Production traces currently omit
260
+ * headers entirely; this is exported as the mandatory boundary if a future
261
+ * trace event ever includes header names.
262
+ */
263
+ export function redactHeaders(headers) {
264
+ const entries = typeof headers?.entries === 'function' ? [...headers.entries()] : Object.entries(headers ?? {});
265
+ const out = {};
266
+ for (const [name] of entries) out[name] = REDACTED;
267
+ return out;
268
+ }
269
+
270
+ function formatValue(key, value) {
271
+ const safe = key === 'url' ? redactUrl(value) : redact(value);
272
+ const text = typeof safe === 'object' ? JSON.stringify(safe) : String(safe);
273
+ const bounded = truncate(text);
274
+ return /[\s"]/.test(bounded) ? JSON.stringify(bounded) : bounded;
275
+ }
276
+
277
+ function write(line) {
278
+ if (writer) writer(line);
279
+ else process.stderr.write(line);
280
+ }
281
+
282
+ /**
283
+ * Emit one trace line. No-op unless tracing is enabled.
284
+ * Fields are rendered as `key=value`, in the order given, with null and
285
+ * undefined fields dropped.
286
+ */
287
+ export function trace(event, fields = {}) {
288
+ if (!isDebugEnabled()) return;
289
+ const parts = [`[nansen:debug] ${event}`];
290
+ for (const [key, value] of Object.entries(fields)) {
291
+ if (value === undefined || value === null) continue;
292
+ parts.push(`${key}=${formatValue(key, value)}`);
293
+ }
294
+ write(`${parts.join(' ')}\n`);
295
+ }
296
+
297
+ /** An HTTP request is about to go out. */
298
+ export function traceRequest({ method, url, attempt, maxAttempts, payment }) {
299
+ trace('http.request', {
300
+ method,
301
+ url,
302
+ attempt: maxAttempts ? `${attempt}/${maxAttempts}` : attempt,
303
+ payment,
304
+ });
305
+ }
306
+
307
+ /**
308
+ * Response headers arrived. `duration_ms` is time from attempt start until
309
+ * fetch resolves with headers (time to first byte / TTFB); it deliberately
310
+ * excludes downloading and parsing the response body.
311
+ */
312
+ export function traceResponse({ method, url, status, durationMs, requestId, attempt, payment }) {
313
+ trace('http.response', {
314
+ method,
315
+ url,
316
+ status,
317
+ duration_ms: durationMs,
318
+ request_id: requestId,
319
+ attempt,
320
+ payment,
321
+ });
322
+ }
323
+
324
+ /**
325
+ * The request never produced response headers. `duration_ms` is elapsed time
326
+ * from attempt start until the transport failure.
327
+ */
328
+ export function traceError({ method, url, durationMs, attempt, error }) {
329
+ trace('http.error', { method, url, duration_ms: durationMs, attempt, error });
330
+ }
331
+
332
+ /** A retry was decided on: which attempt failed, why, and how long we wait. */
333
+ export function traceRetry({ method, url, status, attempt, reason, delayMs, retryAfterMs }) {
334
+ trace('http.retry', {
335
+ method,
336
+ url,
337
+ status,
338
+ attempt,
339
+ reason,
340
+ delay_ms: delayMs === undefined || delayMs === null ? null : Math.round(delayMs),
341
+ retry_after_ms: retryAfterMs,
342
+ });
343
+ }
344
+
345
+ /** The response came from the local cache, so no request was made at all. */
346
+ export function traceCacheHit({ method, url }) {
347
+ trace('http.cache_hit', { method, url });
348
+ }