gangtise-openapi-cli 0.41.1 → 0.43.0

package/dist/src/commands/insight.js

@@ -0,0 +1,338 @@
+import { Command } from "commander";
+import { collectList, dateArg, maybeArray, parseChoiceList, parseFrom, parseSize, parseTimestamp13 } from "../core/args.js";
+import { ValidationError } from "../core/errors.js";
+import { fetchOpinionDetails } from "../core/opinionDetail.js";
+import { rowCount } from "../core/rowSink.js";
+import { emit, addDownloadCommand, confirmCostly, multiChoice, value, required, list, numberList, choiceList, count, rankType, searchType, top, flag, format, output, from, size, startTime, endTime, timeFilters, query } from "./shared.js";
+export const insight = new Command("insight").description("Insight APIs");
+const RESEARCH_AREA_CITIC_OR_DIRECTION = "Research area ID: citicIndustry code (1008001xx) or gangtiseIndustry direction code (122000xxx: macro/strategy/fixed-income/quant/overseas). swIndustry (104xx0000) returns 0 here";
+const SW_INDUSTRY_ONLY = "Industry ID -- swIndustry codes only (104xx0000); citicIndustry codes are rejected with 100005 even where constant-category declares them";
+const opinion = new Command("opinion");
+const summary = new Command("summary");
+const pamirsSummary = new Command("pamirs-summary");
+const roadshow = new Command("roadshow");
+const siteVisit = new Command("site-visit");
+const strategy = new Command("strategy");
+const forum = new Command("forum");
+const performanceCalendar = new Command("performance-calendar");
+const research = new Command("research");
+const foreignReport = new Command("foreign-report");
+const announcement = new Command("announcement");
+const announcementHk = new Command("announcement-hk");
+const announcementUs = new Command("announcement-us");
+const foreignOpinion = new Command("foreign-opinion");
+const independentOpinion = new Command("independent-opinion");
+const officialAccount = new Command("official-account");
+const qa = new Command("qa");
+const reportImage = new Command("report-image");
+query(opinion, "list", {
+    endpoint: (options) => options.withContent ? "insight.opinion.list-with-content" : "insight.opinion.list",
+    fields: [
+        rankType(),
+        list("--research-area <id>", RESEARCH_AREA_CITIC_OR_DIRECTION, "researchAreaList"),
+        list("--chief <id>", "Chief ID", "chiefList"),
+        list("--security <code>", "Security code", "securityList"),
+        list("--broker <id>", "Broker ID", "brokerList"),
+        list("--industry <id>", "Industry ID", "industryList"),
+        list("--concept <id>", "Concept ID", "conceptList"),
+        list("--llm-tag <tag>", "Semantic tag", "llmTagList"),
+        list("--source <source>", "Source", "sourceList"),
+        flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) instead of the 200-char brief (1 credit/row). v1 shape: title and body sit under contentList.title / contentList.content, and there is no brief"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+query(summary, "list", {
+    endpoint: "insight.summary.list",
+    cache: { endpointKey: "insight.summary.list", idField: "summaryId" },
+    fields: [
+        searchType(), rankType(),
+        numberList("--source <number>", "Source type", "sourceList"),
+        list("--research-area <id>", "Research area ID; this endpoint accepts all three code sets: citicIndustry (1008001xx), swIndustry (104xx0000), gangtiseIndustry direction (122000xxx)", "researchAreaList"),
+        list("--security <code>", "Security code", "securityList"),
+        list("--institution <id>", "Institution ID", "institutionList"),
+        list("--category <name>", "Category", "categoryList"),
+        list("--market <name>", "Market", "marketList"),
+        list("--participant-role <name>", "Participant role", "participantRoleList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(summary, { endpointKey: "insight.summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "summary", fileType: { description: "File type: 1=original(default) 2=HTML; only affects meeting platform summaries", choices: ["1", "2"] }, titleListEndpoint: "insight.summary.list" });
+const PAMIRS_CATEGORIES = ["companyAnalysis", "industryAnalysis"];
+const PAMIRS_MARKETS = ["aShares", "hkStocks", "usChinaConcept", "usStocks"];
+query(pamirsSummary, "list", {
+    description: "List Pamirs expert summaries (requires the expert-summary database)",
+    endpoint: "insight.pamirs-summary.list",
+    cache: { endpointKey: "insight.pamirs-summary.list", idField: "summaryId" },
+    fields: [
+        searchType(), rankType(),
+        list("--research-area <id>", "Research area ID: accepts BOTH industry code sets -- citicIndustry (1008001xx) and swIndustry (104xx0000) -- but NOT gangtiseIndustry direction codes (122000xxx), which return 0 on this endpoint only", "researchAreaList"),
+        list("--security <code>", "Security code, e.g. 000001.SZ", "securityList"),
+        choiceList("--category <name>", `Category: ${PAMIRS_CATEGORIES.join(" / ")}`, "categoryList", PAMIRS_CATEGORIES),
+        choiceList("--market <name>", `Market: ${PAMIRS_MARKETS.join(" / ")}`, "marketList", PAMIRS_MARKETS),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(pamirsSummary, { endpointKey: "insight.pamirs-summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "pamirs-summary", fileType: { description: "File type: 1=original(default) 2=HTML", choices: ["1", "2"] }, titleListEndpoint: "insight.pamirs-summary.list" });
+const addScheduleList = (command, endpointKey, fields) => query(command, "list", {
+    endpoint: endpointKey,
+    fields: [
+        fields.researchArea && list("--research-area <id>", RESEARCH_AREA_CITIC_OR_DIRECTION, "researchAreaList"),
+        fields.institution && list("--institution <id>", "Lead institution ID", "institutionList"),
+        fields.security && list("--security <code>", "Security code", "securityList"),
+        fields.object && list("--object <type>", "Object type: company/industry", "objectList"),
+        fields.category && list("--category <name>", fields.category, "categoryList"),
+        fields.market && list("--market <name>", fields.market, "marketList"),
+        fields.participantRole && list("--participant-role <name>", "Participant role: management/expert", "participantRoleList"),
+        fields.brokerType && list("--broker-type <name>", "Lead broker type: cnBroker/otherBroker", "brokerTypeList"),
+        fields.permission && numberList("--permission <number>", "Permission: 1=public 2=private", "permission"),
+        fields.location && list("--location <id>", "Location ID (domesticCity constant, via 'reference constant-list')", "locationList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ].filter((f) => Boolean(f)),
+});
+addScheduleList(roadshow, "insight.roadshow.list", {
+    researchArea: true, institution: true, security: true, location: true,
+    category: "Roadshow type: earningsCall/strategyMeeting/companyAnalysis/industryAnalysis/fundRoadshow",
+    market: "Market: aShares/hkStocks/usChinaConcept/usStocks",
+    participantRole: true, brokerType: true, permission: true,
+});
+addScheduleList(siteVisit, "insight.site-visit.list", {
+    researchArea: true, institution: true, security: true, location: true, object: true,
+    category: "Site-visit form: single/series",
+    market: "Market: aShares/hkStocks/usChinaConcept",
+    permission: true,
+});
+addScheduleList(strategy, "insight.strategy.list", { institution: true, location: true });
+addScheduleList(forum, "insight.forum.list", { researchArea: true, location: true });
+const SECURITY_ONLY_ROW_CAP = 1000;
+function flagIfImplicitCapHit(data, cap, from) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const rec = data;
+    const rows = rowCount(data);
+    if (rows < cap)
+        return;
+    const total = typeof rec.total === "number" ? rec.total : undefined;
+    if (total !== undefined && from + rows >= total)
+        return;
+    rec.partial = true;
+    process.stderr.write(`[gangtise] warning: --security was the only bound, so the fetch was capped at ${cap} rows and more remain (total=${String(rec.total)}) — the filter may not have narrowed anything. Re-run with --start-date/--end-date or an explicit --size.\n`);
+}
+const PERFORMANCE_MARKETS = ["aShares", "hkStocks", "usChinaConcept", "usStocks"];
+const PERFORMANCE_CATEGORIES = ["performanceForecast", "performanceExpress", "performanceAnnouncement"];
+performanceCalendar.command("list").description("Earnings calendar (业绩预告 / 快报 / 公告)")
+    .option("--from <number>", "Starting offset", "0")
+    .option("--size <number>", "Total rows to return; omit to fetch all")
+    .option("--start-date <date>", "Start date (yyyy-MM-dd), filters publishDate", dateArg("--start-date"))
+    .option("--end-date <date>", "End date (yyyy-MM-dd), filters publishDate", dateArg("--end-date"))
+    .option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, [])
+    .addOption(multiChoice("--market <name>", `Market: ${PERFORMANCE_MARKETS.join("/")}`, PERFORMANCE_MARKETS))
+    .addOption(multiChoice("--category <name>", `Event type: ${PERFORMANCE_CATEGORIES.join("/")}`, PERFORMANCE_CATEGORIES))
+    .option("--format <format>", "Output format", "table").option("--output <path>", "Output path")
+    .addOption(confirmCostly().option)
+    .action((options) => {
+    const marketList = parseChoiceList(options.market, "--market", PERFORMANCE_MARKETS);
+    const categoryList = parseChoiceList(options.category, "--category", PERFORMANCE_CATEGORIES);
+    const explicitlyBounded = Boolean(options.size) || Boolean(options.startDate && options.endDate);
+    if (!explicitlyBounded && !options.security.length) {
+        throw new ValidationError("insight performance-calendar list without a bound would auto-paginate the whole calendar (over a hundred thousand rows at 0.1 credits each): pass --start-date and --end-date, or --security, or an explicit --size");
+    }
+    const implicitCap = explicitlyBounded ? undefined : SECURITY_ONLY_ROW_CAP;
+    const from = parseFrom(options.from);
+    return emit(options, async (client) => {
+        const data = await client.call("insight.performance-calendar.list", {
+            from, size: parseSize(options.size) ?? implicitCap,
+            startDate: options.startDate, endDate: options.endDate,
+            marketList,
+            securityList: maybeArray(options.security),
+            categoryList,
+        });
+        if (implicitCap)
+            flagIfImplicitCapHit(data, implicitCap, from);
+        return data;
+    }, { endpointKey: "insight.performance-calendar.list", idField: "performanceReportId" });
+});
+addDownloadCommand(performanceCalendar, { endpointKey: "insight.performance-calendar.download", idOption: "--performance-report-id", idField: "performanceReportId", fallbackPrefix: "performance-calendar", titleListEndpoint: "insight.performance-calendar.list" });
+query(research, "list", {
+    endpoint: "insight.research.list",
+    cache: { endpointKey: "insight.research.list", idField: "reportId" },
+    fields: [
+        searchType(), rankType(),
+        list("--broker <id>", "Broker ID", "brokerList"),
+        list("--security <code>", "Security code", "securityList"),
+        list("--industry <id>", "Industry ID", "industryList"),
+        list("--category <name>", "Report category", "categoryList"),
+        list("--llm-tag <tag>", "Semantic tag", "llmTagList"),
+        list("--rating <name>", "Rating", "ratingList"),
+        list("--rating-change <name>", "Rating change", "ratingChangeList"),
+        count("--min-pages <number>", "Min report pages", "minReportPages"),
+        count("--max-pages <number>", "Max report pages", "maxReportPages"),
+        list("--source <type>", "Source type", "sourceList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(research, { endpointKey: "insight.research.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "research", fileType: { description: "File type: 1=PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.research.list" });
+query(foreignReport, "list", {
+    endpoint: "insight.foreign-report.list",
+    cache: { endpointKey: "insight.foreign-report.list", idField: "reportId" },
+    fields: [
+        searchType(), rankType(),
+        list("--security <code>", "Security code", "securityList"),
+        list("--region <id>", "Region ID", "regionList"),
+        list("--category <name>", "Report category", "categoryList"),
+        list("--industry <id>", "Industry ID", "industryList"),
+        list("--broker <id>", "Broker ID", "brokerList"),
+        list("--llm-tag <tag>", "Semantic tag", "llmTagList"),
+        list("--rating <name>", "Rating", "ratingList"),
+        list("--rating-change <name>", "Rating change", "ratingChangeList"),
+        count("--min-pages <number>", "Min report pages", "minReportPages"),
+        count("--max-pages <number>", "Max report pages", "maxReportPages"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", choices: ["1", "2", "3", "4"], default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
+query(announcement, "list", {
+    endpoint: "insight.announcement.list",
+    cache: { endpointKey: "insight.announcement.list", idField: "announcementId" },
+    fields: [
+        searchType(), rankType(),
+        list("--security <code>", "Security code", "securityList"),
+        list("--category <id>", "Category ID", "categoryList"),
+        format(), output("Output path"),
+        ...timeFilters(parseTimestamp13),
+    ],
+});
+addDownloadCommand(announcement, { endpointKey: "insight.announcement.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement", fileType: { description: "File type: 1=PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement.list" });
+query(announcementHk, "list", {
+    endpoint: "insight.announcement-hk.list",
+    cache: { endpointKey: "insight.announcement-hk.list", idField: "announcementId" },
+    fields: [
+        searchType(), rankType(),
+        list("--security <code>", "Security code (e.g. 01913.HK)", "securityList"),
+        list("--category <id>", "Category ID", "categoryList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(announcementHk, { endpointKey: "insight.announcement-hk.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-hk", fileType: { description: "File type: 1=original 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement-hk.list" });
+query(announcementUs, "list", {
+    endpoint: "insight.announcement-us.list",
+    cache: { endpointKey: "insight.announcement-us.list", idField: "announcementId" },
+    fields: [
+        searchType(), rankType(),
+        list("--security <code>", "Security code (e.g. TSLA.O)", "securityList"),
+        list("--category <id>", "Category ID (constant-list usShareAnnouncementCategory)", "categoryList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(announcementUs, { endpointKey: "insight.announcement-us.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-us", fileType: { description: "File type: 1=original PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement-us.list" });
+query(foreignOpinion, "list", {
+    endpoint: (options) => options.withContent ? "insight.foreign-opinion.list-with-content" : "insight.foreign-opinion.list",
+    fields: [
+        rankType(),
+        list("--security <code>", "Security code (e.g. UBER.N)", "securityList"),
+        list("--region <code>", "Region code -- this endpoint accepts only cn/cnHk/cnTw/us/jp/uk; the other 13 values of regionCategory (sea/gl/fr/de/kr/in/ca/me/othAs/othEur/latAm/oce/af) are rejected here with 100005 though they all work on foreign-report", "regionList"),
+        list("--industry <id>", SW_INDUSTRY_ONLY, "industryList"),
+        list("--broker <id>", "Broker ID", "brokerList"),
+        list("--rating <name>", "Rating", "ratingList"),
+        list("--rating-change <name>", "Rating change", "ratingChangeList"),
+        flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) as content / contentTranslate, instead of the 200-char brief (1 credit/row)"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+opinion.command("detail").description("Full bodies of domestic chief opinions by ID (30 credits per returned opinion; batched 20 per call)")
+    .requiredOption("--chief-opinion-id <id>", "chiefOpinionId from 'insight opinion list' (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.opinion.detail", "chiefOpinionIdList", "chiefOpinionId", options.chiefOpinionId)));
+foreignOpinion.command("detail").description("Full bodies (content + contentTranslate) of foreign opinions by ID (30 credits per returned opinion; batched 20 per call)")
+    .requiredOption("--foreign-opinion-id <id>", "foreignOpinionId from 'insight foreign-opinion list' (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.foreign-opinion.detail", "foreignOpinionIdList", "foreignOpinionId", options.foreignOpinionId)));
+query(independentOpinion, "list", {
+    endpoint: "insight.independent-opinion.list",
+    fields: [
+        rankType(),
+        list("--security <code>", "Security code (e.g. GSK.N)", "securityList"),
+        list("--industry <id>", SW_INDUSTRY_ONLY, "industryList"),
+        list("--rating <name>", "Rating", "ratingList"),
+        list("--rating-change <name>", "Rating change", "ratingChangeList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(independentOpinion, { endpointKey: "insight.independent-opinion.download", idOption: "--independent-opinion-id", idField: "independentOpinionId", fallbackPrefix: "independent-opinion", fileType: { description: "File type: 1=original HTML 2=CN-translated HTML", choices: ["1", "2"], required: true } });
+query(officialAccount, "list", {
+    endpoint: "insight.official-account.list",
+    cache: { endpointKey: "insight.official-account.list", idField: "articleId" },
+    fields: [
+        searchType(), rankType(),
+        list("--account-id <id>", "Official account ID", "accountIdList"),
+        list("--security <code>", "Security code (e.g. 000001.SZ)", "securityList"),
+        list("--category <type>", "Article type: news/law/report/view/data/event/meeting/notice/recruit/investEdu/brand/notes/other", "categoryList"),
+        list("--industry <id>", "Industry ID (constant-list citicIndustry/swIndustry)", "industryList"),
+        format(), output("Output path"),
+        ...timeFilters(),
+    ],
+});
+addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.download", idOption: "--article-id", idField: "articleId", fallbackPrefix: "official-account", fileType: { description: "File type: 1=txt(default) 2=HTML", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.official-account.list" });
+query(qa, "list", {
+    endpoint: "insight.qa.list",
+    fields: [
+        required("--security-code <code>", "Security code, e.g. 601012.SH", "securityCode"),
+        from(), size("Total rows to return; omit to fetch all (max page 500)"),
+        startTime("Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"), endTime("End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"),
+        list("--source <type>", "Source: conference/interactive/survey (repeat)", "source"),
+        list("--question-category <name>", "Question category (repeat): productAndBusiness/capacityAndProjects/ordersAndCustomers/financialData/materialEvents/capitalOperations/shareholdersAndDividends/corporateGovernance/marketAndValuation/macroAndIndustry/risksAndOthers", "questionCategory"),
+        numberList("--answer-important <flag>", "Answer involves key info: 1=yes 0=no (repeat; omit for all)", "answerImportant"),
+        format(), output(),
+    ],
+});
+query(reportImage, "list", {
+    endpoint: "insight.report-image.list",
+    fields: [
+        required("--keyword <text>", "Search keyword, e.g. 'AI' '新能源汽车'", "keyword"),
+        top(20),
+        value("--source-id <id>", "Report source ID, to filter to one report (from a report list or knowledge base)", "sourceId"),
+        startTime("Start time (yyyy-MM-dd HH:mm:ss; yyyy-MM-dd auto-completed)"), endTime("End time (yyyy-MM-dd HH:mm:ss; yyyy-MM-dd auto-completed)"),
+        format(), output(),
+    ],
+});
+addDownloadCommand(reportImage, { endpointKey: "insight.report-image.download", idOption: "--chunk-id", idField: "chunkId", fallbackPrefix: "report-image" });
+insight.addCommand(opinion);
+insight.addCommand(summary);
+insight.addCommand(pamirsSummary);
+insight.addCommand(roadshow);
+insight.addCommand(siteVisit);
+insight.addCommand(strategy);
+insight.addCommand(forum);
+insight.addCommand(performanceCalendar);
+insight.addCommand(research);
+insight.addCommand(foreignReport);
+insight.addCommand(announcement);
+insight.addCommand(announcementHk);
+insight.addCommand(announcementUs);
+insight.addCommand(foreignOpinion);
+insight.addCommand(independentOpinion);
+insight.addCommand(officialAccount);
+insight.addCommand(qa);
+insight.addCommand(reportImage);
+const highlight = new Command("highlight");
+query(highlight, "list", {
+    description: "Meeting highlights feed: key takeaways per meeting, newest first (5 credits/row)",
+    endpoint: "insight.highlight.list",
+    fields: [
+        from(), size("Total rows to return; omit to fetch all (max page 50). Billed per row — bound this on wide ranges"),
+        startTime("Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"), endTime("End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"),
+        list("--security <code>", "Security code, e.g. 000001.SZ / 09992.HK / AAPL.O (repeatable)", "securityList"),
+        list("--research-area <id>", "Research area ID: citicIndustry (1008001xx) or gangtiseIndustry direction (122000xxx). swIndustry codes are NOT accepted here", "researchAreaList"),
+        format(), output(),
+    ],
+});
+insight.addCommand(highlight);

package/dist/src/commands/quote.js

@@ -0,0 +1,181 @@
+import { Command } from "commander";
+import { collectList, dateArg, datetimeArg, maybeArray, parseOptionalNumberOption } from "../core/args.js";
+import { buildQuoteKlineBody } from "../core/commandBodies.js";
+import { callPerSecurity, estimateTradingDays } from "../core/perSecurity.js";
+import { callKlineWithSharding, isFullMarket } from "../core/quoteSharding.js";
+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 { 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 });
+const REALTIME_MARKETS = ["aShares", "hkStocks", "usStocks"];
+const FUND_FLOW_MARKETS = ["aShares"];
+const MARKET_KEYWORDS = new Set(["all", "ashares", "hkstocks", "usstocks"]);
+const matchesMarketKeyword = (value, keyword) => value.toLowerCase() === keyword.toLowerCase();
+export const checkMarketKeywords = (securities, accepted, command, noKeywordReason) => {
+    const used = securities.filter((s) => MARKET_KEYWORDS.has(s.toLowerCase()));
+    if (used.length === 0)
+        return;
+    const unsupported = used.filter((k) => !accepted.some((a) => matchesMarketKeyword(k, a)));
+    if (unsupported.length > 0) {
+        throw new ValidationError(accepted.length > 0
+            ? `${command}: '${unsupported[0]}' is not a whole-market keyword for this command — use ${accepted.join(" / ")}`
+            : `${command}: this command takes explicit security codes only — '${unsupported[0]}' and other whole-market keywords are not supported${noKeywordReason ? `: ${noKeywordReason}` : ""}`);
+    }
+    if (securities.length > 1) {
+        throw new ValidationError(`${command}: a market keyword must be passed alone, got '${securities.join(", ")}' — the API rejects it mixed with security codes or another keyword`);
+    }
+};
+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: ${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 ?? [];
+        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);
+    });
+});
+addKlineCommand("day-kline", "quote.day-kline", "Security code — A-share .SH/.SZ/.BJ, ETF .SH/.SZ (e.g. 512800.SH), HK .HK, US .O/.N/.A, 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 (auto-sharded by date, must be passed alone; keywords cover stocks only — ETFs and indices must be listed by code)", KLINE_MARKETS);
+addKlineCommand("day-kline-hk", "quote.day-kline-hk", "[deprecated: use 'day-kline'] Security code (HK stock: .HK, or 'all' for full market)", LEGACY_ALL_MARKET(2));
+addKlineCommand("day-kline-us", "quote.day-kline-us", "[deprecated: use 'day-kline'] Security code (US stock: e.g. AAPL.O, or 'all' for full market)", LEGACY_ALL_MARKET(1));
+addKlineCommand("index-day-kline", "quote.index-day-kline", "[deprecated: use 'day-kline'] Index code (.SH/.SZ/.BJ), repeat for several; no whole-market keyword — 'all' is refused because the endpoint answers it with an empty result", {}, "the endpoint answers 'all' with an empty result. List the index codes one by one — quote day-kline takes the same codes");
+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: ${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);
+    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, ([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. 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")
+    .option("--output <path>")
+    .action((options) => {
+    checkMarketKeywords(options.security, REALTIME_MARKETS, "quote realtime");
+    return emit(options, async (client) => {
+        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;
+    });
+});
+quote.command("fund-flow")
+    .description("A-share daily fund flow (SH/SZ/BJ)")
+    .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: ${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>")
+    .action((options) => {
+    checkMarketKeywords(options.security, FUND_FLOW_MARKETS, "quote 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: MAX_QUOTE_LIMIT }),
+            fieldList: maybeArray(options.field),
+        };
+        if (isFullMarket(body, "aShares")) {
+            if (!body.startDate || !body.endDate) {
+                throw new ValidationError("quote fund-flow --security aShares requires both --start-date and --end-date (the full market is fetched via per-day shards)");
+            }
+            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;
+        }
+        const limit = body.limit ?? DEFAULT_QUOTE_LIMIT;
+        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

@@ -0,0 +1,49 @@
+import { Command } from "commander";
+import { collectKeyValue } from "../core/args.js";
+import { ENDPOINTS, listEndpoints } from "../core/endpoints.js";
+import { ConfigError, ValidationError } from "../core/errors.js";
+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), 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, yes: Boolean(options.yes) });
+    let body;
+    if (options.body) {
+        try {
+            body = JSON.parse(options.body);
+        }
+        catch {
+            throw new ConfigError(`Invalid JSON in --body: ${options.body}`);
+        }
+    }
+    if (endpoint.kind === "download") {
+        if (body !== undefined && endpoint.method !== "POST") {
+            throw new ValidationError(`--body is not supported for GET download endpoints (use --query key=value); ${endpointKey} is kind=download`);
+        }
+        await runDownload(client, endpointKey, options.query, {
+            output: options.output,
+            fallbackName: "download.bin",
+            body,
+        });
+        return;
+    }
+    if (Object.keys(options.query).length > 0) {
+        throw new ValidationError(`--query is not supported for JSON endpoints (use --body '{...}'); ${endpointKey} is kind=json`);
+    }
+    try {
+        const data = await client.call(endpointKey, body);
+        if (endpoint.itemFailures)
+            flagFailedItems(data, `raw call ${endpointKey}`);
+        await printData(data, format, options.output);
+    }
+    finally {
+        await client.rowSink?.abort();
+    }
+})).addCommand(new Command("list").description("List all registered endpoint keys (for use with 'raw call')").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => printData(listEndpoints(), parseOutputFormat(options.format), options.output)));

package/dist/src/commands/reference.js

@@ -0,0 +1,58 @@
+import { Command } from "commander";
+import { value, required, choiceList, top, format, output, query } from "./shared.js";
+export const reference = new Command("reference").description("Reference data APIs");
+query(reference, "securities-search", {
+    endpoint: "reference.securities-search",
+    fields: [
+        required("--keyword <text>", "Search keyword (name/code/pinyin/English)", "keyword"),
+        choiceList("--category <type>", "Category: stock/dr/index/fund", "category", ["stock", "dr", "index", "fund"]),
+        top(10),
+        format(), output(),
+    ],
+});
+query(reference, "constant-category", {
+    description: "List constant categories and which API params accept them",
+    endpoint: "reference.constant-category",
+    fields: [format(), output()],
+});
+query(reference, "constant-list", {
+    endpoint: "reference.constant-list",
+    fields: [
+        required("--category <code>", "Category code from 'reference constant-category' (e.g. citicIndustry/swIndustry/regionCategory)", "category"),
+        format(), output(),
+    ],
+});
+query(reference, "concept-search", {
+    endpoint: "reference.concept-search",
+    fields: [required("--keyword <text>", "Search keyword (name/pinyin/group name)", "keyword"), top(10), format(), output()],
+});
+query(reference, "sector-search", {
+    endpoint: "reference.sector-search",
+    fields: [value("--keyword <text>", "Search keyword (name/pinyin)", "keyword"), top(10), format(), output()],
+});
+query(reference, "sector-constituents", {
+    endpoint: "reference.sector-constituents",
+    fields: [required("--sector-id <id>", "Sector ID from 'reference sector-search'", "sectorId"), format(), output()],
+});
+query(reference, "chiefs-search", {
+    endpoint: "reference.chiefs-search",
+    fields: [required("--keyword <text>", "Search keyword (chief name / institution / team)", "keyword"), top(10), format(), output()],
+});
+query(reference, "institution-search", {
+    endpoint: "reference.institution-search",
+    fields: [
+        required("--keyword <text>", "Search keyword (institution name / abbreviation)", "keyword"),
+        choiceList("--category <name>", "Category: domesticBroker/foreignInstitution/leadInstitution/opinionInstitution/foreignOpinionInstitution (repeat); omit for all", "categoryList", ["domesticBroker", "foreignInstitution", "leadInstitution", "opinionInstitution", "foreignOpinionInstitution"]),
+        top(10),
+        format(), output(),
+    ],
+});
+query(reference, "official-account-search", {
+    endpoint: "reference.official-account-search",
+    fields: [
+        required("--keyword <text>", "Search keyword (account name / institution / keyword, e.g. 东吴证券)", "keyword"),
+        choiceList("--category <name>", "Category: listedCompany/broker/government/media (repeat); omit for all incl. uncategorized", "category", ["listedCompany", "broker", "government", "media"]),
+        top(10),
+        format(), output(),
+    ],
+});