nansen-cli 1.46.0 → 2.0.1
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/CHANGELOG.md +122 -0
- package/README.md +157 -14
- package/docs/browser-login.md +123 -0
- package/package.json +11 -2
- package/scripts/postinstall.js +35 -30
- package/skills/nansen-agent-guide/SKILL.md +13 -2
- package/skills/nansen-alerts-webhook-listener/SKILL.md +5 -2
- package/skills/nansen-dca-tracker/SKILL.md +10 -2
- package/skills/nansen-defi-positions/SKILL.md +5 -2
- package/skills/nansen-exit-signals/SKILL.md +10 -2
- package/skills/nansen-fund-tracker/SKILL.md +10 -2
- package/skills/nansen-general-search/SKILL.md +10 -2
- package/skills/nansen-holder-analysis/SKILL.md +10 -2
- package/skills/nansen-limit-orders/SKILL.md +6 -3
- package/skills/nansen-perp-screener/SKILL.md +10 -2
- package/skills/nansen-perp-trader-profile/SKILL.md +10 -2
- package/skills/nansen-polymarket-deep-dive/SKILL.md +10 -2
- package/skills/nansen-polymarket-insider-scan/SKILL.md +10 -2
- package/skills/nansen-polymarket-trader-profile/SKILL.md +10 -2
- package/skills/nansen-portfolio-tracker/SKILL.md +10 -2
- package/skills/nansen-prediction-markets/SKILL.md +10 -2
- package/skills/nansen-sm-cross-chain-flows/SKILL.md +10 -2
- package/skills/nansen-smart-alerts/SKILL.md +9 -4
- package/skills/nansen-smart-money-alpha/SKILL.md +10 -2
- package/skills/nansen-smart-money-tracker/SKILL.md +10 -2
- package/skills/nansen-smart-money-trend/SKILL.md +10 -2
- package/skills/nansen-token-research/SKILL.md +10 -2
- package/skills/nansen-token-screener/SKILL.md +14 -4
- package/skills/nansen-token-transfer-analysis/SKILL.md +10 -2
- package/skills/nansen-trading/SKILL.md +8 -2
- package/skills/nansen-wallet-batch/SKILL.md +10 -2
- package/skills/nansen-wallet-clustering/SKILL.md +10 -2
- package/skills/nansen-wallet-deep-dive/SKILL.md +10 -2
- package/skills/nansen-wallet-keychain-migration/SKILL.md +5 -2
- package/skills/nansen-wallet-manager/SKILL.md +11 -9
- package/skills/nansen-wallet-profiler/SKILL.md +10 -2
- package/skills/nansen-web-fetcher/SKILL.md +5 -2
- package/skills/nansen-web-searcher/SKILL.md +5 -2
- package/src/api.js +202 -104
- package/src/auth-browser.js +16 -0
- package/src/auth-credentials.js +73 -0
- package/src/auth-device.js +242 -0
- package/src/auth-key-input.js +46 -0
- package/src/auth-login.js +89 -0
- package/src/auth-state.js +487 -0
- package/src/auth-store-native.js +20 -0
- package/src/auth-store-worker.js +64 -0
- package/src/auth-store.js +140 -0
- package/src/auto-paginate.js +288 -0
- package/src/bridge.js +126 -21
- package/src/cache-inspect.js +345 -0
- package/src/cli.js +473 -199
- package/src/commands/agent.js +15 -7
- package/src/commands/completion.js +2 -15
- package/src/commands/mcp.js +20 -18
- package/src/cost-cache.js +16 -2
- package/src/debug.js +348 -0
- package/src/doctor.js +22 -45
- package/src/hl-action.js +41 -13
- package/src/limit-order.js +1 -1
- package/src/mcp-client-config.js +169 -0
- package/src/mcp-client-config.json +17 -0
- package/src/mcp-verify.js +6 -5
- package/src/perp.js +41 -0
- package/src/privy.js +12 -12
- package/src/response-meta.js +56 -1
- package/src/rpc-urls.js +9 -11
- package/src/schema.json +185 -8
- package/src/semver.js +23 -4
- package/src/swap-simulation.js +35 -30
- package/src/telemetry.js +20 -0
- package/src/trading.js +266 -29
- package/src/transfer.js +53 -6
- package/src/update-check.js +9 -1
- package/src/wallet.js +107 -17
- package/src/walletconnect-trading.js +24 -5
- package/src/x402-svm.js +123 -64
- package/src/x402.js +46 -14
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { spawn } from 'node:child_process';
|
|
2
|
+
import { randomBytes, createHash } from 'node:crypto';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { AuthError, authDirectory } from './auth-credentials.js';
|
|
6
|
+
|
|
7
|
+
export const CHUNK_BYTES = 2048;
|
|
8
|
+
export const MAX_BUNDLE_BYTES = 16384;
|
|
9
|
+
const digest = bytes => createHash('sha256').update(bytes).digest('hex');
|
|
10
|
+
const unavailable = () => new AuthError('AUTH_STORE_UNAVAILABLE', 'Secure credential storage is unavailable or locked. Unlock your OS credential store and retry nansen login. No file fallback is used.');
|
|
11
|
+
export function nativeStoreOperation(operation, account, bytes, { directory = authDirectory(), signal } = {}) {
|
|
12
|
+
signal?.throwIfAborted();
|
|
13
|
+
return new Promise((resolve, reject) => {
|
|
14
|
+
const child = spawn(process.execPath, [fileURLToPath(new URL('./auth-store-worker.js', import.meta.url))], {
|
|
15
|
+
stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true,
|
|
16
|
+
// Do not inherit debugging hooks or unrelated credentials into the helper.
|
|
17
|
+
env: Object.fromEntries(['PATH', 'HOME', 'USERPROFILE', 'SystemRoot', 'LOCALAPPDATA', 'APPDATA', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR'].filter(k => process.env[k] !== undefined).map(k => [k, process.env[k]])),
|
|
18
|
+
});
|
|
19
|
+
let output = '';
|
|
20
|
+
let ready = false, result;
|
|
21
|
+
let failed = false;
|
|
22
|
+
let terminationDeadline;
|
|
23
|
+
const stop = () => {
|
|
24
|
+
failed = true;
|
|
25
|
+
try { child.kill('SIGKILL'); } catch { /* retain exclusion until OS termination */ }
|
|
26
|
+
terminationDeadline ??= setTimeout(() => {
|
|
27
|
+
// Never turn an unobserved termination into cleanup success. The child
|
|
28
|
+
// still owns its gate; recovery must retain the journal on contention.
|
|
29
|
+
child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy();
|
|
30
|
+
child.unref(); signal?.removeEventListener('abort', stop); reject(unavailable());
|
|
31
|
+
}, 1000);
|
|
32
|
+
};
|
|
33
|
+
const timer = setTimeout(stop, 10000);
|
|
34
|
+
signal?.addEventListener('abort', stop, { once: true });
|
|
35
|
+
if (signal?.aborted) stop();
|
|
36
|
+
child.stdout.on('data', chunk => {
|
|
37
|
+
if (failed) return;
|
|
38
|
+
output += chunk;
|
|
39
|
+
if (output.length > 40000) { stop(); return; }
|
|
40
|
+
let end;
|
|
41
|
+
while ((end = output.indexOf('\n')) !== -1) {
|
|
42
|
+
const line = output.slice(0, end); output = output.slice(end + 1);
|
|
43
|
+
try {
|
|
44
|
+
const message = JSON.parse(line);
|
|
45
|
+
if (!ready && message.ready === true) {
|
|
46
|
+
ready = true;
|
|
47
|
+
// The child already holds execution/cleanup exclusion. Keep the
|
|
48
|
+
// pipe open as a parent-lifetime signal; never send secrets early.
|
|
49
|
+
child.stdin.write(JSON.stringify({ operation, account, ...(bytes && { data: Buffer.from(bytes).toString('base64') }) }) + '\n');
|
|
50
|
+
} else if (ready && !result && (Object.hasOwn(message, 'value') || message.error === 'BINDING_MISSING')) result = message;
|
|
51
|
+
else throw new Error();
|
|
52
|
+
} catch { stop(); }
|
|
53
|
+
}
|
|
54
|
+
});
|
|
55
|
+
child.stderr.resume();
|
|
56
|
+
child.stdin.on('error', () => {});
|
|
57
|
+
child.on('error', () => { failed = true; });
|
|
58
|
+
// Success requires actual close; an unobserved kill is a bounded failure.
|
|
59
|
+
child.on('close', code => {
|
|
60
|
+
clearTimeout(timer); clearTimeout(terminationDeadline);
|
|
61
|
+
signal?.removeEventListener('abort', stop);
|
|
62
|
+
try {
|
|
63
|
+
if (failed || code !== 0 || !ready || !result || output) throw new Error();
|
|
64
|
+
if (result.error === 'BINDING_MISSING') {
|
|
65
|
+
reject(new AuthError('AUTH_STORE_UNAVAILABLE', 'The native credential-store binding could not load. Reinstall nansen-cli with optional dependencies enabled on a supported OS and architecture. See nansen doctor --offline and the browser-login platform guide.'));
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
resolve(operation === 'get' && result.value !== null ? Buffer.from(result.value, 'base64') : result.value);
|
|
69
|
+
} catch { reject(unavailable()); }
|
|
70
|
+
});
|
|
71
|
+
child.stdin.write(JSON.stringify({ directory: path.resolve(directory) }) + '\n');
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
export function createAuthStore({ directory, operation = (op, account, bytes, options) => nativeStoreOperation(op, account, bytes, { directory, ...options }), barrier = async () => {} } = {}) {
|
|
75
|
+
const name = (generation, suffix) => {
|
|
76
|
+
if (!/^[a-f0-9-]{36}$/.test(generation)) throw unavailable();
|
|
77
|
+
return `${generation}.${suffix}`;
|
|
78
|
+
};
|
|
79
|
+
async function invoke(op, account, bytes, options) {
|
|
80
|
+
options?.signal?.throwIfAborted();
|
|
81
|
+
const result = await operation(op, account, bytes, options);
|
|
82
|
+
options?.signal?.throwIfAborted();
|
|
83
|
+
return result;
|
|
84
|
+
}
|
|
85
|
+
return {
|
|
86
|
+
async preflight(generation, options) {
|
|
87
|
+
const account = name(generation, 'probe');
|
|
88
|
+
const bytes = randomBytes(CHUNK_BYTES);
|
|
89
|
+
try {
|
|
90
|
+
await invoke('set', account, bytes, options);
|
|
91
|
+
const actual = await invoke('get', account, undefined, options);
|
|
92
|
+
if (!actual || !bytes.equals(actual)) throw unavailable();
|
|
93
|
+
} finally {
|
|
94
|
+
await invoke('delete', account, undefined, options);
|
|
95
|
+
}
|
|
96
|
+
if (await invoke('get', account, undefined, options) !== null) throw unavailable();
|
|
97
|
+
},
|
|
98
|
+
async write(generation, bundle, options) {
|
|
99
|
+
const bytes = Buffer.from(JSON.stringify({ ...bundle, version: 1, generation }));
|
|
100
|
+
if (bytes.length > MAX_BUNDLE_BYTES) throw new AuthError('AUTH_BUNDLE_TOO_LARGE', 'The issued session exceeds the 16 KiB secure-storage limit. The previous credential is unchanged.');
|
|
101
|
+
const count = Math.ceil(bytes.length / CHUNK_BYTES);
|
|
102
|
+
for (let i = 0; i < count; i++) {
|
|
103
|
+
await invoke('set', name(generation, i), bytes.subarray(i * CHUNK_BYTES, (i + 1) * CHUNK_BYTES), options);
|
|
104
|
+
await barrier(`chunk-${i}`);
|
|
105
|
+
}
|
|
106
|
+
await invoke('set', name(generation, 'manifest'), Buffer.from(JSON.stringify({ version: 1, count, bytes: bytes.length, digest: digest(bytes) })), options);
|
|
107
|
+
await barrier('manifest');
|
|
108
|
+
const loaded = await this.read(generation, options);
|
|
109
|
+
if (JSON.stringify(loaded) !== bytes.toString()) throw unavailable();
|
|
110
|
+
},
|
|
111
|
+
async read(generation, options) {
|
|
112
|
+
const manifest = await invoke('get', name(generation, 'manifest'), undefined, options);
|
|
113
|
+
if (!manifest) throw Object.assign(unavailable(), { missing: true });
|
|
114
|
+
try {
|
|
115
|
+
const m = JSON.parse(manifest.toString());
|
|
116
|
+
if (m.version !== 1 || !Number.isInteger(m.count) || m.count < 1 || m.count > 8 || !Number.isInteger(m.bytes) || m.bytes < 1 || m.bytes > MAX_BUNDLE_BYTES || Math.ceil(m.bytes / CHUNK_BYTES) !== m.count) throw new Error();
|
|
117
|
+
const chunks = [];
|
|
118
|
+
for (let i = 0; i < m.count; i++) {
|
|
119
|
+
const bytes = await invoke('get', name(generation, i), undefined, options);
|
|
120
|
+
if (!bytes) throw Object.assign(unavailable(), { missing: true });
|
|
121
|
+
if (bytes.length !== Math.min(CHUNK_BYTES, m.bytes - i * CHUNK_BYTES)) throw new Error();
|
|
122
|
+
chunks.push(bytes);
|
|
123
|
+
}
|
|
124
|
+
const bytes = Buffer.concat(chunks);
|
|
125
|
+
if (digest(bytes) !== m.digest) throw new Error();
|
|
126
|
+
const bundle = JSON.parse(bytes.toString());
|
|
127
|
+
if (bundle.version !== 1 || bundle.generation !== generation) throw new Error();
|
|
128
|
+
return bundle;
|
|
129
|
+
} catch (error) { if (error instanceof AuthError) throw error; throw unavailable(); }
|
|
130
|
+
},
|
|
131
|
+
async remove(generation, options) {
|
|
132
|
+
// Fixed bounded namespace, including interrupted writes without a manifest.
|
|
133
|
+
for (const suffix of ['probe', 'manifest', ...Array.from({ length: 8 }, (_, i) => i)]) {
|
|
134
|
+
const account = name(generation, suffix);
|
|
135
|
+
await invoke('delete', account, undefined, options);
|
|
136
|
+
if (await invoke('get', account, undefined, options) !== null) throw unavailable();
|
|
137
|
+
}
|
|
138
|
+
},
|
|
139
|
+
};
|
|
140
|
+
}
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Nansen CLI - transparent multi-page traversal (--paginate / --all)
|
|
3
|
+
*
|
|
4
|
+
* Every list command already sends `pagination: { page, per_page }` through
|
|
5
|
+
* NansenAPI.request(). Wrapping that one method walks the pages for all of
|
|
6
|
+
* them at once, so no handler needs to know about traversal. Non-list
|
|
7
|
+
* requests (no `pagination` key in the body) pass straight through.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { aggregatePaginatedResponseMeta } from './response-meta.js';
|
|
11
|
+
import { ErrorCode, NansenError, RESPONSE_META } from './api.js';
|
|
12
|
+
|
|
13
|
+
export const DEFAULT_MAX_PAGES = 10;
|
|
14
|
+
// Rows and their serialized de-duplication keys stay resident until traversal
|
|
15
|
+
// completes. Keep an explicit ceiling so a typo cannot request effectively
|
|
16
|
+
// unbounded memory and billed API work from a long-running agent.
|
|
17
|
+
export const MAX_PAGES_LIMIT = 1000;
|
|
18
|
+
|
|
19
|
+
function hasObjectRows(rows) {
|
|
20
|
+
return rows.every(row => row !== null && typeof row === 'object' && !Array.isArray(row));
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// Shared by collectPages and cli.js's formatTable/formatCsv/formatStream so
|
|
24
|
+
// pagination and output formatting recognise the same row shapes.
|
|
25
|
+
export function locateRows(page, { descriptive = false, descriptiveKey, allowEmptyDescriptive = false } = {}) {
|
|
26
|
+
if (page?.success === false) return null;
|
|
27
|
+
if (descriptiveKey) {
|
|
28
|
+
const rows = page?.[descriptiveKey];
|
|
29
|
+
if (!Array.isArray(rows) || !hasObjectRows(rows)) return null;
|
|
30
|
+
return { rows, key: descriptiveKey, rebuild: mergedRows => ({ ...page, [descriptiveKey]: mergedRows }) };
|
|
31
|
+
}
|
|
32
|
+
if (Array.isArray(page) && hasObjectRows(page)) return { rows: page, rebuild: rows => ({ data: rows }) };
|
|
33
|
+
if (Array.isArray(page?.data) && hasObjectRows(page.data)) return { rows: page.data, rebuild: rows => ({ ...page, data: rows }) };
|
|
34
|
+
if (Array.isArray(page?.results) && hasObjectRows(page.results)) return { rows: page.results, rebuild: rows => ({ ...page, results: rows }) };
|
|
35
|
+
if (Array.isArray(page?.data?.data) && hasObjectRows(page.data.data)) {
|
|
36
|
+
return {
|
|
37
|
+
rows: page.data.data,
|
|
38
|
+
rebuild: rows => {
|
|
39
|
+
const data = { ...page.data, data: rows };
|
|
40
|
+
// The traversal summary is canonical at the top level. Keeping the
|
|
41
|
+
// first page's nested pagination would expose stale next-page state.
|
|
42
|
+
delete data.pagination;
|
|
43
|
+
return { ...page, data };
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
if (Array.isArray(page?.data?.results) && hasObjectRows(page.data.results)) {
|
|
48
|
+
return {
|
|
49
|
+
rows: page.data.results,
|
|
50
|
+
rebuild: rows => {
|
|
51
|
+
const data = { ...page.data, results: rows };
|
|
52
|
+
delete data.pagination;
|
|
53
|
+
return { ...page, data };
|
|
54
|
+
},
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Older endpoints use a descriptive top-level key (`trades`, `holdings`,
|
|
59
|
+
// `balances`, etc.) rather than `data`. Only a populated array of objects
|
|
60
|
+
// can identify rows here. Empty or primitive arrays may be envelope fields.
|
|
61
|
+
if (descriptive && page && typeof page === 'object') {
|
|
62
|
+
const fields = Object.entries(page).filter(([key]) => key !== 'pagination' && key !== 'success');
|
|
63
|
+
const arrays = fields.filter(([, value]) => Array.isArray(value) && value.length > 0 && hasObjectRows(value));
|
|
64
|
+
// Pagination can recognize an empty first page only when the array is
|
|
65
|
+
// the entire payload apart from status and pagination metadata.
|
|
66
|
+
const emptyOnly = allowEmptyDescriptive && fields.length === 1
|
|
67
|
+
&& Array.isArray(fields[0][1]) && fields[0][1].length === 0;
|
|
68
|
+
if (arrays.length === 1 || (arrays.length === 0 && emptyOnly)) {
|
|
69
|
+
const [key, rows] = arrays[0] || fields[0];
|
|
70
|
+
return { rows, key, rebuild: mergedRows => ({ ...page, [key]: mergedRows }) };
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
return null;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function isPlainObject(value) {
|
|
77
|
+
if (value === null || typeof value !== 'object') return false;
|
|
78
|
+
const prototype = Object.getPrototypeOf(value);
|
|
79
|
+
return prototype === Object.prototype || prototype === null;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function locatePagination(page) {
|
|
83
|
+
if (isPlainObject(page?.pagination)) return page.pagination;
|
|
84
|
+
if (isPlainObject(page?.data?.pagination)) return page.data.pagination;
|
|
85
|
+
return null;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function numericMetadata(value) {
|
|
89
|
+
if (value === null || value === undefined || value === '') return NaN;
|
|
90
|
+
return Number(value);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
function failedPageError(response, page) {
|
|
94
|
+
const nested = response?.error && typeof response.error === 'object'
|
|
95
|
+
? response.error
|
|
96
|
+
: null;
|
|
97
|
+
const message = typeof response?.error === 'string'
|
|
98
|
+
? response.error
|
|
99
|
+
: nested?.message || response?.message || `Pagination request failed on page ${page}`;
|
|
100
|
+
const code = response?.code || nested?.code || ErrorCode.UNKNOWN;
|
|
101
|
+
const status = response?.status ?? nested?.status ?? null;
|
|
102
|
+
const details = response?.details ?? nested?.details ?? response?.data ?? null;
|
|
103
|
+
return new NansenError(message, code, status, details);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function canonicalRowKey(value) {
|
|
107
|
+
// TODO: Consider a streaming hash only if bounded MAX_PAGES traversals show
|
|
108
|
+
// material memory pressure; canonical strings keep identity deterministic.
|
|
109
|
+
if (value === null) return 'null';
|
|
110
|
+
if (Array.isArray(value)) return `array:[${value.map(canonicalRowKey).join(',')}]`;
|
|
111
|
+
if (isPlainObject(value)) {
|
|
112
|
+
return `object:{${Object.keys(value).sort().map(key => (
|
|
113
|
+
`${JSON.stringify(key)}:${canonicalRowKey(value[key])}`
|
|
114
|
+
)).join(',')}}`;
|
|
115
|
+
}
|
|
116
|
+
if (typeof value === 'bigint') return `bigint:${value.toString()}`;
|
|
117
|
+
if (typeof value === 'number' && Object.is(value, -0)) return 'number:-0';
|
|
118
|
+
return `${typeof value}:${JSON.stringify(value)}`;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Fetch pages starting at `pagination.page` (default 1) until one of:
|
|
123
|
+
* - a page is empty or shorter than the page size (last page),
|
|
124
|
+
* - the server's pagination metadata says the traversal is complete,
|
|
125
|
+
* - a page adds no new rows (server ignored `page` / repeated cursor),
|
|
126
|
+
* - `maxPages` requests have been made (result marked `complete: false`).
|
|
127
|
+
* Rows are de-duplicated by canonical JSON identity (object keys are sorted
|
|
128
|
+
* recursively) so overlapping pages never repeat a semantically equal item.
|
|
129
|
+
* Returns the first page's envelope with the merged rows and a
|
|
130
|
+
* `pagination` summary: { page, pages_fetched, next_page, complete, ...server fields }.
|
|
131
|
+
* A first page with no recognisable rows array is returned unchanged.
|
|
132
|
+
*/
|
|
133
|
+
export async function collectPages(fetchPage, pagination, { maxPages = DEFAULT_MAX_PAGES } = {}) {
|
|
134
|
+
if (!Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > MAX_PAGES_LIMIT) {
|
|
135
|
+
throw new RangeError(`maxPages must be a safe integer between 1 and ${MAX_PAGES_LIMIT}`);
|
|
136
|
+
}
|
|
137
|
+
const startPage = Math.max(1, Number(pagination?.page) || 1);
|
|
138
|
+
// The page size is learned from the first page when --limit is absent;
|
|
139
|
+
// a short page then means "last page". Endpoints that ignore `page` return
|
|
140
|
+
// the same rows again and stop on the duplicate check instead.
|
|
141
|
+
let pageSize = pagination?.per_page;
|
|
142
|
+
const seen = new Set();
|
|
143
|
+
const rows = [];
|
|
144
|
+
let first;
|
|
145
|
+
let page = startPage;
|
|
146
|
+
let pagesFetched = 0;
|
|
147
|
+
let complete = false;
|
|
148
|
+
let firstPagination;
|
|
149
|
+
|
|
150
|
+
while (pagesFetched < maxPages) {
|
|
151
|
+
const res = await fetchPage({ ...pagination, page });
|
|
152
|
+
pagesFetched++;
|
|
153
|
+
if (res?.success === false) throw failedPageError(res, page);
|
|
154
|
+
const located = locateRows(res, {
|
|
155
|
+
descriptive: true,
|
|
156
|
+
descriptiveKey: first?.key,
|
|
157
|
+
allowEmptyDescriptive: first === undefined,
|
|
158
|
+
});
|
|
159
|
+
if (first === undefined) {
|
|
160
|
+
if (!located) return res;
|
|
161
|
+
first = located;
|
|
162
|
+
firstPagination = locatePagination(res);
|
|
163
|
+
}
|
|
164
|
+
// A later HTTP-200 response with an unexpected shape is not proof that
|
|
165
|
+
// traversal completed. Return the rows collected so far as incomplete and
|
|
166
|
+
// leave next_page on this page so callers can investigate or resume.
|
|
167
|
+
if (!located) { complete = false; break; }
|
|
168
|
+
|
|
169
|
+
let fresh = 0;
|
|
170
|
+
for (const row of located.rows) {
|
|
171
|
+
const key = canonicalRowKey(row);
|
|
172
|
+
if (seen.has(key)) continue;
|
|
173
|
+
seen.add(key);
|
|
174
|
+
rows.push(row);
|
|
175
|
+
fresh++;
|
|
176
|
+
}
|
|
177
|
+
// Page size is a property of the server response, so learn it from the raw
|
|
178
|
+
// row count rather than `fresh` (the de-duplicated count). An all-duplicate
|
|
179
|
+
// page still stops immediately via fresh === 0 below.
|
|
180
|
+
if (pageSize === undefined) pageSize = located.rows.length;
|
|
181
|
+
|
|
182
|
+
const serverPagination = locatePagination(res);
|
|
183
|
+
const totalPages = numericMetadata(serverPagination?.total_pages);
|
|
184
|
+
const totalRows = numericMetadata(serverPagination?.total);
|
|
185
|
+
const serverPageSize = numericMetadata(serverPagination?.per_page);
|
|
186
|
+
const effectivePageSize = Number.isInteger(serverPageSize) && serverPageSize > 0
|
|
187
|
+
? serverPageSize
|
|
188
|
+
: pageSize;
|
|
189
|
+
const serverSaysComplete = serverPagination?.is_last_page === true
|
|
190
|
+
|| serverPagination?.has_more === false
|
|
191
|
+
|| (Object.hasOwn(serverPagination || {}, 'next_page') && serverPagination.next_page === null)
|
|
192
|
+
// Pages are 1-based, so page * size is the current page's inclusive row
|
|
193
|
+
// endpoint. Trust the server total to avoid a separately billed empty
|
|
194
|
+
// probe; inconsistent total metadata can therefore cause an under-fetch.
|
|
195
|
+
|| (Number.isInteger(totalRows) && effectivePageSize > 0 && page * effectivePageSize >= totalRows);
|
|
196
|
+
const lastPage = located.rows.length === 0
|
|
197
|
+
|| fresh === 0
|
|
198
|
+
|| located.rows.length < effectivePageSize
|
|
199
|
+
|| serverSaysComplete
|
|
200
|
+
|| (Number.isInteger(totalPages) && page >= totalPages);
|
|
201
|
+
if (lastPage) { complete = true; break; }
|
|
202
|
+
page++;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
const merged = first.rebuild(rows);
|
|
206
|
+
merged.pagination = {
|
|
207
|
+
...(firstPagination || {}),
|
|
208
|
+
page: startPage,
|
|
209
|
+
pages_fetched: pagesFetched,
|
|
210
|
+
next_page: complete ? null : page,
|
|
211
|
+
complete,
|
|
212
|
+
};
|
|
213
|
+
return merged;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Make `api.request` traverse pages for list bodies. Returns the same
|
|
218
|
+
* instance. NansenAPI never calls request() recursively (x402 retries use
|
|
219
|
+
* fetch() directly), so the override cannot nest.
|
|
220
|
+
*/
|
|
221
|
+
export function enableAutoPagination(api, opts = {}) {
|
|
222
|
+
if (typeof api?.request !== 'function') return api;
|
|
223
|
+
const request = api.request.bind(api);
|
|
224
|
+
let traversalQueue = Promise.resolve();
|
|
225
|
+
api.request = async (endpoint, body = {}, options = {}) => {
|
|
226
|
+
if (options.autoPaginate === false
|
|
227
|
+
|| !body || typeof body !== 'object' || !('pagination' in body)) {
|
|
228
|
+
return request(endpoint, body, options);
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
const traverse = async () => {
|
|
232
|
+
// Only a new traversal supersedes the previous aggregate. Auxiliary
|
|
233
|
+
// non-list requests may run afterward and must not erase its credit scope.
|
|
234
|
+
api.paginatedResponseMeta = null;
|
|
235
|
+
api.paginatedEndpoint = null;
|
|
236
|
+
const pageMetadata = [];
|
|
237
|
+
const recordPageMetadata = (meta, cached = false) => {
|
|
238
|
+
pageMetadata.push({ cached, meta: cached ? null : meta });
|
|
239
|
+
};
|
|
240
|
+
try {
|
|
241
|
+
return await collectPages(async pagination => {
|
|
242
|
+
const previousMeta = api.lastResponseMeta;
|
|
243
|
+
try {
|
|
244
|
+
const pageResult = await request(endpoint, { ...body, pagination }, options);
|
|
245
|
+
// The payload belongs to this exact request, unlike the instance's
|
|
246
|
+
// last-* fields which concurrent non-list calls can overwrite.
|
|
247
|
+
const cached = pageResult?._meta?.fromCache === true
|
|
248
|
+
|| (api.responseMetadataOnPayload !== true && api.servedFromCache === true);
|
|
249
|
+
const payloadMeta = pageResult?.[RESPONSE_META];
|
|
250
|
+
const meta = payloadMeta ?? (
|
|
251
|
+
api.responseMetadataOnPayload === true ? null : api.lastResponseMeta
|
|
252
|
+
);
|
|
253
|
+
recordPageMetadata(meta, cached);
|
|
254
|
+
return pageResult;
|
|
255
|
+
} catch (error) {
|
|
256
|
+
const details = error?.details;
|
|
257
|
+
const errorMeta = details && typeof details === 'object'
|
|
258
|
+
? {
|
|
259
|
+
...(details.requestId && { requestId: details.requestId }),
|
|
260
|
+
...(details.credits && { credits: details.credits }),
|
|
261
|
+
...(details.rateLimit && { rateLimit: details.rateLimit }),
|
|
262
|
+
}
|
|
263
|
+
: null;
|
|
264
|
+
const hasErrorMeta = errorMeta && Object.keys(errorMeta).length > 0;
|
|
265
|
+
// A transport failure may leave the prior page's metadata in place;
|
|
266
|
+
// count the attempt, but only use shared state when the error itself
|
|
267
|
+
// carries no metadata and this request demonstrably replaced it.
|
|
268
|
+
recordPageMetadata(hasErrorMeta
|
|
269
|
+
? errorMeta
|
|
270
|
+
: (api.lastResponseMeta === previousMeta ? null : api.lastResponseMeta));
|
|
271
|
+
throw error;
|
|
272
|
+
}
|
|
273
|
+
}, body.pagination, opts);
|
|
274
|
+
} finally {
|
|
275
|
+
api.paginatedResponseMeta = aggregatePaginatedResponseMeta(pageMetadata);
|
|
276
|
+
api.paginatedEndpoint = endpoint;
|
|
277
|
+
}
|
|
278
|
+
};
|
|
279
|
+
|
|
280
|
+
// Shared instance metadata has one command-level slot. Serialize only
|
|
281
|
+
// traversals so two callers cannot interleave pages and overwrite it;
|
|
282
|
+
// ordinary and explicitly bypassed requests remain direct.
|
|
283
|
+
const pending = traversalQueue.then(traverse, traverse);
|
|
284
|
+
traversalQueue = pending.catch(() => {});
|
|
285
|
+
return pending;
|
|
286
|
+
};
|
|
287
|
+
return api;
|
|
288
|
+
}
|