gangtise-openapi-cli 0.28.3 → 0.30.0

package/dist/src/core/args.js

@@ -247,29 +247,70 @@ export function localDateString(d) {
     const day = String(d.getDate()).padStart(2, "0");
     return `${d.getFullYear()}-${month}-${day}`;
 }
-// Parse repeatable `--indicator-param "code:key=value"` specs into the nested
-// indicatorParamList the EDE cross-section / time-series endpoints expect.
-// Multiple specs for the same code accumulate into one group, first-seen order.
-export function parseIndicatorParams(specs) {
-    if (specs.length === 0)
-        return undefined;
+// Parse repeatable `"<lhs>:key=value"` specs into per-lhs parameter lists.
+// The left-hand side is an indicator code for cross-section / time-series and a
+// screener variable (F1, F2…) for the screener, so it stays an opaque string
+// here. Multiple specs for the same lhs accumulate, first-seen order.
+function parseParamSpecs(specs, option, syntax) {
     const groups = new Map();
     for (const spec of specs) {
         const colon = spec.indexOf(":");
         const rest = colon === -1 ? "" : spec.slice(colon + 1);
         const eq = rest.indexOf("=");
-        const code = colon === -1 ? "" : spec.slice(0, colon).trim();
+        const lhs = colon === -1 ? "" : spec.slice(0, colon).trim();
         const paramKey = eq === -1 ? "" : rest.slice(0, eq).trim();
         const paramValue = eq === -1 ? "" : rest.slice(eq + 1).trim();
-        if (!code || !paramKey) {
-            throw new ValidationError(`Invalid --indicator-param: expected "code:key=value", got "${spec}"`);
+        if (!lhs || !paramKey) {
+            throw new ValidationError(`Invalid ${option}: expected "${syntax}", got "${spec}"`);
         }
-        let group = groups.get(code);
-        if (!group) {
-            group = { indicatorCode: code, parameters: [] };
-            groups.set(code, group);
+        let params = groups.get(lhs);
+        if (!params) {
+            params = [];
+            groups.set(lhs, params);
+        }
+        params.push({ paramKey, paramValue });
+    }
+    return groups;
+}
+// Parse repeatable `--indicator-param "code:key=value"` specs into the nested
+// indicatorParamList the EDE cross-section / time-series endpoints expect.
+export function parseIndicatorParams(specs) {
+    if (specs.length === 0)
+        return undefined;
+    return [...parseParamSpecs(specs, "--indicator-param", "code:key=value")].map(([indicatorCode, parameters]) => ({ indicatorCode, parameters }));
+}
+/** Screener variables are `F` + a positive integer; the server rejects anything
+ * else, and a typo'd variable would otherwise surface as an opaque expression
+ * error rather than pointing at the binding that is wrong. */
+const SCREENER_FIELD = /^F[1-9][0-9]*$/;
+// Parse the screener's `--indicator "F1:code"` bindings and merge each one's
+// `--indicator-param "F1:key=value"` specs. Params key off the variable, not the
+// code, because the same indicator may legitimately appear under two variables
+// with different parameters (e.g. the same price on two dates).
+export function parseScreenerIndicators(bindings, paramSpecs) {
+    const params = parseParamSpecs(paramSpecs, "--indicator-param", "F1:key=value");
+    const indicators = new Map();
+    for (const spec of bindings) {
+        const colon = spec.indexOf(":");
+        const field = colon === -1 ? "" : spec.slice(0, colon).trim();
+        const indicatorCode = colon === -1 ? "" : spec.slice(colon + 1).trim();
+        if (!field || !indicatorCode) {
+            throw new ValidationError(`Invalid --indicator: expected "F1:code", got "${spec}"`);
+        }
+        if (!SCREENER_FIELD.test(field)) {
+            throw new ValidationError(`Invalid --indicator variable "${field}": expected F followed by a positive integer, e.g. F1`);
+        }
+        if (indicators.has(field)) {
+            throw new ValidationError(`Duplicate --indicator variable "${field}": each variable must bind exactly one indicator`);
+        }
+        indicators.set(field, { field, indicatorCode, parameters: params.get(field) ?? [] });
+    }
+    // A param for an unbound variable is silently dropped by the server, so the
+    // query would run with a filter the caller believes is applied but is not.
+    for (const field of params.keys()) {
+        if (!indicators.has(field)) {
+            throw new ValidationError(`--indicator-param references "${field}", which no --indicator binds`);
         }
-        group.parameters.push({ paramKey, paramValue });
     }
-    return [...groups.values()];
+    return [...indicators.values()];
 }

package/dist/src/core/asyncContent.js

@@ -5,7 +5,7 @@ import { isTransientError } from "./transport.js";
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
 const POLL_MAX_DELAY_MS = 30_000;
-function nextDelayMs(attempt) {
+export function nextPollDelayMs(attempt) {
     // 5s, 8s, 13s, 20s, 30s, 30s, ...
     const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
     return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
@@ -19,7 +19,9 @@ function nextDelayMs(attempt) {
 // recognize the pending code aborts the poll on a job already billed 50 credits.
 const PENDING_CODES = new Set(["410110", "140001"]);
 const FAILED_CODES = new Set(["410111", "140002"]);
-function isAsyncPending(error) {
+/** Shared by the AI content endpoints and `tool file-parse` — both report
+ * "still generating" with the same codes. */
+export function isAsyncPending(error) {
     return error instanceof ApiError && error.code !== undefined && PENDING_CODES.has(error.code);
 }
 function isAsyncFailed(error) {
@@ -66,7 +68,7 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
             }
         }
         if (attempt < POLL_MAX_ATTEMPTS) {
-            const delay = nextDelayMs(attempt);
+            const delay = nextPollDelayMs(attempt);
             process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
             await new Promise(resolve => setTimeout(resolve, delay));
         }

package/dist/src/core/client.js

@@ -2,12 +2,12 @@ import { createWriteStream } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
-import { request } from "undici";
+import { FormData, request } from "undici";
 import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
 import { ApiError, attachEnvelopeTraceId, ValidationError } from "./errors.js";
 import { ENDPOINTS, resolveTimeoutMs } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
-import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, runWithConcurrency, withRetry } from "./transport.js";
+import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, quoteBigIntFields, runWithConcurrency, withRetry } from "./transport.js";
 // Auth errors that warrant a forced re-login + one replay: the token was rejected
 // server-side while still looking valid by local expiry, so only a forced refresh
 // recovers it. 0000001008 is the legacy code (probed 2026-07-20: still what the
@@ -343,12 +343,17 @@ export class GangtiseClient {
         const authState = { retried: false };
         const timeoutMs = resolveTimeoutMs(this.config.timeoutMs, endpoint);
         return withRetry(async () => {
+            // An upload endpoint hands undici the FormData itself: undici derives the
+            // multipart content-type (boundary included) from the body, so setting one
+            // here would corrupt the request.
+            const isUpload = endpoint.kind === 'upload';
             const headers = {
-                'content-type': 'application/json',
                 // undici does not auto-decompress; decodeResponseBody gunzips below. Server
                 // gzip cuts JSON payloads ~3-10x (measured 3.6x on constant-list).
                 'accept-encoding': 'gzip',
             };
+            if (!isUpload)
+                headers['content-type'] = 'application/json';
             // Keep the header we actually sent: the self-heal check compares it against
             // the current memoCache token to tell "stale token" from "fresh token died".
             let usedAuthorization;
@@ -360,7 +365,7 @@ export class GangtiseClient {
             const response = await request(url, {
                 method: endpoint.method,
                 headers,
-                body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
+                body: endpoint.method === 'GET' ? undefined : (isUpload ? body : JSON.stringify(body ?? {})),
                 headersTimeout: timeoutMs,
                 bodyTimeout: timeoutMs,
                 dispatcher,
@@ -392,7 +397,7 @@ export class GangtiseClient {
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             let parsed;
             try {
-                parsed = JSON.parse(text);
+                parsed = JSON.parse(quoteBigIntFields(text, endpoint.bigIntFields));
             }
             catch {
                 const message = response.statusCode >= 400
@@ -434,7 +439,22 @@ export class GangtiseClient {
             throw error;
         });
     }
-    async download(endpoint, query, options) {
+    /** POST a file as multipart/form-data under the field name `file`. Reuses
+     * requestJson for auth / retry / envelope handling — only the body differs. */
+    async uploadFile(endpointKey, file) {
+        const endpoint = ENDPOINTS[endpointKey];
+        if (!endpoint || endpoint.kind !== 'upload') {
+            throw new ApiError(`Not an upload endpoint: ${endpointKey}`);
+        }
+        const form = new FormData();
+        // Cast: TS 5.7+ types Uint8Array as Uint8Array<ArrayBufferLike>, which BlobPart
+        // (ArrayBufferView<ArrayBuffer>) rejects; a Node Buffer is always ArrayBuffer-backed.
+        form.append('file', new Blob([file.data], { type: file.contentType ?? 'application/octet-stream' }), file.filename);
+        return this.requestJson(endpoint, form);
+    }
+    /** `body` is only sent for POST download endpoints (the file-parse result
+     * endpoint takes `{taskId}` as JSON and answers with the ZIP bytes). */
+    async download(endpoint, query, options, body) {
         const dispatcher = getDispatcher();
         const url = this.buildUrl(endpoint.path);
         Object.entries(query).forEach(([key, value]) => {
@@ -446,9 +466,13 @@ export class GangtiseClient {
             const startedAt = Date.now();
             let currentUrl = url;
             let auth = authorization;
+            const isPost = endpoint.method === 'POST';
             let response = await request(currentUrl, {
                 method: endpoint.method,
-                headers: { Authorization: authorization },
+                headers: isPost
+                    ? { Authorization: authorization, 'content-type': 'application/json' }
+                    : { Authorization: authorization },
+                body: isPost ? JSON.stringify(body ?? {}) : undefined,
                 headersTimeout: this.config.timeoutMs,
                 bodyTimeout: this.config.timeoutMs,
                 dispatcher,
@@ -488,7 +512,7 @@ export class GangtiseClient {
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             if (contentType?.includes('application/json')) {
                 const text = await response.body.text();
-                logTiming(`GET ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                logTiming(`${endpoint.method} ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
                 let parsed;
                 try {
                     parsed = JSON.parse(text);
@@ -517,7 +541,7 @@ export class GangtiseClient {
             }
             if (contentType?.includes('text/plain') || contentType?.includes('text/html')) {
                 const text = await response.body.text();
-                logTiming(`GET ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                logTiming(`${endpoint.method} ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
                 if (response.statusCode >= 400) {
                     throw new ApiError('Download failed', undefined, response.statusCode, text, retryAfterMs);
                 }
@@ -560,11 +584,11 @@ export class GangtiseClient {
                     await fs.unlink(partPath).catch(() => { });
                     throw error;
                 }
-                logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
+                logTiming(`${endpoint.method} ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
                 return { contentType, filename, savedPath: options.streamTo };
             }
             const buffer = await response.body.arrayBuffer();
-            logTiming(`GET ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
+            logTiming(`${endpoint.method} ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
             return {
                 data: new Uint8Array(buffer),
                 contentType,
@@ -587,8 +611,11 @@ export class GangtiseClient {
         if (!endpoint) {
             throw new ApiError(`Unknown endpoint key: ${endpointKey}`);
         }
+        if (endpoint.kind === 'upload') {
+            throw new ValidationError(`${endpointKey} takes a file upload — use 'gangtise tool file-parse --file <path>' ('raw call' cannot send files)`);
+        }
         if (endpoint.kind === 'download') {
-            return this.download(endpoint, query ?? {}, options);
+            return this.download(endpoint, query ?? {}, options, body);
         }
         if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
             return this.requestPaginated(endpoint, body);

package/dist/src/core/commandBodies.js

@@ -1,4 +1,4 @@
-import { maybeArray, parseFrom, parseIndicatorParams, parseOptionalNumberOption, parseSize } from "./args.js";
+import { maybeArray, parseFrom, parseIndicatorParams, parseOptionalNumberOption, parseScreenerIndicators, parseSize } from "./args.js";
 export function buildQuoteKlineBody(options) {
     return {
         securityList: maybeArray(options.security),
@@ -34,25 +34,61 @@ export function buildStockPoolStocksBody(options) {
         poolIdList: options.poolId?.length ? options.poolId : ["all"],
     };
 }
+/** Parameter keys that carry an indicator's own query date. The 2026-08-01 EDE
+ * revision dropped the root-level `date`, so `--date` now fans out into each
+ * indicator's `tradeDate`. Report-period indicators read `reportDate`/`sDate`
+ * instead and answer a `tradeDate` with an EMPTY result rather than an error
+ * (probed 2026-08-01 on `is_op_rev_mom`), so a caller-supplied date of any of
+ * these kinds suppresses the injection for that indicator. Injecting into an
+ * indicator that takes no date at all is harmless — `pty_op_scope` still
+ * answers normally with a stray `tradeDate` attached. */
+const DATE_PARAM_KEYS = new Set(["tradeDate", "reportDate", "sDate"]);
+function withQueryDate(groups, codes, date) {
+    const merged = new Map();
+    for (const group of groups ?? [])
+        merged.set(group.indicatorCode, group);
+    for (const code of codes) {
+        const group = merged.get(code);
+        if (!group) {
+            merged.set(code, { indicatorCode: code, parameters: [{ paramKey: "tradeDate", paramValue: date }] });
+        }
+        else if (!group.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))) {
+            group.parameters.push({ paramKey: "tradeDate", paramValue: date });
+        }
+    }
+    return [...merged.values()];
+}
 export function buildIndicatorCrossSectionBody(options) {
     return {
         indicatorCodeList: maybeArray(options.indicator),
-        securityCodeList: maybeArray(options.security),
-        date: options.date,
+        universe: maybeArray(options.security),
         currency: options.currency,
         scale: options.scale,
-        indicatorParamList: parseIndicatorParams(options.indicatorParam),
+        indicatorParamList: withQueryDate(parseIndicatorParams(options.indicatorParam), options.indicator, options.date),
     };
 }
 export function buildIndicatorTimeSeriesBody(options) {
     return {
         indicatorCodeList: maybeArray(options.indicator),
-        securityCodeList: maybeArray(options.security),
+        universe: maybeArray(options.security),
         startDate: options.startDate,
         endDate: options.endDate,
         calendarType: options.calendarType,
         currency: options.currency,
         scale: options.scale,
-        indicatorParamList: parseIndicatorParams(options.indicatorParam),
+        // The endpoint requires the key even with nothing to configure.
+        indicatorParamList: parseIndicatorParams(options.indicatorParam) ?? [],
+    };
+}
+export function buildIndicatorScreenerBody(options) {
+    const indicators = parseScreenerIndicators(options.indicator, options.indicatorParam);
+    return {
+        universe: maybeArray(options.security),
+        expression: options.expression,
+        indicatorList: options.date
+            ? indicators.map((indicator) => (indicator.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))
+                ? indicator
+                : { ...indicator, parameters: [...indicator.parameters, { paramKey: "tradeDate", paramValue: options.date }] }))
+            : indicators,
     };
 }

package/dist/src/core/endpoints.js

@@ -77,6 +77,19 @@ const ENDPOINT_DEFS = {
         description: "List forums",
         pagination: { enabled: true, maxPageSize: 50 },
     },
+    "insight.performance-calendar.list": {
+        method: "POST",
+        path: "/application/open-insight/schedule/performance-calendar/getList",
+        kind: "json",
+        description: "List earnings calendar events (forecast / express / announcement)",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.performance-calendar.download": {
+        method: "GET",
+        path: "/application/open-insight/schedule/performance-calendar/download/file",
+        kind: "download",
+        description: "Download an earnings report file (A-share 10 credits, HK/US 20)",
+    },
     "insight.research.list": {
         method: "POST",
         path: "/application/open-insight/broker-report/getList",
@@ -619,6 +632,36 @@ const ENDPOINT_DEFS = {
         description: "Get time-series data (multi-indicator x single-security OR single-indicator x multi-security)",
         retry: "no-999999",
     },
+    // Note the path: the screener sits directly under open-indicator, NOT under
+    // the EDE/ prefix its three siblings share.
+    "indicator.screener": {
+        method: "POST",
+        path: "/application/open-indicator/screener",
+        kind: "json",
+        description: "Screen securities by an expression over indicator values (条件选股)",
+        retry: "no-999999",
+    },
+    // ─── tool (open-tool: async file parsing) ───
+    "tool.file-parse.submit": {
+        method: "POST",
+        path: "/application/open-tool/file-parse/submit",
+        kind: "upload",
+        description: "Submit a PDF for parsing (multipart upload), returns taskId",
+        // Billed per page (0.8/页) at submit time, and the upload itself can take
+        // minutes on a 100MB file — never replay it, and don't let the default 30s
+        // headers timeout kill an in-flight upload.
+        timeoutMs: 300_000,
+        retry: "no-replay",
+        // Probed 2026-07-25: taskId comes back as a string today. Guard anyway — if it
+        // ever arrives as a bare number, rounding would strand a paid parse job.
+        bigIntFields: ["taskId"],
+    },
+    "tool.file-parse.result": {
+        method: "POST",
+        path: "/application/open-tool/file-parse/result",
+        kind: "download",
+        description: "Fetch a file-parse result ZIP by taskId (140001 = still generating)",
+    },
 };
 export const ENDPOINTS = Object.fromEntries(Object.entries(ENDPOINT_DEFS).map(([key, def]) => [key, { key, ...def }]));
 /** Flat catalog of every registered endpoint, for `raw list` discoverability

package/dist/src/core/fileParse.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isAsyncPending, nextPollDelayMs, POLL_MAX_ATTEMPTS } from "./asyncContent.js";
+import { saveDownloadResult } from "./download.js";
+import { ApiError, ValidationError } from "./errors.js";
+import { isTransientError } from "./transport.js";
+/** Server-side upload cap (spec: ≤100MB, ≤500 pages). Checked locally so a
+ * doomed 100MB+ upload fails instantly instead of after a long transfer. */
+export const FILE_PARSE_MAX_BYTES = 100 * 1024 * 1024;
+/** Upload a PDF and return its taskId. Billed at submit time (0.8 credits/page),
+ * so every reason to reject a file is checked before the request goes out. */
+export async function submitFileParse(client, filePath) {
+    const resolved = path.resolve(filePath);
+    let stat;
+    try {
+        stat = await fs.stat(resolved);
+    }
+    catch {
+        throw new ValidationError(`File not found: ${filePath}`);
+    }
+    if (!stat.isFile())
+        throw new ValidationError(`Not a file: ${filePath}`);
+    if (stat.size === 0)
+        throw new ValidationError(`File is empty: ${filePath}`);
+    if (stat.size > FILE_PARSE_MAX_BYTES) {
+        throw new ValidationError(`File is ${(stat.size / 1024 / 1024).toFixed(1)}MB — the parse API accepts at most 100MB`);
+    }
+    if (path.extname(resolved).toLowerCase() !== ".pdf") {
+        throw new ValidationError(`Only PDF files are supported: ${filePath}`);
+    }
+    // Buffered, not streamed: undici's FormData needs a Blob, so a 100MB file peaks
+    // at ~2× its size in memory. Acceptable against the API's own 100MB ceiling —
+    // switch to a hand-rolled streaming multipart body if that ceiling ever rises.
+    const data = await fs.readFile(resolved);
+    const result = await client.uploadFile("tool.file-parse.submit", {
+        filename: path.basename(resolved),
+        data,
+        contentType: "application/pdf",
+    });
+    const taskId = result?.taskId;
+    if (taskId === undefined || taskId === null || taskId === "") {
+        throw new ApiError("File parse task was accepted but the response carried no taskId", undefined, undefined, result);
+    }
+    return String(taskId);
+}
+/**
+ * One result fetch. "pending" = the server answered with the generating code
+ * (140001 / legacy 410110); "ok" = the ZIP was written and its path printed.
+ * Free to call — only the submit step is billed.
+ */
+export async function fetchFileParseResult(client, taskId, output) {
+    let result;
+    try {
+        result = await client.call("tool.file-parse.result", { taskId }, undefined, output ? { streamTo: output } : undefined);
+    }
+    catch (error) {
+        if (isAsyncPending(error))
+            return "pending";
+        throw error;
+    }
+    await saveDownloadResult(result, `file-parse-${taskId}`, output);
+    return "ok";
+}
+/** Poll until the ZIP is ready. Same backoff budget as the AI async endpoints
+ * (≈316s), which covers the documented ~3 min parse time. */
+export async function pollFileParseResult(client, taskId, output) {
+    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            if (await fetchFileParseResult(client, taskId, output) === "ok")
+                return "ok";
+        }
+        catch (error) {
+            // The task is already paid for: a blip must not void the wait. Transient
+            // errors consume the attempt, anything else (bad taskId, no permission) aborts.
+            if (!isTransientError(error))
+                throw error;
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
+        }
+        if (attempt < POLL_MAX_ATTEMPTS) {
+            const delay = nextPollDelayMs(attempt);
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: parse result not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    return "timeout";
+}

package/dist/src/core/indicatorMatrix.js

@@ -31,23 +31,32 @@ export function unwrapIndicatorData(raw) {
 function asStringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item)) : undefined;
 }
+function asIndicatorMetaList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.map((item) => (item && typeof item === "object" && !Array.isArray(item) ? item : {}));
+}
+function optionalString(value) {
+    return value === undefined || value === null ? undefined : String(value);
+}
 function rowOf(values, index) {
     const row = values[index];
     return Array.isArray(row) ? row : undefined;
 }
 // Build one column header per series. Prefer the human-readable name; on a
-// duplicate name append the code so a column is never silently overwritten.
-function buildHeaders(names, codes, count) {
-    // Pre-seed the metadata column names: an indicator literally named "date" /
-    // "security" / "name" must get a suffixed header, not overwrite the metadata.
-    const used = new Set(["date", "security", "name"]);
+// duplicate name append a disambiguator so a column is never silently
+// overwritten. `reserved` pre-seeds the metadata column names, so a series
+// literally named "date" / "security" / "name" gets suffixed rather than
+// clobbering the metadata.
+function buildHeaders(bases, suffixes, reserved) {
+    const used = new Set(reserved);
     const headers = [];
-    for (let i = 0; i < count; i++) {
-        const base = String(names?.[i] ?? codes?.[i] ?? `col${i}`);
+    for (let i = 0; i < bases.length; i++) {
+        const base = bases[i] ?? suffixes[i] ?? `col${i}`;
         let header = base;
         let attempt = 1;
         while (used.has(header)) {
-            const suffix = codes?.[i] ?? i;
+            const suffix = suffixes[i] ?? i;
             header = attempt === 1 ? `${base} (${suffix})` : `${base} (${suffix})_${attempt}`;
             attempt++;
         }
@@ -56,27 +65,40 @@ function buildHeaders(names, codes, count) {
     }
     return headers;
 }
-// Cross-section: one row per security, one column per indicator. The live
-// `values` is a 2D [numIndicators][numSecurities] matrix in indicator-major
-// order, so indicator i on security j is values[i][j].
-// keyBy "code" makes each indicator column its `indicatorCode` (unique, and
-// independent of the display name or the server's column order) instead of the
-// human name — required for batch code→value mapping, where names collide
-// (many indicators share a display name) and the server reorders columns.
+// Column headers for a list of indicator metadata. keyBy "code" makes each
+// column its `code` (unique, and independent of the display name or the
+// server's column order) instead of the human name — required for batch
+// code→value mapping, where names collide (many indicators share a display
+// name) and the server reorders columns relative to the request. The screener
+// disambiguates by `field` instead, because there the SAME code may legitimately
+// appear twice under two variables with different parameters.
+function indicatorHeaders(indicators, keyBy, reserved) {
+    const codes = indicators.map((meta) => optionalString(meta.code));
+    const fields = indicators.map((meta, i) => optionalString(meta.field) ?? codes[i]);
+    const bases = keyBy === "code" ? codes : indicators.map((meta) => optionalString(meta.name));
+    return buildHeaders(bases, fields, reserved);
+}
+const CROSS_SECTION_COLUMNS = ["security", "name"];
+// Cross-section (and the screener, whose payload is the same shape plus a
+// per-indicator `field`): one row per security, one column per indicator.
+// `values` is [security][indicator], so security i's value for indicator j is
+// values[i][j]. There is no row-level date any more — the query date now lives
+// in each indicator's own parameters and may legitimately differ per column.
 export function flattenCrossSection(data, keyBy = "name") {
     if (!data || typeof data !== "object")
         return data;
     const d = data;
     const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asStringArray(d.indicatorCodeList);
+    const indicators = asIndicatorMetaList(d.indicatorList);
     if (!Array.isArray(d.values) || !securityCode || !indicators)
         return data;
     const securityName = asStringArray(d.securityNameList);
-    const headers = buildHeaders(keyBy === "code" ? indicators : asStringArray(d.indicatorNameList), indicators, indicators.length);
-    const list = securityCode.map((code, j) => {
-        const row = { date: d.date, security: code, name: securityName?.[j] };
-        for (let i = 0; i < indicators.length; i++) {
-            row[headers[i]] = rowOf(d.values, i)?.[j];
+    const headers = indicatorHeaders(indicators, keyBy, CROSS_SECTION_COLUMNS);
+    const list = securityCode.map((code, i) => {
+        const row = { security: code, name: securityName?.[i] };
+        const cells = rowOf(d.values, i);
+        for (let j = 0; j < headers.length; j++) {
+            row[headers[j]] = cells?.[j];
         }
         return row;
     });
@@ -84,20 +106,24 @@ export function flattenCrossSection(data, keyBy = "name") {
 }
 // Time-series: one row per date. Columns are the indicators (single-security
 // case) or the securities (single-indicator case) — exactly one dimension
-// varies, per the API contract. `values` is a 2D [series][date] matrix.
+// varies, per the API contract. `values` stays a 2D [series][date] matrix.
 export function flattenTimeSeries(data, keyBy = "name") {
     if (!data || typeof data !== "object")
         return data;
     const d = data;
     const dates = asStringArray(d.dates);
     const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asStringArray(d.indicatorCodeList);
+    const indicators = asIndicatorMetaList(d.indicatorList);
     if (!Array.isArray(d.values) || !dates || !securityCode || !indicators)
         return data;
+    const securityName = asStringArray(d.securityNameList);
     const seriesAreIndicators = securityCode.length <= 1;
+    // Map over securityCode rather than securityNameList directly: a response that
+    // omits the names must still yield one header per security (falling back to
+    // the code), not zero columns.
     const headers = seriesAreIndicators
-        ? buildHeaders(keyBy === "code" ? indicators : asStringArray(d.indicatorNameList), indicators, indicators.length)
-        : buildHeaders(keyBy === "code" ? securityCode : asStringArray(d.securityNameList), securityCode, securityCode.length);
+        ? indicatorHeaders(indicators, keyBy, ["date"])
+        : buildHeaders(securityCode.map((code, i) => (keyBy === "code" ? code : securityName?.[i])), securityCode, ["date"]);
     const list = dates.map((date, k) => {
         const row = { date };
         for (let i = 0; i < headers.length; i++) {

package/dist/src/core/transport.js

@@ -9,6 +9,26 @@ export function decodeResponseBody(buf, contentEncoding) {
     const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
     return enc === "gzip" ? gunzipSync(b).toString("utf8") : b.toString("utf8");
 }
+/**
+ * Re-quote the *unquoted numeric* values of the named JSON fields so ids past
+ * 2^53 survive JSON.parse: `{"taskId":1782345678901234567}` would otherwise come
+ * back as 1782345678901234700 and address a task that does not exist.
+ *
+ * Probed 2026-07-25: file-parse's submit returns `taskId` as a STRING (matching
+ * the spec), so this is a forward guard, not a live fix — but the failure mode it
+ * covers is silent and expensive (the parse job is already billed, and a rounded
+ * id can never fetch its result). Values already in quotes are left alone: the
+ * pattern only matches a bare number right after the key.
+ */
+export function quoteBigIntFields(text, fields) {
+    if (!fields?.length)
+        return text;
+    let out = text;
+    for (const field of fields) {
+        out = out.replace(new RegExp(`("${field}"\\s*:\\s*)(-?\\d+)`, "g"), '$1"$2"');
+    }
+    return out;
+}
 /** A Retry-After delay we'll honor even if it exceeds maxDelay — but never past this
  * ceiling, so a hostile/misconfigured header can't hang the CLI for minutes. */
 const RETRY_AFTER_CEILING_MS = 60_000;

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.28.3";
+export const CLI_VERSION = "0.30.0";