nansen-cli 2.4.0 → 2.5.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.
package/src/api.js CHANGED
@@ -15,6 +15,7 @@ import { readResponseMeta, stringHeader } from './response-meta.js';
15
15
  import { trace, traceRequest, traceResponse, traceError, traceRetry, traceCacheHit } from './debug.js';
16
16
  import { appendPaymentRecord, newPaymentId, sanitizeRequestUrl } from './x402-audit.js';
17
17
  import { openLocalFile } from './local-file.js';
18
+ import { ENTRY_MAX_AGE_MS, isStaleTemp, pruneResponseCacheDir } from './response-cache-files.js';
18
19
 
19
20
  /**
20
21
  * Key for the credit/rate-limit metadata attached to a successful response.
@@ -423,9 +424,11 @@ function getCacheKey(endpoint, body, context = {}) {
423
424
  /**
424
425
  * Get cached response if valid
425
426
  */
426
- export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL, context = {}) {
427
+ export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL, context = {}, onHit = null) {
427
428
  const cacheKey = getCacheKey(endpoint, body, context);
428
429
  const cacheFile = path.join(CACHE_DIR, `${cacheKey}.json`);
430
+ // The sweep after a write keeps entries this process may still read.
431
+ if (Number.isFinite(ttlSeconds) && ttlSeconds > largestReadTtlSeconds) largestReadTtlSeconds = ttlSeconds;
429
432
 
430
433
  if (!fs.existsSync(cacheFile)) {
431
434
  return null;
@@ -458,6 +461,10 @@ export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL
458
461
  } else {
459
462
  result = { ...cached.data, _meta: meta };
460
463
  }
464
+ const warningMeta = typeof cached.warning === 'string' && cached.warning
465
+ ? { notices: { warning: cached.warning } } : null;
466
+ if (result !== null && typeof result === 'object' && warningMeta) result[RESPONSE_META] = warningMeta;
467
+ onHit?.(warningMeta);
461
468
  }
462
469
  } catch (error) {
463
470
  primaryError = error;
@@ -477,7 +484,7 @@ export function getCachedResponse(endpoint, body, ttlSeconds = DEFAULT_CACHE_TTL
477
484
  /**
478
485
  * Save response to cache
479
486
  */
480
- export function setCachedResponse(endpoint, body, data, context = {}) {
487
+ export function setCachedResponse(endpoint, body, data, context = {}, responseMeta = data?.[RESPONSE_META]) {
481
488
  if (!fs.existsSync(CACHE_DIR)) {
482
489
  fs.mkdirSync(CACHE_DIR, { mode: 0o700, recursive: true });
483
490
  }
@@ -488,6 +495,7 @@ export function setCachedResponse(endpoint, body, data, context = {}) {
488
495
  const cached = {
489
496
  timestamp: Date.now(),
490
497
  endpoint,
498
+ warning: responseMeta?.notices?.warning,
491
499
  data
492
500
  };
493
501
 
@@ -522,22 +530,58 @@ export function setCachedResponse(endpoint, body, data, context = {}) {
522
530
  try { fs.unlinkSync(tempFile); } catch { /* rename may already have committed */ }
523
531
  if (primaryError) throw primaryError;
524
532
  if (closeError) throw closeError;
533
+ sweepResponseCache(cacheFile);
534
+ }
535
+
536
+ // Sweep old entries and abandoned temp files after the first successful write
537
+ // in a process, then at most once per RESPONSE_CACHE_SWEEP_INTERVAL_MS so a
538
+ // long-running process keeps sweeping. Best effort: the response is already
539
+ // cached and a failed sweep must not fail the request. Ages are measured
540
+ // against the mtime of the entry just written rather than Date.now(), so every
541
+ // file is judged by the same clock (a network filesystem may stamp its own
542
+ // time) and the new entry itself is never older than the window. Entries this
543
+ // process may still read with a longer TTL are kept.
544
+ const RESPONSE_CACHE_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
545
+ let lastResponseCacheSweep;
546
+ let largestReadTtlSeconds = 0;
547
+ function sweepResponseCache(writtenFile) {
548
+ const now = Date.now();
549
+ if (lastResponseCacheSweep !== undefined && now - lastResponseCacheSweep < RESPONSE_CACHE_SWEEP_INTERVAL_MS) return;
550
+ lastResponseCacheSweep = now;
551
+ try {
552
+ const retentionMs = Math.max(ENTRY_MAX_AGE_MS, largestReadTtlSeconds * 1000);
553
+ pruneResponseCacheDir(CACHE_DIR, fs.lstatSync(writtenFile).mtimeMs, retentionMs);
554
+ } catch {
555
+ // The next process tries again.
556
+ }
525
557
  }
526
558
 
527
559
  /**
528
560
  * Clear all cached responses
529
561
  */
530
562
  export function clearCache() {
531
- if (fs.existsSync(CACHE_DIR)) {
532
- const files = fs.readdirSync(CACHE_DIR);
533
- for (const file of files) {
534
- if (file.endsWith('.json')) {
535
- fs.unlinkSync(path.join(CACHE_DIR, file));
563
+ // Like the sweep and `nansen cache clear`, never follow a symlinked cache
564
+ // directory: deletes stay inside the directory itself.
565
+ const dirStat = fs.lstatSync(CACHE_DIR, { throwIfNoEntry: false });
566
+ if (!dirStat?.isDirectory()) return 0;
567
+ const files = fs.readdirSync(CACHE_DIR);
568
+ const now = Date.now();
569
+ let removed = 0;
570
+ for (const file of files) {
571
+ const full = path.join(CACHE_DIR, file);
572
+ if (file.endsWith('.json')) {
573
+ fs.unlinkSync(full);
574
+ removed += 1;
575
+ } else {
576
+ // A temp file younger than this may belong to a write in progress.
577
+ const stat = fs.lstatSync(full, { throwIfNoEntry: false });
578
+ if (stat?.isFile() && isStaleTemp(file, stat, now)) {
579
+ fs.unlinkSync(full);
580
+ removed += 1;
536
581
  }
537
582
  }
538
- return files.length;
539
583
  }
540
- return 0;
584
+ return removed;
541
585
  }
542
586
 
543
587
  /**
@@ -1073,6 +1117,7 @@ export class NansenAPI {
1073
1117
  }
1074
1118
  const meta = readResponseMeta(paidResponse);
1075
1119
  this.lastResponseMeta = meta;
1120
+ options.onResponseMeta?.(meta, false);
1076
1121
  if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
1077
1122
  return data;
1078
1123
  }
@@ -1107,8 +1152,18 @@ export class NansenAPI {
1107
1152
 
1108
1153
  let cacheContext = credentialContext();
1109
1154
  if (useCache && cacheContext) {
1110
- const cached = getCachedResponse(endpoint, body, cacheTtl, cacheContext);
1111
- if (cached) {
1155
+ let hit = false;
1156
+ const cached = getCachedResponse(endpoint, body, cacheTtl, cacheContext, meta => {
1157
+ hit = true;
1158
+ options.onResponseMeta?.(meta, true);
1159
+ const warning = meta?.notices?.warning;
1160
+ if (warning) {
1161
+ const previous = this.lastResponseMeta;
1162
+ const combined = [...new Set([previous?.notices?.warning, warning].filter(Boolean))].join(', ');
1163
+ this.lastResponseMeta = { ...previous, notices: { ...previous?.notices, warning: combined } };
1164
+ }
1165
+ });
1166
+ if (hit) {
1112
1167
  this.servedFromCache = true;
1113
1168
  traceCacheHit({ method, url });
1114
1169
  return cached;
@@ -1211,10 +1266,13 @@ export class NansenAPI {
1211
1266
  lastError = error;
1212
1267
  continue;
1213
1268
  }
1269
+ options.onResponseMeta?.(meta, false);
1214
1270
  throw error;
1215
1271
  }
1216
1272
 
1217
1273
  if (!response.ok) {
1274
+ // A literal `null` body parses as JSON but has no fields to read.
1275
+ if (data == null) data = {};
1218
1276
  let message = data.message || data.error
1219
1277
  || (typeof data.detail === 'string' ? data.detail : data.detail?.message)
1220
1278
  || `API error: ${response.status}`;
@@ -1444,6 +1502,7 @@ export class NansenAPI {
1444
1502
  continue;
1445
1503
  }
1446
1504
 
1505
+ options.onResponseMeta?.(meta, false);
1447
1506
  throw lastError;
1448
1507
  }
1449
1508
 
@@ -1452,18 +1511,14 @@ export class NansenAPI {
1452
1511
  data._meta = { ...(data._meta || {}), retriedAttempts: attempt };
1453
1512
  }
1454
1513
 
1455
- // Cache successful response
1456
- if (useCache && cacheContext) {
1457
- setCachedResponse(endpoint, body, data, cacheContext);
1458
- }
1459
-
1460
- // Attach after caching so the cache stores the payload alone — quota
1461
- // numbers are per-response and would be stale on a cache hit.
1462
- // Guarded: a response body can be a primitive, which cannot take a property.
1514
+ // Symbols do not serialize into the payload. The cache persists only the
1515
+ // durable warning separately; quota and request metadata remain live-only.
1463
1516
  const meta = readResponseMeta(response);
1464
1517
  this.lastResponseMeta = meta;
1465
- if (meta) {
1466
- if (data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
1518
+ options.onResponseMeta?.(meta, false);
1519
+ if (meta && data !== null && typeof data === 'object') data[RESPONSE_META] = meta;
1520
+ if (useCache && cacheContext) {
1521
+ setCachedResponse(endpoint, body, data, cacheContext, meta);
1467
1522
  }
1468
1523
 
1469
1524
  return data;
@@ -1693,7 +1748,7 @@ export class NansenAPI {
1693
1748
  const { address, chain = 'ethereum', orderBy, pagination } = params;
1694
1749
  if (address) requireValidAddress(address, chain);
1695
1750
  return this.request('/api/v1/profiler/address/related-wallets', {
1696
- address,
1751
+ wallet_address: address,
1697
1752
  chain,
1698
1753
  order_by: orderBy,
1699
1754
  pagination
@@ -1809,7 +1864,7 @@ export class NansenAPI {
1809
1864
  const { address, chain = 'ethereum', days = 30 } = params;
1810
1865
  if (address) requireValidAddress(address, chain);
1811
1866
  return this.request('/api/v1/profiler/address/pnl-summary', {
1812
- address,
1867
+ wallet_address: address,
1813
1868
  chain,
1814
1869
  date: buildDateRange(days)
1815
1870
  });
@@ -2158,12 +2213,11 @@ export class NansenAPI {
2158
2213
  async pmMarketScreener(params = {}) {
2159
2214
  const { orderBy, sortBy = 'volume_24hr', query = '', status = '', tags, minLiquidity, maxLiquidity, maxUniqueTraders24h, minVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, minPrice, maxPrice, pagination } = params;
2160
2215
  const body = {
2161
- sort_by: sortBy,
2216
+ order_by: orderBy || [{ field: sortBy, direction: 'DESC' }],
2162
2217
  query,
2163
2218
  status,
2164
2219
  pagination
2165
2220
  };
2166
- if (orderBy) body.order_by = orderBy;
2167
2221
  if (tags && tags.length) body.tags = tags;
2168
2222
  if (minLiquidity != null) body.min_liquidity = minLiquidity;
2169
2223
  if (maxLiquidity != null) body.max_liquidity = maxLiquidity;
@@ -2182,12 +2236,11 @@ export class NansenAPI {
2182
2236
  async pmEventScreener(params = {}) {
2183
2237
  const { orderBy, sortBy = 'volume_24hr', query = '', status = '', tags, minLiquidity, maxLiquidity, maxUniqueTraders24h, minVolume24hr, negRisk, minOpenInterest, maxOpenInterest, endDateBefore, endDateAfter, pagination } = params;
2184
2238
  const body = {
2185
- sort_by: sortBy,
2239
+ order_by: orderBy || [{ field: sortBy, direction: 'DESC' }],
2186
2240
  query,
2187
2241
  status,
2188
2242
  pagination
2189
2243
  };
2190
- if (orderBy) body.order_by = orderBy;
2191
2244
  if (tags && tags.length) body.tags = tags;
2192
2245
  if (minLiquidity != null) body.min_liquidity = minLiquidity;
2193
2246
  if (maxLiquidity != null) body.max_liquidity = maxLiquidity;
@@ -6,12 +6,17 @@ function inputError(message, code) {
6
6
  return new CommandError(message, code, { error: code, message });
7
7
  }
8
8
 
9
- // Explicit stdin input keeps secrets out of command arguments and shell history.
10
- export async function readApiKeyInput(input, isTTY = input.isTTY, { timeoutMs = 30_000 } = {}) {
11
- if (isTTY) throw inputError('Pipe an API key or redirect a key file into --api-key-stdin. For a hidden terminal prompt, use nansen login --human.', 'NOT_A_PIPE');
9
+ /**
10
+ * Read a single secret from a pipe or redirected file. Shared by the API key
11
+ * (`--api-key-stdin`) and the alert webhook signing secret
12
+ * (`--webhook-secret-stdin`). `errors` maps each failure to the
13
+ * CommandError to throw; none of them may quote the input.
14
+ */
15
+ async function readSecretBytes(input, isTTY, { timeoutMs, maxBytes, errors }) {
16
+ if (isTTY) throw errors.notAPipe();
12
17
  const chunks = [];
13
18
  let size = 0;
14
- const timeoutError = inputError('Timed out reading the API key from stdin. Close the pipe after writing a single key, or redirect a key file.', 'API_KEY_INPUT_TIMEOUT');
19
+ const timeoutError = errors.timeout();
15
20
  let timer;
16
21
  let iterator;
17
22
  let exhausted = false;
@@ -23,12 +28,12 @@ export async function readApiKeyInput(input, isTTY = input.isTTY, { timeoutMs =
23
28
  if (done) { exhausted = true; break; }
24
29
  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
25
30
  size += bytes.length;
26
- if (size > MAX_KEY_BYTES) break;
31
+ if (size > maxBytes) break;
27
32
  chunks.push(bytes);
28
33
  }
29
34
  } catch (error) {
30
35
  if (error === timeoutError) throw timeoutError;
31
- throw inputError('Could not read the API key from stdin. Check the input and try again.', 'API_KEY_INPUT_FAILED');
36
+ throw errors.failed();
32
37
  } finally {
33
38
  clearTimeout(timer);
34
39
  try { input.destroy?.(); } catch { /* Never expose input cleanup errors. */ }
@@ -38,9 +43,52 @@ export async function readApiKeyInput(input, isTTY = input.isTTY, { timeoutMs =
38
43
  try { Promise.resolve(iterator?.return?.()).catch(() => {}); } catch { /* Preserve the sanitized input error. */ }
39
44
  }
40
45
  }
41
- if (size > MAX_KEY_BYTES) throw inputError('API key input exceeds 4096 bytes. Provide a single API key.', 'INVALID_PARAMS');
42
- const key = Buffer.concat(chunks).toString('utf8').trim();
46
+ if (size > maxBytes) throw errors.tooLarge();
47
+ return Buffer.concat(chunks).toString('utf8');
48
+ }
49
+
50
+ export function hasControlChars(value) {
51
+ return /�/u.test(value) || [...value].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
52
+ }
53
+
54
+ // Explicit stdin input keeps secrets out of command arguments and shell history.
55
+ export async function readApiKeyInput(input, isTTY = input.isTTY, { timeoutMs = 30_000 } = {}) {
56
+ const raw = await readSecretBytes(input, isTTY, {
57
+ timeoutMs,
58
+ maxBytes: MAX_KEY_BYTES,
59
+ errors: {
60
+ notAPipe: () => inputError('Pipe an API key or redirect a key file into --api-key-stdin. For a hidden terminal prompt, use nansen login --human.', 'NOT_A_PIPE'),
61
+ timeout: () => inputError('Timed out reading the API key from stdin. Close the pipe after writing a single key, or redirect a key file.', 'API_KEY_INPUT_TIMEOUT'),
62
+ failed: () => inputError('Could not read the API key from stdin. Check the input and try again.', 'API_KEY_INPUT_FAILED'),
63
+ tooLarge: () => inputError('API key input exceeds 4096 bytes. Provide a single API key.', 'INVALID_PARAMS'),
64
+ },
65
+ });
66
+ const key = raw.trim();
43
67
  if (!key) throw inputError('No API key received on stdin. Pipe a single key or redirect a key file.', 'API_KEY_REQUIRED');
44
- if (/\s|\ufffd/u.test(key) || [...key].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) throw inputError('API key input must contain a single key without whitespace or control characters.', 'INVALID_PARAMS');
68
+ if (/\s/u.test(key) || hasControlChars(key)) throw inputError('API key input must contain a single key without whitespace or control characters.', 'INVALID_PARAMS');
45
69
  return key;
46
70
  }
71
+
72
+ /**
73
+ * Read an alert webhook signing secret from stdin (`--webhook-secret-stdin`).
74
+ * Surrounding whitespace (such as the newline `echo` adds) is removed, so the
75
+ * secret matches what a listener reads from a trimmed env var or file. Inner
76
+ * spaces are kept; line breaks and other control characters are rejected
77
+ * because they mean more than one value was piped.
78
+ */
79
+ export async function readWebhookSecretInput(input, isTTY = input?.isTTY, { timeoutMs = 30_000 } = {}) {
80
+ const raw = await readSecretBytes(input, isTTY, {
81
+ timeoutMs,
82
+ maxBytes: MAX_KEY_BYTES,
83
+ errors: {
84
+ notAPipe: () => inputError('--webhook-secret-stdin reads from a pipe or redirected file, not a terminal. Example: nansen alerts create ... --webhook-secret-stdin < secret.txt, or set NANSEN_WEBHOOK_SECRET.', 'NOT_A_PIPE'),
85
+ timeout: () => inputError('Timed out reading the webhook secret from stdin. Close the pipe after writing the secret, or redirect a file.', 'INVALID_PARAMS'),
86
+ failed: () => inputError('Could not read the webhook secret from stdin. Check the input and try again.', 'INVALID_PARAMS'),
87
+ tooLarge: () => inputError('Webhook secret input exceeds 4096 bytes. Provide a single secret.', 'INVALID_PARAMS'),
88
+ },
89
+ });
90
+ const secret = raw.trim();
91
+ if (!secret) throw inputError('No webhook secret received on stdin. Pipe the secret or redirect a file that contains it.', 'MISSING_PARAM');
92
+ if (hasControlChars(secret)) throw inputError('Webhook secret input must be a single line without control characters.', 'INVALID_PARAMS');
93
+ return secret;
94
+ }
@@ -213,6 +213,16 @@ export async function collectPages(fetchPage, pagination, { maxPages = DEFAULT_M
213
213
  return merged;
214
214
  }
215
215
 
216
+ /**
217
+ * The merged result reuses page 1's envelope, so its `_meta.fromCache` and
218
+ * `cacheAge` describe page 1 only. Keep them only when every page was cached.
219
+ */
220
+ function withMergedCacheMarker(result, pages) {
221
+ if (result?._meta?.fromCache !== true || pages.every(page => page.cached)) return result;
222
+ const { fromCache: _fromCache, cacheAge: _cacheAge, ...meta } = result._meta;
223
+ return { ...result, _meta: meta };
224
+ }
225
+
216
226
  /**
217
227
  * Make `api.request` traverse pages for list bodies. Returns the same
218
228
  * instance. NansenAPI never calls request() recursively (x402 retries use
@@ -235,19 +245,26 @@ export function enableAutoPagination(api, opts = {}) {
235
245
  api.paginatedEndpoint = null;
236
246
  const pageMetadata = [];
237
247
  const recordPageMetadata = (meta, cached = false) => {
238
- pageMetadata.push({ cached, meta: cached ? null : meta });
248
+ pageMetadata.push({ cached, meta });
239
249
  };
240
250
  try {
241
- return await collectPages(async pagination => {
251
+ const result = await collectPages(async pagination => {
242
252
  const previousMeta = api.lastResponseMeta;
253
+ let requestMetadata;
243
254
  try {
244
- const pageResult = await request(endpoint, { ...body, pagination }, options);
255
+ const pageResult = await request(endpoint, { ...body, pagination }, {
256
+ ...options,
257
+ onResponseMeta(meta, cached) {
258
+ requestMetadata = { meta, cached };
259
+ options.onResponseMeta?.(meta, cached);
260
+ },
261
+ });
245
262
  // The payload belongs to this exact request, unlike the instance's
246
263
  // last-* fields which concurrent non-list calls can overwrite.
247
- const cached = pageResult?._meta?.fromCache === true
248
- || (api.responseMetadataOnPayload !== true && api.servedFromCache === true);
264
+ const cached = requestMetadata?.cached ?? (pageResult?._meta?.fromCache === true
265
+ || (api.responseMetadataOnPayload !== true && api.servedFromCache === true));
249
266
  const payloadMeta = pageResult?.[RESPONSE_META];
250
- const meta = payloadMeta ?? (
267
+ const meta = requestMetadata ? requestMetadata.meta : payloadMeta ?? (
251
268
  api.responseMetadataOnPayload === true ? null : api.lastResponseMeta
252
269
  );
253
270
  recordPageMetadata(meta, cached);
@@ -265,12 +282,13 @@ export function enableAutoPagination(api, opts = {}) {
265
282
  // A transport failure may leave the prior page's metadata in place;
266
283
  // count the attempt, but only use shared state when the error itself
267
284
  // carries no metadata and this request demonstrably replaced it.
268
- recordPageMetadata(hasErrorMeta
285
+ recordPageMetadata(requestMetadata ? requestMetadata.meta : hasErrorMeta
269
286
  ? errorMeta
270
287
  : (api.lastResponseMeta === previousMeta ? null : api.lastResponseMeta));
271
288
  throw error;
272
289
  }
273
290
  }, body.pagination, opts);
291
+ return withMergedCacheMarker(result, pageMetadata);
274
292
  } finally {
275
293
  api.paginatedResponseMeta = aggregatePaginatedResponseMeta(pageMetadata);
276
294
  api.paginatedEndpoint = endpoint;
@@ -12,8 +12,9 @@
12
12
  * and they are not printed either.
13
13
  *
14
14
  * Safety: clearing only ever unlinks regular files at the three paths above —
15
- * `.json` entries directly inside the response cache directory, and the two
16
- * named files. Directories and symlinks are skipped rather than followed, so a
15
+ * `.json` entries directly inside the response cache directory (plus temp
16
+ * files that a killed write left behind, once they are 10 minutes old), and
17
+ * the two named files. Directories and symlinks are skipped rather than followed, so a
17
18
  * clear cannot reach outside the cache it was pointed at. Everything else under
18
19
  * ~/.nansen (config.json, wallets/, quotes/, telemetry-id, saved auth) is never
19
20
  * read or deleted by the inspector. CLI startup loads config separately.
@@ -22,13 +23,13 @@
22
23
  import fs from 'fs';
23
24
  import path from 'path';
24
25
  import { openLocalFile } from './local-file.js';
26
+ import { RESPONSE_ENTRY, RESPONSE_TEMP, isStaleTemp } from './response-cache-files.js';
25
27
 
26
28
  import { getCacheDir, getConfigDir, DEFAULT_CACHE_TTL, NansenError, ErrorCode } from './api.js';
27
29
  import { getCostMapFile, COST_MAP_TTL_MS } from './cost-cache.js';
28
30
  import { getUpdateCheckFile, UPDATE_CHECK_TTL_MS } from './update-check.js';
29
31
 
30
32
  const SECOND = 1000;
31
- const RESPONSE_ENTRY = /^[0-9a-f]{64}\.json$/;
32
33
 
33
34
  /** Cache names, in report order. */
34
35
  export const CACHE_NAMES = ['responses', 'cost-map', 'update-check'];
@@ -106,7 +107,7 @@ function readTimestamp(file, field) {
106
107
  }
107
108
  }
108
109
 
109
- function listDirEntries(dir, { readMetadata = false } = {}) {
110
+ function listDirEntries(dir, { readMetadata = false, includeStaleTemps = false } = {}) {
110
111
  let names;
111
112
  try {
112
113
  const dirStat = fs.lstatSync(dir);
@@ -123,16 +124,25 @@ function listDirEntries(dir, { readMetadata = false } = {}) {
123
124
  throw fsError('list', dir, error);
124
125
  }
125
126
  const entries = [];
127
+ const now = Date.now();
126
128
  for (const name of names) {
127
129
  // `name` comes from this directory's own listing, not from a caller. The
128
130
  // strict digest shape both identifies files written by api.js and prevents
129
131
  // path separators or traversal segments from reaching path.join(). The
130
132
  // lstat below then rejects a final-component symlink before any read/delete.
131
- if (!RESPONSE_ENTRY.test(name)) continue;
133
+ // A temp file is a write that never finished renaming onto its entry.
134
+ // Only stale ones are listed (for clearing), so a write in progress is
135
+ // never deleted, and they have no timestamp metadata to read.
136
+ const isTemp = includeStaleTemps && RESPONSE_TEMP.test(name);
137
+ if (!isTemp && !RESPONSE_ENTRY.test(name)) continue;
132
138
  const file = path.join(dir, name);
133
139
  try {
134
140
  const stat = fs.lstatSync(file);
135
141
  if (!stat.isFile()) continue;
142
+ if (isTemp) {
143
+ if (isStaleTemp(name, stat, now)) entries.push({ file, bytes: stat.size });
144
+ continue;
145
+ }
136
146
  const metadata = readMetadata ? readTimestamp(file, 'timestamp') : {};
137
147
  if (metadata.raced) continue;
138
148
  entries.push({ file, bytes: stat.size, ...metadata });
@@ -256,7 +266,7 @@ export function clearCaches(target) {
256
266
  if (!wanted.includes(ns.name)) continue;
257
267
  let entries = 0;
258
268
  let bytes = 0;
259
- for (const entry of listEntries(ns, { readMetadata: false })) {
269
+ for (const entry of listEntries(ns, { readMetadata: false, includeStaleTemps: true })) {
260
270
  try {
261
271
  fs.unlinkSync(entry.file);
262
272
  } catch (error) {