gangtise-openapi-cli 0.34.0 → 0.35.0

package/dist/src/core/client.js

@@ -8,22 +8,11 @@ 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, 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
-// token filter emits); 999002 TOKEN_INVALID is its 2026-07-17 replacement, listed
-// ahead of the rollout so self-heal does not silently die when the filter switches.
-// 8000014/8000015 are the retired AK/SK codes, kept for older server builds.
-// 999011 CREDENTIAL_INVALID is not here and could not act if it were — it comes from
-// auth.login, which runs useAuth=false and so never reaches this check. Its "never
-// replay" guarantee lives in transport's TERMINAL_API_CODES instead.
 const AUTH_RETRY_CODES = new Set(["8000014", "8000015", "0000001008", "999002"]);
 export class GangtiseClient {
     config;
     refreshPromise = null;
     memoCache = null;
-    // After an injected env token (GANGTISE_TOKEN) is rejected and we self-heal via
-    // login, stop preferring that now-stale token so the retry uses the fresh one.
     envTokenInvalidated = false;
     constructor(config) {
         this.config = config;
@@ -53,15 +42,10 @@ export class GangtiseClient {
             accessKey: credentials.accessKey,
             secretKey: credentials.secretKey,
         }, false);
-        // Validate the shape before touching it: a missing accessToken used to surface
-        // as a bare TypeError from normalizeToken, hiding the real cause.
         if (typeof envelope?.accessToken !== "string" || !envelope.accessToken) {
             throw new ApiError("Login succeeded but the response carried no accessToken", undefined, undefined, envelope);
         }
         const accessToken = normalizeToken(envelope.accessToken);
-        // A non-numeric expiresIn would make expiresAt NaN — the cache would never
-        // validate and every command would silently re-login. Degrade to 0 instead
-        // (token works now, next process logs in again).
         const expiresIn = Number.isFinite(envelope.expiresIn) ? envelope.expiresIn : 0;
         const expiresAt = Math.floor(Date.now() / 1000) + expiresIn;
         const cache = { ...envelope, accessToken, expiresIn, expiresAt };
@@ -70,20 +54,11 @@ export class GangtiseClient {
             await writeTokenCache(this.config.tokenCachePath, cache);
         }
         catch (error) {
-            // A read-only HOME or full disk must not fail the request — the in-memory
-            // token is valid; we just can't persist it for the next process.
             const msg = error instanceof Error ? error.message : String(error);
             process.stderr.write(`[gangtise] warning: could not persist token cache: ${msg}\n`);
         }
         return accessToken;
     }
-    /**
-     * On a recoverable auth error (expired/invalid token codes), force a one-time
-     * token refresh and re-throw as retryable so withRetry replays the request.
-     * Otherwise — or once we've already retried this request — it's a no-op and
-     * the caller re-throws the original error. `authState` persists across the
-     * withRetry attempts so we only refresh once per logical request.
-     */
     async refreshAuthIfRecoverable(error, useAuth, authState, usedAuthorization) {
         if (useAuth
             && !authState.retried
@@ -94,13 +69,6 @@ export class GangtiseClient {
             && this.config.secretKey) {
             authState.retried = true;
             this.envTokenInvalidated = true;
-            // If the failed request was still carrying an OLDER token than the one now in
-            // memoCache, another request already refreshed — replay with the fresh token
-            // instead of logging in again (back-to-back logins can kick each other's
-            // sessions server-side, the 0000001008 semantics). If the failed request used
-            // the CURRENT token, that token is genuinely dead: force a new login. A time
-            // window is NOT a valid proxy here — right after the initial login the window
-            // is always "recent", which would skip the refresh exactly when it's needed.
             const memoToken = this.memoCache && isTokenCacheValid(this.memoCache) ? normalizeToken(this.memoCache.accessToken) : null;
             const alreadyRefreshed = memoToken !== null && usedAuthorization !== undefined && usedAuthorization !== memoToken;
             if (!alreadyRefreshed) {
@@ -110,9 +78,6 @@ export class GangtiseClient {
             throw markRetryable(new ApiError(error.message, error.code, error.statusCode, error.details));
         }
     }
-    /** `new URL("/a/b", "https://proxy/prefix")` drops "/prefix" — an absolute path
-     * replaces the base's path per the URL spec. Join manually so a reverse-proxy
-     * GANGTISE_BASE_URL with a path prefix keeps working. */
     buildUrl(path) {
         const base = this.config.baseUrl.endsWith("/") ? this.config.baseUrl : `${this.config.baseUrl}/`;
         return new URL(path.replace(/^\//, ""), base);
@@ -142,9 +107,6 @@ export class GangtiseClient {
             throw new ApiError(parsed.msg || "API request failed", code, statusCode, parsed, retryAfterMs);
         }
         if ('data' in parsed) {
-            // Carry the envelope's traceId onto the payload: the EDE endpoints wrap a
-            // second envelope inside `data` and raise their own failures from it, by
-            // which point this is the only traceId in reach.
             return attachEnvelopeTraceId(parsed.data, parsed.traceId);
         }
         return parsed;
@@ -177,7 +139,6 @@ export class GangtiseClient {
         const startFrom = typeof initialBody.from === 'number' && Number.isFinite(initialBody.from) ? initialBody.from : 0;
         const requestedSize = typeof initialBody.size === 'number' && Number.isFinite(initialBody.size) ? initialBody.size : undefined;
         const maxPageSize = endpoint.pagination?.maxPageSize ?? requestedSize ?? 20;
-        // First page: serial — we need total before deciding how many more requests to fan out.
         const firstPageSize = requestedSize === undefined ? maxPageSize : Math.min(maxPageSize, requestedSize);
         const firstPage = await this.requestJson(endpoint, {
             ...initialBody,
@@ -185,26 +146,7 @@ export class GangtiseClient {
             size: firstPageSize,
         });
         if (!this.isPaginatedListResponse(firstPage)) {
-            // Shape drift (e.g. total arriving as a string) silently degrades fetch-all
-            // to a single page with no partial marker. This is NOT hypothetical: passing
-            // industryList to insight foreign-opinion / independent-opinion makes the
-            // server answer 200 + data:null, which then renders as one phantom row
-            // ({"value":null} in jsonl, a blank row in table/markdown). Verbose-only was
-            // the wrong bar — a caller who never sets GANGTISE_VERBOSE reads that row as
-            // real data, so warn on stderr unconditionally.
             process.stderr.write(`[gangtise] warning: ${endpoint.key} is marked paginated but the first page has an unexpected shape (no numeric total + list); returning it as-is\n`);
-            // A warning only helps a human. Scripts read the exit code, and without one they
-            // cannot tell "this filter legitimately matched nothing" from "this filter is
-            // broken". Reuse exit 3 (result is not what was asked for) rather than inventing a
-            // fourth code — fetch-all silently degraded to one page either way.
-            //
-            // Applies to EVERY malformed shape, not just `null`: a string `total` truncates the
-            // result to page 1, which looks complete and is therefore worse than an obviously
-            // empty payload. All 24 paginated endpoints are genuine {total, list} lists (the
-            // odd-shaped ones like reference.constant-list are not marked paginated), so there
-            // is no legitimate response that lands here. Endpoints where `null` IS a valid
-            // answer (ai.one-pager for a security with no generated content) are unpaginated
-            // and never reach this branch.
             process.exitCode = 3;
             return firstPage;
         }
@@ -212,9 +154,6 @@ export class GangtiseClient {
         const collected = [...firstPage.list];
         const available = Math.max(total - startFrom, 0);
         const target = requestedSize === undefined ? available : Math.min(requestedSize, available);
-        // Last page reached on first request. If `total` promises more rows than the
-        // short page delivered, the server's page cap may be lower than our configured
-        // maxPageSize — say so instead of silently returning a subset as "everything".
         if (firstPage.list.length < firstPageSize) {
             const out = {
                 ...firstPage,
@@ -223,8 +162,6 @@ export class GangtiseClient {
             };
             if (collected.length < target) {
                 process.stderr.write(`[gangtise] warning: server returned a short page (${collected.length} rows) but reported total=${total}; treating it as the end of data — results may be incomplete\n`);
-                // Machine-readable counterpart of the warning: scripts key off partial /
-                // exit code 3, and must not mistake a truncated result for a complete one.
                 out.partial = true;
             }
             return out;
@@ -236,9 +173,6 @@ export class GangtiseClient {
                 list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
             };
         }
-        // Build remaining page requests. The cap lives inside the loop: a corrupt
-        // server `total` (e.g. 9e15) must not materialize millions of page objects —
-        // or spin for minutes — before a post-hoc truncation applies.
         const MAX_PAGES = 1000;
         let truncatedByPageCap = false;
         const pageRequests = [];
@@ -256,11 +190,6 @@ export class GangtiseClient {
         }
         let unexpectedShape = false;
         let totalDrift = false;
-        // Fail-soft fan-out: a hard page failure (rate-limit 903301, no-perm, retries
-        // exhausted) must NOT discard the pages already fetched. Catch per page, record
-        // it, and stop starting new requests so we don't keep burning quota into a rate
-        // limit. Mirrors quoteSharding's partial-result tolerance — but firstPage already
-        // succeeded to get here, so unlike sharding there's no total-failure case.
         const failedPages = [];
         let firstError = null;
         let aborted = false;
@@ -276,8 +205,6 @@ export class GangtiseClient {
                     size: req.size,
                 });
                 if (!this.isPaginatedListResponse(page)) {
-                    // Treat a shape-broken page like a failed page: its rows are missing, so
-                    // the result must carry the partial marker instead of looking complete.
                     unexpectedShape = true;
                     failedPages.push(req);
                     return [];
@@ -305,39 +232,27 @@ export class GangtiseClient {
         if (totalDrift) {
             process.stderr.write(`[gangtise] warning: 'total' changed across pages (data shifted during fetch); rows may be duplicated or missing\n`);
         }
-        // Always surface a cap-induced truncation (not gated on verbose): the user
-        // asked for everything and is silently getting a subset, mirroring the
-        // partial-result warning in quoteSharding.
         if (truncatedByPageCap) {
             process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${collected.length} of ${total} rows. Narrow the query (e.g. a shorter date range) or pass --size to fetch a bounded subset.\n`);
         }
         const short = collected.length < target;
-        // `total` is not always the real row count. Three opinion endpoints report a fixed
-        // 10000 while `from=30000` still returns real rows with monotonically older publish
-        // times (the shape of Elasticsearch's default track_total_hits). A fetch-all then
-        // stops exactly at the cap with collected === total, so every completeness check
-        // below passes and the truncated export looks complete — the worst failure mode we
-        // have, because `opinion` bills 30 credits per row.
-        //
-        // Probe one row past the claimed end rather than hardcoding any number: the server
-        // can change the cap, and evidence survives that where a constant would not. Only on
-        // a genuine fetch-all that otherwise looked complete — when `total` is honest the
-        // probe comes back empty (and bills nothing, since these endpoints charge per row).
         let totalCapped = false;
-        if (requestedSize === undefined && total > 0 && !short && !totalDrift && !truncatedByPageCap && failedPages.length === 0) {
+        if (endpoint.retry !== "no-replay" && requestedSize === undefined && total > 0 && !short && !totalDrift && !truncatedByPageCap && failedPages.length === 0) {
             try {
                 const probe = await this.requestJson(endpoint, { ...initialBody, from: total, size: 1 });
                 if (this.isPaginatedListResponse(probe) && probe.list.length > 0)
                     totalCapped = true;
             }
             catch {
-                // A failed probe must never fail an otherwise-complete export: we simply do not
-                // learn whether the total was capped, which is the pre-existing behaviour.
             }
         }
         if (totalCapped) {
             process.stderr.write(`[gangtise] warning: ${endpoint.key} reported total=${total} but rows exist past that offset — 'total' is a server-side cap, not the real count. This export is TRUNCATED at ${collected.length} rows. Narrow the query (date range / filters) and fetch in slices.\n`);
         }
+        if (endpoint.retry === "no-replay" && requestedSize === undefined && total > 0
+            && !short && !totalDrift && !truncatedByPageCap && failedPages.length === 0 && isVerbose()) {
+            process.stderr.write(`[gangtise] total-cap probe skipped on ${endpoint.key} (per-call billing) — a capped 'total' would go undetected here\n`);
+        }
         const out = {
             ...firstPage,
             total,
@@ -347,15 +262,6 @@ export class GangtiseClient {
             out.partial = true;
             out.totalCapped = true;
         }
-        // Unified completeness backstop. Whatever the cause — a failed/shape-broken page,
-        // a short later page (server page cap < maxPageSize), the MAX_PAGES cap, or `total`
-        // drifting mid-fetch — the result is partial. A short row count or a total drift each
-        // force it; so does any failedPages entry on its own — an over-returning sibling page
-        // can lift the row count back to target and mask the hole (short would read false), yet
-        // the failedPages branch below still writes "results are partial" to stderr, so the flag
-        // must agree. printData maps partial → exit 3 so a script can't read a truncated export
-        // as complete. The cap and drift branches above already warned on stderr; failedPages
-        // warns below.
         if (short || totalDrift || failedPages.length > 0)
             out.partial = true;
         if (failedPages.length > 0) {
@@ -365,9 +271,6 @@ export class GangtiseClient {
             process.stderr.write(`[gangtise] warning: ${failedPages.length}/${pageRequests.length} pages not fetched${detail}; results are partial — got ${collected.length}/${total} rows (see failedPages).${skippedHint}\n`);
         }
         else if (short && !truncatedByPageCap && !totalDrift) {
-            // A short later page with no failure, cap, or drift to explain it: the server
-            // simply delivered fewer rows than `total` promised. Warn so an interactive run
-            // sees why the result is partial (the other causes each warn on their own path).
             process.stderr.write(`[gangtise] warning: server returned ${collected.length} of ${total} rows (a later page came back short); results may be incomplete\n`);
         }
         return out;
@@ -389,19 +292,12 @@ 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 = {
-                // 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;
             if (useAuth) {
                 usedAuthorization = await this.getAuthorizationHeader();
@@ -416,14 +312,10 @@ export class GangtiseClient {
                 bodyTimeout: timeoutMs,
                 dispatcher,
             });
-            // Only buffer + gunzip when the server actually compressed; an unencoded
-            // response reads as text directly (and keeps existing behavior on that path).
             const encoding = response.headers['content-encoding'];
             const gzipped = (Array.isArray(encoding) ? encoding[0] : encoding)?.toLowerCase().trim() === 'gzip';
             let text;
             if (gzipped) {
-                // A proxy/middlebox can declare gzip and deliver garbage — surface that as
-                // an ApiError with request context instead of a bare zlib Z_DATA_ERROR.
                 const bytes = new Uint8Array(await response.body.arrayBuffer());
                 try {
                     text = decodeResponseBody(bytes, encoding);
@@ -437,9 +329,6 @@ export class GangtiseClient {
                 text = await response.body.text();
             }
             logTiming(`${endpoint.method} ${endpoint.path}`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
-            // Parse Retry-After once so every error path below (JSON parse failure AND the
-            // envelope/HTTP-error throw) carries it — a non-JSON 429/503 must still honor
-            // the server's rate window instead of falling back to default backoff.
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             let parsed;
             try {
@@ -452,8 +341,6 @@ export class GangtiseClient {
                 throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500), retryAfterMs);
             }
             try {
-                // Auth errors can arrive as HTTP 4xx or as a 200-wrapped error envelope;
-                // both routes must reach the self-heal check below.
                 if (response.statusCode >= 400) {
                     this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                 }
@@ -472,15 +359,6 @@ export class GangtiseClient {
                 process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
             },
         }).catch((error) => {
-            // Until 2026-08-01 EDE answered a no-data query with 999999, so this hint
-            // led with "多为查询无数据". No-data now comes back as a null CELL with its
-            // row and column intact (re-probed 2026-08-08), which leaves 999999 meaning
-            // an actual server fault — but the parameter checklist
-            // is still the right first move, because a wrong param name or date axis
-            // silently yields an EMPTY TABLE rather than this error. Only the data
-            // endpoints take a date/security/params; indicator.search shares the
-            // no-999999 policy but has just a keyword, so it keeps the generic hint
-            // instead of nonsensical date/scope/param guidance.
             const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series' || endpoint.key === 'indicator.screener';
             if (isIndicatorFetch && error instanceof ApiError && error.code === '999999') {
                 throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名是静默失效）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意此码不表示无数据——有效 code 无数据现在返回保留行列的 null 单元格，空表则多半是整个轴的 code 都没被识别。');
@@ -488,21 +366,15 @@ export class GangtiseClient {
             throw error;
         });
     }
-    /** 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);
@@ -526,10 +398,6 @@ export class GangtiseClient {
                 bodyTimeout: this.config.timeoutMs,
                 dispatcher,
             });
-            // undici does not follow redirects, and a download endpoint may 302 to a
-            // pre-signed object-store URL — without this the redirect body would be
-            // saved as the "file". Follow up to 3 hops, dropping Authorization once the
-            // redirect leaves the API origin so the bearer never reaches storage hosts.
             for (let hops = 0; hops < 3 && response.statusCode >= 300 && response.statusCode < 400; hops++) {
                 const locationHeader = response.headers.location;
                 const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader;
@@ -548,16 +416,11 @@ export class GangtiseClient {
                     dispatcher,
                 });
             }
-            // The loop above can exit with a 3xx still in hand (hop limit exceeded, or a
-            // redirect without Location) — that response must never be treated as file
-            // content: its HTML placeholder body would be saved as the "downloaded file".
             if (response.statusCode >= 300 && response.statusCode < 400) {
                 await response.body.text().catch(() => { });
                 throw new ApiError(`Download failed: unresolved redirect (HTTP ${response.statusCode})`, undefined, response.statusCode);
             }
             const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
-            // From the final (post-redirect) response, so a rate-limited download honors
-            // Retry-After too — every error branch below passes it into the ApiError.
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             if (contentType?.includes('application/json')) {
                 const text = await response.body.text();
@@ -604,9 +467,6 @@ export class GangtiseClient {
             const filenameMatch = Array.isArray(contentDisposition)
                 ? contentDisposition[0]?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i)
                 : contentDisposition?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i);
-            // A plain filename= value with a bare % ("增长100%.pdf") is not valid URI
-            // encoding — decodeURIComponent would throw and fail the whole download over
-            // a cosmetic hint. Fall back to the raw value instead.
             let filename;
             if (filenameMatch) {
                 const raw = filenameMatch[1] || filenameMatch[2];
@@ -617,13 +477,8 @@ export class GangtiseClient {
                     filename = raw;
                 }
             }
-            // Stream directly to disk when caller already knows the destination
             if (options?.streamTo) {
                 await fs.mkdir(path.dirname(options.streamTo), { recursive: true });
-                // Stream into a .part sibling and rename over the target only on success:
-                // writing to the target directly would truncate an existing file on the
-                // FIRST byte and delete it on failure — a failed re-download (or each
-                // withRetry attempt) must never destroy the user's previous good file.
                 const partPath = `${options.streamTo}.part`;
                 try {
                     await pipeline(response.body, createWriteStream(partPath));
@@ -644,8 +499,6 @@ export class GangtiseClient {
                 filename,
             };
         }, {
-            // Download endpoints carry per-篇 billing too (summary/foreign-report/
-            // my-conference at 50/篇) — honor the endpoint's retry policy here as well.
             policy: endpoint.retry ?? "default",
             onRetry: (attempt, error, delay) => {
                 if (!isVerbose())

package/dist/src/core/commandBodies.js

@@ -34,27 +34,6 @@ export function buildStockPoolStocksBody(options) {
         poolIdList: options.poolId?.length ? options.poolId : ["all"],
     };
 }
-/** Parameter keys that REPLACE an indicator's `tradeDate`. The 2026-08-01 EDE
- * revision dropped the root-level `date`, so `--date` now fans out into each
- * indicator's `tradeDate`. A caller-supplied `reportDate` suppresses that
- * injection for its indicator, so the two date fields are never sent together.
- *
- * This is load-bearing, and the server has moved twice on it. A report-period
- * indicator answered a `tradeDate` with an EMPTY result (probed 2026-08-01 on
- * `is_op_rev_mom`), then resolved it to the enclosing report period (2026-08-08,
- * same 33.4903 either way), and since 2026-08-14 REJECTS it outright:
- * `100003 指标 is_op_rev_mom 不支持参数 tradeDate; 缺少必填参数 reportDate`
- * (re-probed 2026-08-15; `reportDate` still returns 33.4903). So a caller-supplied
- * `reportDate` is now the only way to reach those indicators, and suppressing the
- * `tradeDate` injection is what makes it work rather than merely being tidier.
- * Injecting into an indicator that takes no date at all is harmless —
- * `pty_op_scope` still answers normally with a stray `tradeDate` attached.
- *
- * `sDate` is deliberately NOT here. It is an interval START, not a substitute:
- * `qte_vol_intvl` declares `tradeDate` required (the interval END) and `sDate`
- * optional. Treating it as a replacement dropped `--date` and silently moved the
- * interval end — probed 2026-08-02, 茅台 sDate=2024-01-02 returned 2,265,873,849
- * without a tradeDate vs 65,687,435 with tradeDate=2024-01-31, both exit 0. */
 const DATE_PARAM_KEYS = new Set(["tradeDate", "reportDate"]);
 function withQueryDate(groups, codes, date) {
     const merged = new Map();
@@ -65,11 +44,15 @@ function withQueryDate(groups, codes, date) {
         if (!group) {
             merged.set(code, { indicatorCode: code, parameters: [{ paramKey: "tradeDate", paramValue: date }] });
         }
-        else if (!group.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))) {
+        else if (!group.noQueryDate && !group.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))) {
             group.parameters.push({ paramKey: "tradeDate", paramValue: date });
         }
     }
-    return [...merged.values()];
+    return [...merged.values()].map(stripMarker);
+}
+function stripMarker(item) {
+    const { noQueryDate, ...rest } = item;
+    return rest;
 }
 export function buildIndicatorCrossSectionBody(options) {
     return {
@@ -89,8 +72,7 @@ export function buildIndicatorTimeSeriesBody(options) {
         calendarType: options.calendarType,
         currency: options.currency,
         scale: options.scale,
-        // The endpoint requires the key even with nothing to configure.
-        indicatorParamList: parseIndicatorParams(options.indicatorParam) ?? [],
+        indicatorParamList: (parseIndicatorParams(options.indicatorParam) ?? []).map(stripMarker),
     };
 }
 export function buildIndicatorScreenerBody(options) {
@@ -98,16 +80,6 @@ export function buildIndicatorScreenerBody(options) {
     return {
         universe: maybeArray(options.security),
         expression: options.expression,
-        // Every indicator gets a date, including ones whose parameterList is empty.
-        // Harmless there (a parameterless indicator answers normally with a stray
-        // tradeDate), and it keeps one rule for the whole list rather than a
-        // per-indicator exception.
-        //
-        // It also used to be load-bearing: through 2026-08-02 the screener DROPPED
-        // any indicator sent with `parameters: []`, so the official doc's own
-        // `F3 contains '酒'` example could not work as written. Re-probed 2026-08-03:
-        // fixed server-side. Kept anyway — unconditional is simpler than conditional,
-        // and it survives a rollback.
         indicatorList: indicators.map((indicator) => (indicator.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))
             ? indicator
             : { ...indicator, parameters: [...indicator.parameters, { paramKey: "tradeDate", paramValue: options.date }] })),

package/dist/src/core/download.js

@@ -3,34 +3,18 @@ import { extname } from "node:path";
 import { DownloadError } from "./errors.js";
 import { saveOutputIfNeeded } from "./output.js";
 import { lookupTitleCache, readTitleCache, TITLE_LOOKUP_SIZE } from "./titleCache.js";
-/** Replace filesystem-unsafe characters (path separators, wildcards, and control
- * characters / NUL) with `_` so a title or a server-supplied filename can't create
- * stray subdirectories, escape the intended output path, or break fs.writeFile.
- * Shared by title-based naming and the download fallback. */
 function sanitizeFilename(name) {
     return name.replace(/[/\\:*?"<>|\u0000-\u001f]/g, "_");
 }
-/** Keep auto-derived filenames under 200 UTF-8 bytes, preserving the extension.
- * ext4 caps directory entries at 255 bytes — long Chinese titles hit that at
- * ~85 chars (3 bytes each) and fs.writeFile throws ENAMETOOLONG after the body
- * has already been downloaded. */
 function truncateFilename(name, maxBytes = 200) {
     if (Buffer.byteLength(name, "utf8") <= maxBytes)
         return name;
     const ext = extname(name);
-    // Trim by code point, not UTF-16 unit: a cut inside a surrogate pair would put
-    // a lone surrogate in the name, which reaches the filesystem as U+FFFD (�).
     const stem = [...name.slice(0, name.length - ext.length)];
     while (stem.length > 1 && Buffer.byteLength(stem.join("") + ext, "utf8") > maxBytes)
         stem.pop();
     return stem.join("") + ext;
 }
-/** Pick a non-existing path by suffixing -1, -2, … before the extension, so batch
- * downloads whose titles collide ("2025年第一季度报告" from several companies) don't
- * silently overwrite each other. Only auto-derived names go through this — an
- * explicit --output path keeps plain overwrite semantics. Throws instead of
- * falling back to the original path once the suffixes run out: returning `p`
- * there would silently overwrite the very first file. */
 export async function uniquePath(p) {
     const exists = (f) => fs.access(f).then(() => true, () => false);
     if (!(await exists(p)))
@@ -93,7 +77,6 @@ export async function resolveTitle(client, result, listEndpoint, idField, idValu
             return buildFilename(cached);
     }
     catch {
-        // Ignore corrupt cache data and fall back to the list endpoint.
     }
     try {
         const resp = await client.call(listEndpoint, { from: 0, size: TITLE_LOOKUP_SIZE });
@@ -115,13 +98,8 @@ async function downloadUrlTo(url, outputPath) {
     const { request } = await import("undici");
     const { getDispatcher, logTiming, withRetry } = await import("./transport.js");
     const { loadConfig } = await import("./config.js");
-    // Through the transport layer instead of a bare global fetch: the configured
-    // timeout applies (a slow-drip CDN can no longer hang the CLI indefinitely),
-    // network-level failures retry, and --verbose logs the request.
     const timeoutMs = loadConfig().timeoutMs;
     await fs.mkdir(dirname(outputPath), { recursive: true });
-    // Signed URLs carry credentials in the query string — verbose logs must strip
-    // search/hash so signatures never land in terminal/CI logs.
     const redactUrl = (u) => {
         try {
             const parsed = new URL(u);
@@ -131,7 +109,6 @@ async function downloadUrlTo(url, outputPath) {
             return "signed-url";
         }
     };
-    // .part + rename so a failed follow-download never destroys an existing file.
     const partPath = `${outputPath}.part`;
     await withRetry(async () => {
         const startedAt = Date.now();
@@ -139,18 +116,11 @@ async function downloadUrlTo(url, outputPath) {
             method: "GET",
             headersTimeout: timeoutMs,
             bodyTimeout: timeoutMs,
-            // headers/body timeouts are IDLE timeouts — a stream trickling one byte
-            // per interval resets them forever. A generous total deadline (10× the
-            // per-request timeout) bounds the whole transfer without killing large
-            // legitimate downloads.
             signal: AbortSignal.timeout(timeoutMs * 10),
             dispatcher: getDispatcher(),
         };
         let currentUrl = url;
         let response = await request(currentUrl, requestOptions);
-        // undici does not follow redirects (the old global fetch did): a signed URL
-        // may 302 to the real CDN object. Follow a bounded number of hops; no
-        // Authorization header is involved on this path, so nothing leaks cross-origin.
         for (let hops = 0; hops < 3 && response.statusCode >= 300 && response.statusCode < 400; hops++) {
             const locationHeader = response.headers.location;
             const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader;
@@ -166,7 +136,6 @@ async function downloadUrlTo(url, outputPath) {
         }
         if (response.statusCode >= 400) {
             await response.body.text().catch(() => { });
-            // DownloadError (not retried): signed URLs expire — replaying a 403 is useless.
             throw new DownloadError(`Failed to fetch download URL (HTTP ${response.statusCode})`);
         }
         try {
@@ -182,7 +151,6 @@ async function downloadUrlTo(url, outputPath) {
         await fs.rename(partPath, outputPath);
     }
     catch (error) {
-        // e.g. outputPath turned out to be a directory — don't leave the .part behind.
         await fs.unlink(partPath).catch(() => { });
         throw error;
     }
@@ -192,16 +160,12 @@ export async function saveDownloadResult(result, fallbackName, output) {
         throw new DownloadError("Unexpected download response");
     }
     const file = result;
-    // The fallback prefix embeds a user-supplied id (e.g. --report-id): sanitize it
-    // like server-provided names so an auto filename never interprets input as a path.
     const safeFallback = sanitizeFilename(fallbackName);
     if (typeof file.savedPath === "string") {
         process.stdout.write(`${file.savedPath}\n`);
         return;
     }
     if (file.data instanceof Uint8Array) {
-        // Sanitize the server-provided filename so a Content-Disposition value with
-        // / or : can't write outside the intended path (same rule as buildFilename).
         const autoName = (file.filename ? sanitizeFilename(file.filename) : undefined) ?? (safeFallback + extFromContentType(file.contentType));
         const outputPath = output ?? await uniquePath(truncateFilename(autoName));
         await saveOutputIfNeeded(file.data, outputPath);
@@ -216,9 +180,6 @@ export async function saveDownloadResult(result, fallbackName, output) {
     }
     if (typeof file.url === "string") {
         if (output) {
-            // The server handed us a (typically signed, short-lived) URL instead of the
-            // bytes. The user asked for a file — follow the URL and stream the content
-            // to disk instead of writing the URL string into a fake .pdf.
             await downloadUrlTo(file.url, output);
             process.stdout.write(`${output}\n`);
             return;