gangtise-openapi-cli 0.42.0 → 0.43.1

package/dist/src/commands/quote.js

@@ -7,7 +7,8 @@ import { ValidationError } from "../core/errors.js";
 import { flagMissingFields } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { emit, withClient, DEFAULT_QUOTE_LIMIT, flagIfLimitTruncated } from "./shared.js";
+import { rowCount } from "../core/rowSink.js";
+import { emit, withClient, DEFAULT_QUOTE_LIMIT, MAX_QUOTE_LIMIT, flagIfLimitTruncated, noteLateStart } from "./shared.js";
 export const quote = new Command("quote").description("Quote APIs");
 const KLINE_MARKETS = { aShares: 1, hkStocks: 2, usStocks: 1 };
 const LEGACY_ALL_MARKET = (shardDays) => ({ all: shardDays });
@@ -30,38 +31,61 @@ export const checkMarketKeywords = (securities, accepted, command, noKeywordReas
     }
 };
 const canonicalizeMarketKeywords = (securities, accepted) => securities.map((s) => accepted.find((a) => matchesMarketKeyword(s, a)) ?? s);
+function withIdentityFields(fieldList, identity, label) {
+    if (!fieldList)
+        return fieldList;
+    const missing = identity.filter((field) => !fieldList.includes(field));
+    if (missing.length === 0)
+        return fieldList;
+    const says = [missing.includes("securityCode") ? "security" : "", missing.some((f) => f !== "securityCode") ? "time" : ""].filter(Boolean).join(" and ");
+    process.stderr.write(`[gangtise] note: ${label} adds ${missing.join(", ")} to --field so each row says which ${says} it belongs to.\n`);
+    return [...missing, ...fieldList];
+}
 const addKlineCommand = (name, endpointKey, securityHelp, markets, noKeywordReason) => quote.command(name)
     .option("--security <code>", securityHelp, collectList, [])
     .option("--start-date <date>", "Start date (default: 1 year before end-date)", dateArg("--start-date"))
     .option("--end-date <date>", "End date (default: latest)", dateArg("--end-date"))
-    .option("--limit <number>", "Max rows per request (default: 6000, max: 10000)")
+    .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}). With several securities it also sizes the groups they are fetched in, so a small value fetches one security per request`)
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
     .option("--output <path>")
     .action((options) => {
     checkMarketKeywords(options.security, Object.keys(markets), `quote ${name}`, noKeywordReason);
     options.security = canonicalizeMarketKeywords(options.security, Object.keys(markets));
+    const fullMarketKeyword = Object.keys(markets).find((k) => options.security.includes(k));
+    if (fullMarketKeyword && (!options.startDate || !options.endDate)) {
+        throw new ValidationError(`quote ${name} --security ${fullMarketKeyword} requires both --start-date and --end-date (the full market is fetched via date shards; an unbounded whole-market request is rejected by the server)`);
+    }
     return withClient(options, async (client) => {
         const format = parseOutputFormat(options.format);
+        client.rowSink?.watchEarliest("tradeDate");
         const body = buildQuoteKlineBody(options);
+        const severalSecurities = (body.securityList?.length ?? 0) > 1 || fullMarketKeyword !== undefined;
+        body.fieldList = withIdentityFields(body.fieldList, severalSecurities ? ["securityCode", "tradeDate"] : [], `quote ${name}`);
         const keyword = Object.keys(markets).find((k) => isFullMarket(body, k));
         if (keyword) {
             const data = await callKlineWithSharding(client, endpointKey, body, { shardDays: markets[keyword], fullMarketValue: keyword });
             flagMissingFields(data, body.fieldList, `quote ${name}`);
+            noteLateStart(data, body.startDate, "tradeDate", `quote ${name}`);
             await printData(data, format, options.output);
             return;
         }
         const limit = body.limit ?? DEFAULT_QUOTE_LIMIT;
         const securities = body.securityList ?? [];
-        if (securities.length > 1 && securities.length * estimateTradingDays(body.startDate, body.endDate) > limit) {
-            const data = await callPerSecurity(client, endpointKey, securities, (code) => ({ ...body, securityList: [code], limit }), limit, `quote ${name}`);
+        const tradingDays = estimateTradingDays(body.startDate, body.endDate);
+        if (securities.length > 1 && securities.length * tradingDays >= limit) {
+            const cap = body.limit ?? MAX_QUOTE_LIMIT;
+            const groupSize = Math.max(1, Math.floor((cap - 1) / tradingDays));
+            const data = await callPerSecurity(client, endpointKey, securities, (codes) => ({ ...body, securityList: codes, limit: cap }), cap, `quote ${name}`, groupSize);
             flagMissingFields(data, body.fieldList, `quote ${name}`);
+            noteLateStart(data, body.startDate, "tradeDate", `quote ${name}`);
             await printData(data, format, options.output);
             return;
         }
         const data = await client.call(endpointKey, { ...body, limit });
         flagIfLimitTruncated(data, limit, name);
         flagMissingFields(data, body.fieldList, `quote ${name}`);
+        noteLateStart(data, body.startDate, "tradeDate", `quote ${name}`);
         await printData(data, format, options.output);
     });
 });
@@ -73,28 +97,33 @@ quote.command("minute-kline")
     .option("--security <code>", "Security code — A-share .SH/.SZ (SH/SZ only), ETF .SH/.SZ (e.g. 512800.SH), exchange index .SH/.SZ, concept index .GT, industry index .CI/.SWI, global index (e.g. SPX.SPI / N225.NKI / HSI.HI); repeat for several — one request each, run concurrently and merged; no whole-market keyword", collectList, [])
     .option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)", datetimeArg("--start-time"))
     .option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)", datetimeArg("--end-time"))
-    .option("--limit <number>", "Max rows per request (default: 6000, max: 10000)")
+    .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT})`)
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
     .option("--output <path>")
     .action((options) => withClient(options, async (client) => {
     const format = parseOutputFormat(options.format);
-    const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }) ?? DEFAULT_QUOTE_LIMIT;
-    const fieldList = maybeArray(options.field);
+    client.rowSink?.watchEarliest("tradeTime");
+    const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: MAX_QUOTE_LIMIT }) ?? DEFAULT_QUOTE_LIMIT;
     const securities = options.security;
     if (securities.length === 0)
         throw new ValidationError("--security is required (repeat it for several securities)");
+    const fieldList = withIdentityFields(maybeArray(options.field), securities.length > 1 ? ["securityCode", "tradeTime"] : [], "quote minute-kline");
     const makeBody = (code) => ({ securityCode: code, startTime: options.startTime, endTime: options.endTime, limit, fieldList });
     const data = securities.length === 1
         ? await client.call("quote.minute-kline", makeBody(securities[0]))
-        : await callPerSecurity(client, "quote.minute-kline", securities, makeBody, limit, "quote minute-kline");
+        : await callPerSecurity(client, "quote.minute-kline", securities, ([code]) => makeBody(code), limit, "quote minute-kline");
     if (securities.length === 1)
         flagIfLimitTruncated(data, limit, "minute-kline", "--start-time/--end-time");
     flagMissingFields(data, fieldList, "quote minute-kline");
+    noteLateStart(data, options.startTime, "tradeTime", "quote minute-kline");
+    if (rowCount(data) === 0 && (options.startTime || options.endTime)) {
+        process.stderr.write(`[gangtise] note: no minute bars came back. Minute bars cover a much shorter history than daily bars, and a range entirely before it returns nothing rather than an error — try a recent range to check.\n`);
+    }
     await printData(data, format, options.output);
 }));
 quote.command("realtime")
-    .description("Realtime quote snapshot (A-share / HK / US stocks, ETFs, and indices incl. 20 global indices)")
+    .description("Realtime quote snapshot (A-share / HK / US stocks, ETFs, and indices incl. global indices)")
     .option("--security <code>", "Security code — stock .SH/.SZ/.BJ/.HK/.O/.N/.A, ETF .SH/.SZ (e.g. 512800.SH), exchange index .SH/.SZ/.BJ, concept index .GT, industry index .CI/.SWI, global index (e.g. SPX.SPI / N225.NKI / HSI.HI); or one market keyword: aShares / hkStocks / usStocks (must be passed alone; keywords cover stocks only — ETFs and indices have no whole-market keyword)", collectList, [])
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
@@ -102,7 +131,9 @@ quote.command("realtime")
     .action((options) => {
     checkMarketKeywords(options.security, REALTIME_MARKETS, "quote realtime");
     return emit(options, async (client) => {
-        const fieldList = maybeArray(options.field);
+        const securities = options.security;
+        const severalSecurities = securities.length > 1 || securities.some((s) => REALTIME_MARKETS.some((keyword) => matchesMarketKeyword(s, keyword)));
+        const fieldList = withIdentityFields(maybeArray(options.field), severalSecurities ? ["securityCode"] : [], "quote realtime");
         const data = await client.call("quote.realtime", { securityList: maybeArray(options.security), fieldList });
         flagMissingFields(data, fieldList, "quote realtime");
         return data;
@@ -113,7 +144,7 @@ quote.command("fund-flow")
     .option("--security <code>", "Security code (e.g. 600519.SH / 920982.BJ), or 'aShares' for full A-share market — auto-sharded by day (repeat)", collectList, [])
     .option("--start-date <date>", "Start date yyyy-MM-dd (default: endDate minus 1 year)", dateArg("--start-date"))
     .option("--end-date <date>", "End date yyyy-MM-dd (default: latest trading day)", dateArg("--end-date"))
-    .option("--limit <number>", "Max rows per request (default: 6000, max: 10000; single-security cap — aShares auto-shards by day)")
+    .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}; single-security cap — aShares auto-shards by day)`)
     .option("--field <field>", "Field, e.g. mainNetInflow/largeInflow/xlargeOutflow (repeat); omit for all", collectList, [])
     .option("--format <format>", "Output format", "table")
     .option("--output <path>")
@@ -122,11 +153,12 @@ quote.command("fund-flow")
     options.security = canonicalizeMarketKeywords(options.security, FUND_FLOW_MARKETS);
     return withClient(options, async (client) => {
         const format = parseOutputFormat(options.format);
+        client.rowSink?.watchEarliest("tradeDate");
         const body = {
             securityList: maybeArray(options.security),
             startDate: options.startDate,
             endDate: options.endDate,
-            limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }),
+            limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: MAX_QUOTE_LIMIT }),
             fieldList: maybeArray(options.field),
         };
         if (isFullMarket(body, "aShares")) {
@@ -135,6 +167,7 @@ quote.command("fund-flow")
             }
             const data = await callKlineWithSharding(client, "quote.fund-flow", body, { shardDays: 1, fullMarketValue: "aShares" });
             flagMissingFields(data, body.fieldList, "quote fund-flow");
+            noteLateStart(data, body.startDate, "tradeDate", "quote fund-flow");
             await printData(data, format, options.output);
             return;
         }
@@ -142,6 +175,7 @@ quote.command("fund-flow")
         const data = await client.call("quote.fund-flow", { ...body, limit });
         flagIfLimitTruncated(data, limit, "fund-flow");
         flagMissingFields(data, body.fieldList, "quote fund-flow");
+        noteLateStart(data, body.startDate, "tradeDate", "quote fund-flow");
         await printData(data, format, options.output);
     });
 });

package/dist/src/commands/raw.js

@@ -6,14 +6,14 @@ import { flagFailedItems } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
 import { createClient, runDownload, assertConfirmed } from "./shared.js";
-export const raw = new Command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--yes", "Confirm an irreversible endpoint (required for the ones marked destructive)").option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
+export const raw = new Command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--yes", "Confirm an irreversible endpoint (required for the ones marked destructive), or fetch every row of a per-row billed list past the credit guard").option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
     const endpoint = ENDPOINTS[endpointKey];
     if (!endpoint) {
         throw new ConfigError(`Unknown endpoint key: ${endpointKey}`);
     }
     assertConfirmed(endpointKey, Boolean(options.yes), endpointKey);
     const format = parseOutputFormat(options.format);
-    const client = await createClient({ format, output: options.output });
+    const client = await createClient({ format, output: options.output, yes: Boolean(options.yes) });
     let body;
     if (options.body) {
         try {

package/dist/src/commands/shared.js

@@ -1,4 +1,5 @@
 import { Option } from "commander";
+import { QUOTE_MAX_LIMIT } from "../core/quoteSharding.js";
 import { collectList, dateArg, datetimeArg, maybeArray, numberListArg, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize } from "../core/args.js";
 import { loadConfig } from "../core/config.js";
 import { releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
@@ -6,15 +7,17 @@ import { ENDPOINTS } from "../core/endpoints.js";
 import { ValidationError } from "../core/errors.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { ExportSink } from "../core/rowSink.js";
+import { ExportSink, getRowSink } from "../core/rowSink.js";
 export async function createClient(stream) {
     const { GangtiseClient } = await import("../core/client.js");
     const sink = stream?.output && (stream.format === "jsonl" || stream.format === "csv") ? new ExportSink(stream.output, stream.format, stream.cache) : undefined;
-    return new GangtiseClient(loadConfig(), sink);
+    const client = new GangtiseClient(loadConfig(), sink);
+    client.allowCostlyFetch = Boolean(stream?.yes);
+    return client;
 }
 export async function emit(options, produce, cache) {
     const format = parseOutputFormat(options.format);
-    const client = await createClient({ format, output: options.output, cache });
+    const client = await createClient({ format, output: options.output, cache, yes: options.yes });
     try {
         await printData(await produce(client), format, options.output, cache);
     }
@@ -33,6 +36,7 @@ export async function withClient(a, b) {
     }
 }
 export const DEFAULT_QUOTE_LIMIT = 6000;
+export const MAX_QUOTE_LIMIT = QUOTE_MAX_LIMIT;
 export function flagIfLimitTruncated(data, cap, label, rangeFlags = "--start-date/--end-date", advice) {
     if (!data || typeof data !== "object" || Array.isArray(data))
         return;
@@ -44,6 +48,43 @@ export function flagIfLimitTruncated(data, cap, label, rangeFlags = "--start-dat
         process.stderr.write(`[gangtise] warning: ${label} returned ${rec.list.length} rows = the ${cap}-row limit; results are likely truncated (this endpoint has no pagination). ${advice ?? `Narrow ${rangeFlags} or raise --limit (max 10000), fetching in date batches.`}\n`);
     }
 }
+const LATE_START_DAYS = 14;
+export function earliestRowDate(data, field) {
+    const sink = getRowSink(data);
+    if (sink)
+        return sink.earliest(field);
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return undefined;
+    const rec = data;
+    if (!Array.isArray(rec.list))
+        return undefined;
+    const index = Array.isArray(rec.fieldList) ? rec.fieldList.indexOf(field) : -1;
+    let earliest;
+    for (const row of rec.list) {
+        const value = Array.isArray(row) ? (index >= 0 ? row[index] : undefined) : row && typeof row === "object" ? row[field] : undefined;
+        if (typeof value !== "string")
+            continue;
+        const day = value.slice(0, 10);
+        if (earliest === undefined || day < earliest)
+            earliest = day;
+    }
+    return earliest;
+}
+export function noteLateStart(data, requestedStart, field, label) {
+    const failedShards = data?.failedShards;
+    if (Array.isArray(failedShards) && failedShards.length > 0)
+        return;
+    const start = requestedStart?.slice(0, 10);
+    if (!start || !/^\d{4}-\d{2}-\d{2}$/.test(start))
+        return;
+    const first = earliestRowDate(data, field);
+    if (!first || !/^\d{4}-\d{2}-\d{2}$/.test(first))
+        return;
+    const lateDays = (Date.parse(`${first}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000;
+    if (lateDays <= LATE_START_DAYS)
+        return;
+    process.stderr.write(`[gangtise] note: ${label} starts at ${first}, ${lateDays} days after the requested start ${start}. The security may have listed or resumed trading later, or the range reaches past your account's history window for this data — the endpoint returns what lies inside the window without an error.\n`);
+}
 export async function runDownload(client, endpointKey, query, options) {
     if (options.output) {
         const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
@@ -68,8 +109,10 @@ export function addDownloadCommand(parent, spec) {
         const option = new Option("--file-type <number>", spec.fileType.description).choices(spec.fileType.choices);
         cmd.addOption(spec.fileType.required ? option.makeOptionMandatory() : option.default(spec.fileType.default));
     }
-    if (spec.contentTypeDescription)
-        cmd.requiredOption("--content-type <type>", spec.contentTypeDescription);
+    if (spec.contentTypeDescription) {
+        const option = new Option("--content-type <type>", spec.contentTypeDescription).makeOptionMandatory();
+        cmd.addOption(spec.contentTypeChoices ? option.choices(spec.contentTypeChoices) : option);
+    }
     if (spec.titleListEndpoint) {
         cmd.option("--resolve-title", "On a title-cache miss, query the list endpoint for a friendly filename (4 extra requests; most of these list endpoints bill per row). Without it the server filename or <prefix>-<id> is used. Ignored when --output is given");
     }
@@ -97,6 +140,7 @@ export function assertConfirmed(endpointKey, confirmed, target) {
     throw new ValidationError(`${destructive.warning} 确认要对 ${target} 执行就加上 --yes。`);
 }
 export const field = (option, body) => ({ option, body });
+export const confirmCostly = () => field(new Option("--yes", "Fetch every row even when a fetch without --size is estimated above the credit guard (the list is billed per row)"));
 export const value = (flags, description, key) => field(new Option(flags, description), (v) => ({ [key]: v }));
 export const required = (flags, description, key) => field(new Option(flags, description).makeOptionMandatory(), (v) => ({ [key]: v }));
 export const date = (flags, description, key, opts = {}) => {
@@ -110,8 +154,14 @@ export const numberList = (flags, description, key) => {
     option.argParser(numberListArg(option.long));
     return field(option, (v) => ({ [key]: v.length ? v : undefined }));
 };
-export const choiceList = (flags, description, key, choices) => {
+export const multiChoiceValues = new WeakMap();
+export function multiChoice(flags, description, choices) {
     const option = new Option(flags, description).argParser(collectList).default([]);
+    multiChoiceValues.set(option, choices);
+    return option;
+}
+export const choiceList = (flags, description, key, choices) => {
+    const option = multiChoice(flags, description, choices);
     return field(option, (v) => ({ [key]: parseChoiceList(v, option.long, choices) }));
 };
 export const count = (flags, description, key) => {
@@ -139,7 +189,9 @@ export function query(parent, name, spec) {
     const command = parent.command(name);
     if (spec.description)
         command.description(spec.description);
-    for (const f of spec.fields)
+    const defaultEndpoint = ENDPOINTS[typeof spec.endpoint === "string" ? spec.endpoint : spec.endpoint({})];
+    const fields = defaultEndpoint?.pagination?.enabled && defaultEndpoint.billing?.per === "row" ? [...spec.fields, confirmCostly()] : spec.fields;
+    for (const f of fields)
         command.addOption(f.option);
-    return command.action((options) => emit(options, (client) => client.call(typeof spec.endpoint === "string" ? spec.endpoint : spec.endpoint(options), requestBody(spec.fields, options)), spec.cache));
+    return command.action((options) => emit(options, (client) => client.call(typeof spec.endpoint === "string" ? spec.endpoint : spec.endpoint(options), requestBody(fields, options)), spec.cache));
 }

package/dist/src/commands/vault.js

@@ -111,7 +111,7 @@ query(vault, "record-list", {
         format(), output(),
     ],
 });
-addDownloadCommand(vault, { endpointKey: "vault.record.download", name: "record-download", idOption: "--record-id", idField: "recordId", fallbackPrefix: "record", contentTypeDescription: "Content type: original/asr/summary", titleListEndpoint: "vault.record.list" });
+addDownloadCommand(vault, { endpointKey: "vault.record.download", name: "record-download", idOption: "--record-id", idField: "recordId", fallbackPrefix: "record", contentTypeDescription: "Content type: original/asr/summary", contentTypeChoices: ["original", "asr", "summary"], titleListEndpoint: "vault.record.list" });
 query(vault, "my-conference-list", {
     endpoint: "vault.my-conference.list",
     cache: { endpointKey: "vault.my-conference.list", idField: "conferenceId" },
@@ -125,7 +125,7 @@ query(vault, "my-conference-list", {
         format(), output(),
     ],
 });
-addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "my-conference-download", idOption: "--conference-id", idField: "conferenceId", fallbackPrefix: "conference", contentTypeDescription: "Content type: asr/summary", titleListEndpoint: "vault.my-conference.list" });
+addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "my-conference-download", idOption: "--conference-id", idField: "conferenceId", fallbackPrefix: "conference", contentTypeDescription: "Content type: asr/summary", contentTypeChoices: ["asr", "summary"], titleListEndpoint: "vault.my-conference.list" });
 vault.command("wechat-message-list")
     .option("--from <number>", "Starting offset", "0")
     .option("--size <number>", "Total rows to return; omit to fetch all")

package/dist/src/core/args.js

@@ -84,11 +84,14 @@ export function isVersionNewer(latest, current) {
 export function parseChoiceList(values, optionName, allowed) {
     for (const value of values) {
         if (!allowed.includes(value)) {
-            throw new ValidationError(`Invalid ${optionName}: "${value}" is not one of ${allowed.join("/")}`);
+            throw new ValidationError(`Invalid ${optionName}: "${value}". ${unknownChoiceMessage(allowed)}`);
         }
     }
     return maybeArray(values);
 }
+export function unknownChoiceMessage(known) {
+    return `This CLI version knows ${known.join(", ")}. Check the spelling; if the platform has added a new value, report it so the CLI can be updated.`;
+}
 const YEAR_FIRST_DATE = /^(\d{4})([-/]?)(\d{2})\2(\d{2})$/;
 function normalizeYearFirstDate(value) {
     const parts = YEAR_FIRST_DATE.exec(value);
@@ -172,10 +175,8 @@ export function parseDatetimeOption(value, optionName) {
 export function datetimeArg(optionName) {
     return (value) => parseDatetimeOption(value, optionName);
 }
-export function localDateString(d) {
-    const month = String(d.getMonth() + 1).padStart(2, "0");
-    const day = String(d.getDate()).padStart(2, "0");
-    return `${d.getFullYear()}-${month}-${day}`;
+export function beijingDateString(d) {
+    return new Date(d.getTime() + 8 * 60 * 60 * 1000).toISOString().slice(0, 10);
 }
 function parseParamSpecs(specs, option, syntax) {
     const groups = new Map();

package/dist/src/core/auth.js

@@ -1,7 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
+import { stagingPath } from "./output.js";
 export function credentialFingerprint(accessKey, baseUrl) {
     return createHash("sha256").update(`${accessKey}\u0000${baseUrl}`).digest("hex").slice(0, 16);
 }
@@ -30,7 +31,7 @@ export function redactTokenCache(cache) {
 }
 export async function writeTokenCache(filePath, cache) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    const tmp = `${filePath}.tmp-${randomUUID()}`;
+    const tmp = stagingPath(filePath, "tmp");
     await fs.writeFile(tmp, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
     try {
         await fs.rename(tmp, filePath);

package/dist/src/core/client.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { createWriteStream } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -17,9 +18,32 @@ function hasExpectedShape(expects, payload) {
         return Array.isArray(payload);
     return Boolean(payload && typeof payload === "object" && Array.isArray(payload.list));
 }
+export const COSTLY_FETCH_CREDITS = 1000;
+const PROBE_ABOVE_CREDITS = 50;
+const OFFSET_REFUSAL_CODES = new Set(["140002", "100006"]);
+function readEmptyListAsArray(page) {
+    const rec = page;
+    if (rec && typeof rec === "object" && rec.total === 0 && rec.list === null)
+        rec.list = [];
+}
+function markTotalCapped(out, why, collected, keepBelow) {
+    process.stderr.write(`[gangtise] warning: ${why}. This export is TRUNCATED at ${collected} rows. Narrow the query (e.g. a shorter time range) until total stays below ${keepBelow}, and fetch in slices.\n`);
+    out.partial = true;
+    out.totalCapped = true;
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (value && typeof value === "object") {
+        const obj = value;
+        return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
 export class GangtiseClient {
     config;
     rowSink;
+    allowCostlyFetch = false;
     refreshPromise = null;
     memoCache = null;
     envTokenInvalidated = false;
@@ -168,12 +192,39 @@ export class GangtiseClient {
             throw new ValidationError(`${endpoint.key} serves rows only up to offset ${maxWindow} (from + size ≤ ${maxWindow}); --from ${startFrom} is past it. Narrow the query (e.g. a shorter time range) instead of paging deeper.`);
         }
         const windowRoom = maxWindow === undefined ? Infinity : maxWindow - startFrom;
-        const firstPageSize = Math.min(requestedSize === undefined ? maxPageSize : Math.min(maxPageSize, requestedSize), windowRoom);
-        const firstPage = await this.requestJson(endpoint, {
+        const billing = endpoint.billing;
+        const guarded = requestedSize === undefined && billing?.per === "row" && !this.allowCostlyFetch;
+        const refuseIfCostly = (reportedTotal, fetched) => {
+            if (!guarded || !billing)
+                return;
+            const rows = Math.min(Math.max(reportedTotal - startFrom, 0), windowRoom);
+            const estimatedCredits = Math.round(rows * billing.price * 100) / 100;
+            if (estimatedCredits <= COSTLY_FETCH_CREDITS)
+                return;
+            throw new ValidationError(`fetching all ${rows} rows of ${endpoint.key} would cost about ${estimatedCredits} credits (${billing.price} per row), above the ${COSTLY_FETCH_CREDITS}-credit guard for a fetch without --size. Only ${fetched} row(s) were fetched, to learn the total. Pass --size N for a bounded subset, or --yes to fetch them all.`);
+        };
+        let probe;
+        let probed = false;
+        let probeRows = 0;
+        if (guarded && billing && Math.min(maxPageSize, windowRoom) * billing.price > PROBE_ABOVE_CREDITS) {
+            probe = await this.requestJson(endpoint, { ...initialBody, from: startFrom, size: 1 });
+            readEmptyListAsArray(probe);
+            if (!this.isPaginatedListResponse(probe)) {
+                probed = true;
+            }
+            else {
+                refuseIfCostly(probe.total, probe.list.length);
+                probeRows = probe.list.length;
+                probed = probe.list.length === Math.min(Math.max(probe.total - startFrom, 0), windowRoom);
+            }
+        }
+        const firstPageSize = probed ? 1 : Math.min(requestedSize === undefined ? maxPageSize : Math.min(maxPageSize, requestedSize), windowRoom);
+        const firstPage = probed ? probe : await this.requestJson(endpoint, {
             ...initialBody,
             from: startFrom,
             size: firstPageSize,
         });
+        readEmptyListAsArray(firstPage);
         if (!this.isPaginatedListResponse(firstPage)) {
             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`);
             markIncomplete();
@@ -195,7 +246,45 @@ export class GangtiseClient {
             sink.setFieldList(firstPage.fieldList);
         const collected = [];
         let count = 0;
-        const keep = async (rows) => {
+        const rowId = endpoint.rowId;
+        const seen = rowId ? new Map() : undefined;
+        let duplicateRows = 0;
+        let changedRows = 0;
+        let idIsRowKey = true;
+        const dropRepeats = (rows) => {
+            if (!seen || !rowId)
+                return rows;
+            const onThisPage = new Map();
+            return rows.filter((row) => {
+                const id = row && typeof row === "object" ? row[rowId] : undefined;
+                if (id === undefined || id === null)
+                    return true;
+                const digest = createHash("sha1").update(stableStringify(row)).digest("base64");
+                const key = String(id);
+                const pageVersions = onThisPage.get(key);
+                if (pageVersions && !pageVersions.has(digest))
+                    idIsRowKey = false;
+                if (pageVersions)
+                    pageVersions.add(digest);
+                else
+                    onThisPage.set(key, new Set([digest]));
+                const versions = seen.get(key);
+                if (versions === undefined) {
+                    seen.set(key, new Set([digest]));
+                    return true;
+                }
+                if (versions.has(digest)) {
+                    duplicateRows++;
+                    return false;
+                }
+                versions.add(digest);
+                if (!pageVersions)
+                    changedRows++;
+                return true;
+            });
+        };
+        const keep = async (fetched) => {
+            const rows = dropRepeats(fetched);
             const kept = requestedSize === undefined ? rows : rows.slice(0, Math.max(0, requestedSize - count));
             if (kept.length === 0)
                 return;
@@ -209,10 +298,20 @@ export class GangtiseClient {
         const checkTotalCap = async (out) => {
             if (probeFits)
                 return this.flagIfTotalCapped(endpoint, initialBody, total, out, count);
-            process.stderr.write(`[gangtise] note: ${endpoint.key} reported total=${total}, which reaches its ${maxWindow}-row offset window, so whether that is the real count cannot be checked. Narrow the query (e.g. a shorter time range) to keep total below ${maxWindow} if you need to be sure.\n`);
+            markTotalCapped(out, `${endpoint.key} reported total=${total}, which equals its ${maxWindow}-row offset window: rows past it can be neither fetched nor counted`, count, maxWindow);
         };
         const result = () => {
             const out = { ...firstPage, total, list: collected };
+            if (duplicateRows > 0) {
+                process.stderr.write(`[gangtise] warning: ${endpoint.key} returned ${duplicateRows} row(s) more than once — its sort order is not unique, so paging also missed as many rows. The duplicates were dropped and the result is partial. Re-run over a shorter time range to fetch the missing rows.\n`);
+                out.duplicateRows = duplicateRows;
+                out.partial = true;
+            }
+            if (changedRows > 0 && idIsRowKey && !endpoint.rowIdUnverified) {
+                process.stderr.write(`[gangtise] warning: ${endpoint.key} returned ${changedRows} row(s) whose ${rowId} came back on a later page with different content — the list changed while it was being paged, so rows may also have been missed. Both versions were kept (deduplicating by ${rowId} keeps one) and the result is partial. Re-run to fetch a consistent result.\n`);
+                out.changedRows = changedRows;
+                out.partial = true;
+            }
             return sink ? attachRowSink(out, sink) : out;
         };
         await keep(firstPage.list);
@@ -232,6 +331,7 @@ export class GangtiseClient {
                 await checkTotalCap(out);
             return out;
         }
+        refuseIfCostly(total, count + (probed ? 0 : probeRows));
         const MAX_PAGES = 1000;
         let truncatedByPageCap = false;
         const pageRequests = [];
@@ -264,6 +364,7 @@ export class GangtiseClient {
                     from: req.from,
                     size: req.size,
                 });
+                readEmptyListAsArray(page);
                 if (!this.isPaginatedListResponse(page)) {
                     unexpectedShape = true;
                     failedPages.push(req);
@@ -293,9 +394,10 @@ export class GangtiseClient {
             process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${count} of ${total} rows. Narrow the query (e.g. a shorter date range) or pass --size to fetch a bounded subset.\n`);
         }
         const short = count < target;
+        const shortByRepeatsOnly = short && count + duplicateRows >= target;
         const out = result();
         flagWindowCut(out);
-        if (requestedSize === undefined && total > 0 && target === wanted && !short && !totalDrift && !truncatedByPageCap && failedPages.length === 0) {
+        if (requestedSize === undefined && total > 0 && target === wanted && (!short || shortByRepeatsOnly) && !totalDrift && !truncatedByPageCap && failedPages.length === 0) {
             await checkTotalCap(out);
         }
         if (short || totalDrift || failedPages.length > 0)
@@ -310,7 +412,7 @@ export class GangtiseClient {
             const skippedHint = aborted ? " A page hit a non-retryable error (e.g. rate limit); remaining pages were skipped." : "";
             process.stderr.write(`[gangtise] warning: ${failedPages.length}/${pageRequests.length} pages not fetched${detail}; results are partial — got ${count}/${total} rows (see failedPages).${skippedHint}\n`);
         }
-        else if (short && !truncatedByPageCap && !totalDrift) {
+        else if (short && !shortByRepeatsOnly && !truncatedByPageCap && !totalDrift) {
             process.stderr.write(`[gangtise] warning: server returned ${count} of ${total} rows (a later page came back short); results may be incomplete\n`);
         }
         return out;
@@ -322,13 +424,14 @@ export class GangtiseClient {
             if (this.isPaginatedListResponse(probe) && probe.list.length > 0)
                 totalCapped = true;
         }
-        catch {
+        catch (error) {
+            if (error instanceof ApiError && error.code !== undefined && OFFSET_REFUSAL_CODES.has(error.code)) {
+                markTotalCapped(out, `${endpoint.key} reported total=${total} and refused the row right after it (${error.code}) — most likely a server-side offset window at total, so rows past it may exist and can be neither fetched nor counted`, collectedLength, total);
+            }
         }
         if (!totalCapped)
             return;
-        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 ${collectedLength} rows. Narrow the query (date range / filters) and fetch in slices.\n`);
-        out.partial = true;
-        out.totalCapped = true;
+        markTotalCapped(out, `${endpoint.key} reported total=${total} but rows exist past that offset — 'total' is a server-side cap, not the real count`, collectedLength, total);
     }
     async login() {
         if (this.config.token && !this.envTokenInvalidated) {
@@ -420,7 +523,7 @@ export class GangtiseClient {
         }).catch((error) => {
             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 都没被识别。');
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名会报 100003 并指名）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意此码不表示无数据——无数据返回保留行列的 null 单元格；code 或参数名写错报 100003、缺必填参数报 100001，都会指名（fiscalYear 例外：漏传不报错，返回 null 或默认年度的值）。');
             }
             throw error;
         });

package/dist/src/core/commandBodies.js

@@ -1,11 +1,12 @@
 import { maybeArray, parseFrom, parseIndicatorParams, parseOptionalNumberOption, parseScreenerIndicators, parseSize } from "./args.js";
 import { ValidationError } from "./errors.js";
+import { QUOTE_MAX_LIMIT } from "./quoteSharding.js";
 export function buildQuoteKlineBody(options) {
     return {
         securityList: maybeArray(options.security),
         startDate: options.startDate,
         endDate: options.endDate,
-        limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }),
+        limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: QUOTE_MAX_LIMIT }),
         fieldList: maybeArray(options.field),
     };
 }