gangtise-openapi-cli 0.50.0 → 0.52.0

package/dist/src/commands/bond.js

@@ -2,7 +2,7 @@ import { Command, Option } from "commander";
 import { collectList, collectNames, dateArg, maybeArray, parseNumberOption } from "../core/args.js";
 import { maxUnitsOf } from "../core/endpoints.js";
 import { ValidationError } from "../core/errors.js";
-import { emit, noteLateStart } from "./shared.js";
+import { emit, noteLateStart, OUTPUT_HELP } from "./shared.js";
 const BOND_LATE_CAUSE = "The bond may have listed later, or this data starts later than the requested range — the endpoint returns from its first day of data without an error.";
 export const bond = new Command("bond").description("Bond APIs: profiles, issuers, quotes, valuations, cash flows, ratings, announcements");
 function requireBondCodes(codes, max) {
@@ -16,7 +16,7 @@ function requireBondCodes(codes, max) {
 const bondSecurityOption = (command) => command
     .option("--security <code>", "Bond code, e.g. 019742.SH / 123456.SZ / 220205.IB (repeatable). Short names and pinyin are rejected — resolve them with 'reference securities-search --category bond' first", collectList, [])
     .option("--field <field>", "Field to return (repeatable); omit for all. An unsupported name rejects the whole call with 100003", collectList, [])
-    .option("--format <format>", "Output format", "table").option("--output <path>");
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP);
 const addBondRange = (name, endpointKey, describe, rangeHelp, max) => bondSecurityOption(bond.command(name).description(describe))
     .option("--start-date <date>", `${rangeHelp} start (yyyy-MM-dd); omit for all history`, dateArg("--start-date"))
     .option("--end-date <date>", `${rangeHelp} end (yyyy-MM-dd); omit for all history`, dateArg("--end-date"))
@@ -64,7 +64,7 @@ bond.command("issuance-plan").description("Rate-bond issuance calendar over a da
     .requiredOption("--start-date <date>", "Issue date range start (yyyy-MM-dd)", dateArg("--start-date"))
     .requiredOption("--end-date <date>", "Issue date range end (yyyy-MM-dd)", dateArg("--end-date"))
     .option("--field <field>", "Field to return (repeatable); omit for all", collectList, [])
-    .option("--format <format>", "Output format", "table").option("--output <path>")
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => client.call("bond.issuance-plan", { startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) })));
 bondSecurityOption(bond.command("announcement").description("Bond announcements, paged. Filter by bond codes OR by announcement date range, never both"))
     .option("--start-date <date>", "Announcement date range start (yyyy-MM-dd); mutually exclusive with --security", dateArg("--start-date"))
@@ -90,7 +90,7 @@ bond.command("default-list").description("Defaulted bonds: by default-date range
     .option("--security <code>", "Bond code, e.g. 169687.SH / 220205.IB (repeatable, no per-call limit)", collectList, [])
     .option("--issuer <name>", "One issuer, by full name. A short name is matched to a single closest issuer, which may not be the one meant — check issuerName in the result", collectNames, [])
     .option("--field <field>", "Field to return (repeatable); omit for all. An unsupported name rejects the whole call with 100005", collectList, [])
-    .option("--format <format>", "Output format", "table").option("--output <path>")
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     const byDate = Boolean(options.startDate || options.endDate);
     const modes = [byDate, options.security.length > 0, options.issuer.length > 0].filter(Boolean).length;

package/dist/src/commands/fund.js

@@ -3,7 +3,7 @@ import { collectNames } from "../core/args.js";
 import { addComponentCodes, clientLookup } from "../core/etfComponents.js";
 import { date, flag, format, list, output, query, requiredList, value } from "./shared.js";
 export const fund = new Command("fund").description("Fund APIs: profiles, NAV, fees, managers, scale, holders, holdings and allocation, ETF creation/redemption");
-const code = () => requiredList("--security <code>", "Fund code, e.g. 005827.OF / 159967.SZ / 510300.SH (repeatable, comma-separated accepted). From a fund name: 'reference securities-search --category fund', keeping only rows whose category is fund", "fundCodeList");
+const code = () => requiredList("--security <code>", "Fund code, e.g. 005827.OF / 159967.SZ / 510300.SH (repeatable, comma-separated accepted). From a fund name: 'reference securities-search --category fund', which returns funds only", "fundCodeList");
 const range = (what) => [
     date("--start-date <date>", `${what} range start (yyyy-MM-dd); omit both ends for everything in your account's history window`, "startDate"),
     date("--end-date <date>", `${what} range end (yyyy-MM-dd)`, "endDate"),

package/dist/src/commands/fundamental.js

@@ -4,16 +4,16 @@ import { COSTLY_FETCH_CREDITS } from "../core/endpoints.js";
 import { normalizeRows } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { emit, withClient, flagIfLimitTruncated, field, required, date, list, format, output, query } from "./shared.js";
+import { emit, withClient, flagIfLimitTruncated, field, date, list, format, output, query, OUTPUT_HELP, SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode, securityCode } from "./shared.js";
 export const fundamental = new Command("fundamental").description("Fundamental APIs");
-const addFinancialReport = (name, endpointKey, periodHelp = "Period") => query(fundamental, name, {
+const addFinancialReport = (name, endpointKey, periodHelp = "Period: q1/interim/q3/annual/latest") => query(fundamental, name, {
     endpoint: endpointKey,
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
-        list("--fiscal-year <year>", "Fiscal year", "fiscalYear"),
-        list("--period <period>", periodHelp, "period"),
+        list("--fiscal-year <year>", "Fiscal year; pass --period with it, or the latest report comes back whatever the year", "fiscalYear"),
+        list("--period <period>", `${periodHelp} (server default: latest)`, "period"),
         list("--report-type <type>", "Report type", "reportType"),
         list("--field <field>", "Field", "fieldList"),
         format(), output(),
@@ -33,7 +33,7 @@ addFinancialReport("cash-flow-us", "fundamental.cash-flow-us", "Period: q1/h1/q3
 query(fundamental, "main-business", {
     endpoint: "fundamental.main-business",
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
         field(new Option("--breakdown <type>", "Breakdown: product/industry/region").choices(["product", "industry", "region"]).default("product"), (v) => ({ breakdown: v })),
@@ -62,7 +62,7 @@ function firstRowTradeDate(data) {
     return typeof value === "string" ? value : undefined;
 }
 fundamental.command("valuation-analysis")
-    .requiredOption("--security-code <code>")
+    .requiredOption(SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode)
     .addOption(new Option("--indicator <name>", "Indicator").choices(["peTtm", "pbMrq", "peg", "psTtm", "pcfTtm", "em"]).makeOptionMandatory())
     .option("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date"))
     .option("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date"))
@@ -70,7 +70,7 @@ fundamental.command("valuation-analysis")
     .option("--field <field>", "Field", collectList, [])
     .option("--skip-null", "Drop rows where value or percentileRank is null")
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const requested = maybeArray(options.field);
@@ -115,7 +115,7 @@ fundamental.command("valuation-analysis")
 query(fundamental, "top-holders", {
     endpoint: "fundamental.top-holders",
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         field(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory(), (v) => ({ holderType: v })),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
@@ -125,13 +125,13 @@ query(fundamental, "top-holders", {
     ],
 });
 fundamental.command("earning-forecast")
-    .requiredOption("--security-code <code>")
+    .requiredOption(SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode)
     .option("--start-date <date>", "Start date (default: 1 year before end-date)", dateArg("--start-date"))
     .option("--end-date <date>", "End date (default: today)", dateArg("--end-date"))
     .option("--consensus <name>", "Consensus indicator: netIncome/netIncomeYoy/eps/pe/bps/pb/peg/roe/ps", collectList, [])
     .option("--yes", `Fetch a range estimated above ${COSTLY_FETCH_CREDITS} credits (billed per row; see the refusal for the estimate)`)
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => {
     const endDate = options.endDate ?? beijingDateString(new Date());
     const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);

package/dist/src/commands/indicator.js

@@ -5,7 +5,7 @@ import { checkScreenerBindings, droppedFromMatrix, flattenCrossSection, flattenT
 import { ValidationError } from "../core/errors.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { withClient } from "./shared.js";
+import { withClient, OUTPUT_HELP } from "./shared.js";
 function flagDropped(rows, data, requestedSecurities, requestedIndicators, timeSeries = false) {
     if (isEmptyMatrix(data)) {
         if (timeSeries) {
@@ -44,7 +44,7 @@ indicator.command("search")
     .requiredOption("--keyword <text>", "Search keyword, e.g. '收盘价' '成交量' '营业收入' (not free-form questions)")
     .option("--limit <number>", "Max results (default: 50, max: 100)", "50")
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.search", {
@@ -62,7 +62,7 @@ indicator.command("cross-section")
     .option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'. Bare 'code:' (nothing after the colon) declares the indicator takes NO date — required by any indicator whose parameterList has no date key at all, which otherwise rejects the tradeDate --date injects: the pty_* / scr_* static-attribute families (pty_op_scope, scr_exchg_mkt, scr_isin …), plus div_cash_paid_ratio / div_cash_yr (add 'code:fiscalYear=YYYY' too) and pty_shr_reg. It composes with real params, so 'code:' + 'code:scale=8' keeps the scale", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
@@ -83,7 +83,7 @@ indicator.command("time-series")
     .option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode/securityCode, unique & order-stable for batch mapping").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
@@ -102,7 +102,7 @@ indicator.command("screener")
     .option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'. Bare 'F1:' (nothing after the colon) declares that the indicator takes NO date — required by any indicator whose parameterList has no date key at all, which otherwise rejects the tradeDate --date injects: the pty_* / scr_* static-attribute families (pty_op_scope, scr_exchg_sctr, scr_isin …), plus div_cash_paid_ratio / div_cash_yr (add 'F1:fiscalYear=YYYY' too) and pty_shr_reg. It composes with real params, so 'F1:' + 'F1:scale=8' keeps the scale", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);

package/dist/src/commands/insight.js

@@ -3,7 +3,7 @@ import { collectList, dateArg, datetimeArg, maybeArray, parseChoiceList, parseEn
 import { ValidationError } from "../core/errors.js";
 import { fetchOpinionDetails } from "../core/opinionDetail.js";
 import { rowCount } from "../core/rowSink.js";
-import { emit, addDownloadCommand, confirmCostly, multiChoice, field, value, required, list, numberList, choiceList, count, rankType, searchType, top, flag, format, output, from, size, startTime, endTime, timeFilters, query, RESEARCH_AREA_CITIC_OR_DIRECTION } from "./shared.js";
+import { emit, addDownloadCommand, confirmCostly, multiChoice, field, value, required, list, numberList, choiceList, count, rankType, searchType, top, flag, format, output, from, size, startTime, endTime, timeFilters, query, RESEARCH_AREA_CITIC_OR_DIRECTION, OUTPUT_HELP, securityCode } from "./shared.js";
 export const insight = new Command("insight").description("Insight APIs");
 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");
@@ -21,6 +21,7 @@ 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 overseasOpinion = new Command("overseas-opinion");
 const officialAccount = new Command("official-account");
 const qa = new Command("qa");
 const reportImage = new Command("report-image");
@@ -46,7 +47,7 @@ query(opinion, "list", {
         list("--broker-tag <tag>", "Broker tag: topBroker/newFortune", "brokerTagList"),
         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. Takes no --category / --broker-tag, and --llm-tag only strongRcmd/earningsReview/topBroker/newFortune"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -62,7 +63,7 @@ query(summary, "list", {
         list("--category <name>", "Category", "categoryList"),
         list("--market <name>", "Market", "marketList"),
         list("--participant-role <name>", "Participant role", "participantRoleList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -79,7 +80,7 @@ query(pamirsSummary, "list", {
         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"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -102,7 +103,7 @@ const addScheduleList = (command, endpointKey, fields) => query(command, "list",
         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"),
+        format(), output(),
         ...timeFilters(),
         publishTime("--publish-start-time <datetime>", "Collected from (publishTime, when the schedule first came in — not when it is held); combines with --start-time/--end-time", "publishStartTime"),
         publishTime("--publish-end-time <datetime>", "Collected until (publishTime); a bare date covers that whole day", "publishEndTime"),
@@ -146,7 +147,7 @@ performanceCalendar.command("list").description("Earnings calendar (业绩预告
     .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")
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP)
     .addOption(confirmCostly().option)
     .action((options) => {
     const marketList = parseChoiceList(options.market, "--market", PERFORMANCE_MARKETS);
@@ -186,7 +187,7 @@ query(research, "list", {
         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"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -206,7 +207,7 @@ query(foreignReport, "list", {
         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"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -218,7 +219,7 @@ query(announcement, "list", {
         searchType(), rankType(),
         list("--security <code>", "Security code", "securityList"),
         list("--category <id>", "Category ID", "categoryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(parseTimestamp13, parseEndTimestamp13),
     ],
 });
@@ -230,7 +231,7 @@ query(announcementHk, "list", {
         searchType(), rankType(),
         list("--security <code>", "Security code (e.g. 01913.HK)", "securityList"),
         list("--category <id>", "Category ID", "categoryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -242,7 +243,7 @@ query(announcementUs, "list", {
         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"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -258,17 +259,17 @@ query(foreignOpinion, "list", {
         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"),
+        format(), output(),
         ...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>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .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>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.foreign-opinion.detail", "foreignOpinionIdList", "foreignOpinionId", options.foreignOpinionId)));
 query(independentOpinion, "list", {
     endpoint: "insight.independent-opinion.list",
@@ -278,11 +279,30 @@ query(independentOpinion, "list", {
         list("--industry <id>", SW_INDUSTRY_ONLY, "industryList"),
         list("--rating <name>", "Rating", "ratingList"),
         list("--rating-change <name>", "Rating change", "ratingChangeList"),
-        format(), output("Output path"),
+        format(), output(),
         ...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(overseasOpinion, "list", {
+    description: "List overseas opinions: brief + briefTranslate, body via 'overseas-opinion detail' (0.1 credits/row)",
+    endpoint: "insight.overseas-opinion.list",
+    fields: [
+        rankType(),
+        list("--account <id>", "Account ID from 'reference overseas-account-search' (repeat or comma-separate)", "accountIdList"),
+        list("--security <code>", "Security code with market suffix, e.g. NVDA.O. A missing suffix is rejected (120001); a real suffix of the wrong market (NVDA.N) matches nothing", "securityList"),
+        list("--category <name>", "Category: opinion/news/dataAnalysis/promotion (repeat). A row in several categories is returned under each; rows without a category only when this is omitted", "categoryList"),
+        list("--industry <id>", "GICS sector ID: 107700001 energy ... 107700011 real estate (list: 'reference constant-list --category gicsIndustry'). Other industry code sets are rejected (100005)", "industryList"),
+        list("--region <code>", "Region code: cn/cnHk/cnTw/us/jp/kr/uk/gl; other regionCategory values are rejected (100005)", "regionList"),
+        count("--original-flag <number>", "1=original posts only 0=reposts only; omit for both", "originalFlag"),
+        format(), output(),
+        ...timeFilters(),
+    ],
+});
+overseasOpinion.command("detail").description("Full bodies (content + contentTranslate) of overseas opinions by ID (10 credits per returned opinion; batched 20 per call)")
+    .requiredOption("--overseas-opinion-id <id>", "overseasOpinionId from 'insight overseas-opinion list' (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
+    .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.overseas-opinion.detail", "overseasOpinionIdList", "overseasOpinionId", options.overseasOpinionId)));
 query(officialAccount, "list", {
     endpoint: "insight.official-account.list",
     cache: { endpointKey: "insight.official-account.list", idField: "articleId" },
@@ -292,7 +312,7 @@ query(officialAccount, "list", {
         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"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -300,7 +320,7 @@ addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.dow
 query(qa, "list", {
     endpoint: "insight.qa.list",
     fields: [
-        required("--security-code <code>", "Security code, e.g. 601012.SH", "securityCode"),
+        securityCode("Security code, e.g. 601012.SH"),
         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"),
@@ -335,6 +355,7 @@ insight.addCommand(announcementHk);
 insight.addCommand(announcementUs);
 insight.addCommand(foreignOpinion);
 insight.addCommand(independentOpinion);
+insight.addCommand(overseasOpinion);
 insight.addCommand(officialAccount);
 insight.addCommand(qa);
 insight.addCommand(reportImage);

package/dist/src/commands/quote.js

@@ -8,7 +8,7 @@ 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";
+import { emit, withClient, DEFAULT_QUOTE_LIMIT, MAX_QUOTE_LIMIT, flagIfLimitTruncated, noteLateStart, OUTPUT_HELP } 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 });
@@ -48,7 +48,7 @@ const addKlineCommand = (name, endpointKey, securityHelp, markets, noKeywordReas
     .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>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, Object.keys(markets), `quote ${name}`, noKeywordReason);
     options.security = canonicalizeMarketKeywords(options.security, Object.keys(markets));
@@ -100,7 +100,7 @@ quote.command("minute-kline")
     .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>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(options, async (client) => {
     const format = parseOutputFormat(options.format);
     client.rowSink?.watchEarliest("tradeTime");
@@ -127,7 +127,7 @@ quote.command("realtime")
     .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>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, REALTIME_MARKETS, "quote realtime");
     return emit(options, async (client) => {
@@ -147,7 +147,7 @@ quote.command("fund-flow")
     .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>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, FUND_FLOW_MARKETS, "quote fund-flow");
     options.security = canonicalizeMarketKeywords(options.security, FUND_FLOW_MARKETS);
@@ -187,7 +187,7 @@ quote.command("sector-fund-flow")
     .option("--limit <number>", `Max rows returned (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}). It cuts the answer only: a query too heavy to compute fails with 100006 whatever the limit — shorten the range, or pass fewer sectors or fields`)
     .option("--field <field>", "Field, e.g. sectorMainNetInflow / sectorLargeInflow (repeat); omit for all. sectorId and tradeDate always come first", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, async (client) => {
     const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: MAX_QUOTE_LIMIT }) ?? DEFAULT_QUOTE_LIMIT;
     const fieldList = maybeArray(options.field);

package/dist/src/commands/raw.js

@@ -5,8 +5,8 @@ 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) => {
+import { createClient, runDownload, assertConfirmed, OUTPUT_HELP } from "./shared.js";
+export const raw = new Command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>", "Request body as a JSON string").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>", OUTPUT_HELP).action(async (endpointKey, options) => {
     const endpoint = ENDPOINTS[endpointKey];
     if (!endpoint) {
         throw new ConfigError(`Unknown endpoint key: ${endpointKey}`);
@@ -47,4 +47,4 @@ export const raw = new Command("raw").description("Raw API calls").addCommand(ne
     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)));
+})).addCommand(new Command("list").description("List all registered endpoint keys (for use with 'raw call')").option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP).action((options) => printData(listEndpoints(), parseOutputFormat(options.format), options.output)));

package/dist/src/commands/reference.js

@@ -1,11 +1,11 @@
 import { Command } from "commander";
-import { value, required, choiceList, top, format, output, query } from "./shared.js";
+import { value, required, requiredList, date, choiceList, top, format, output, from, size, 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/bond. Convertible bonds can come back under any category — keep the rows whose returned category matches", "category", ["stock", "dr", "index", "fund", "bond"]),
+        choiceList("--category <type>", "Category: stock/dr/index/fund/bond. Without it, a convertible bond can rank above its stock on a short name", "category", ["stock", "dr", "index", "fund", "bond"]),
         top(10),
         format(), output(),
     ],
@@ -34,6 +34,29 @@ query(reference, "sector-constituents", {
     endpoint: "reference.sector-constituents",
     fields: [required("--sector-id <id>", "Sector ID from 'reference sector-search'", "sectorId"), format(), output()],
 });
+function noteMissingIndices(data, requested, tradeDate) {
+    const rows = data?.list;
+    if (!Array.isArray(rows))
+        return;
+    const found = new Set(rows.map((row) => String(row?.indexCode).toUpperCase()));
+    const missing = requested.filter((code) => !found.has(code.toUpperCase()));
+    if (!missing.length)
+        return;
+    process.stderr.write(`[gangtise] note: no constituent weights for ${missing.join(", ")} on ${tradeDate}. Weights come for the last trading day of each month — another date, like an unknown index code, comes back empty without an error. Check the date, and the code with 'reference securities-search --category index'.\n`);
+}
+query(reference, "index-weight", {
+    description: "Index constituents and their weights (%) on the last trading day of a month (free)",
+    endpoint: "reference.index-weight",
+    fields: [
+        requiredList("--index <code>", "Index code, e.g. 000300.SH / 000905.SH / 399006.SZ (repeat or comma-separate)", "indexCodeList"),
+        date("--date <date>", "Trading date (yyyy-MM-dd): the last trading day of a month, e.g. 2026-10-30; any other date returns no rows", "tradeDate", { required: true }),
+        format(), output(),
+    ],
+    shape: async (data, _client, options) => {
+        noteMissingIndices(data, options.index, options.date);
+        return data;
+    },
+});
 query(reference, "chiefs-search", {
     endpoint: "reference.chiefs-search",
     fields: [required("--keyword <text>", "Search keyword (chief name / institution / team)", "keyword"), top(10), format(), output()],
@@ -50,9 +73,18 @@ query(reference, "institution-search", {
 query(reference, "official-account-search", {
     endpoint: "reference.official-account-search",
     fields: [
-        required("--keyword <text>", "Search keyword (account name / institution / keyword, e.g. 东吴证券)", "keyword"),
+        required("--keyword <text>", "Account name fragment, e.g. 中信证券 (finds 中信证券研究). Matches the account name: an institution's full name misses accounts named by short form (东吴证券 finds none, 东吴 finds 东吴策略陈刚团队)", "keyword"),
         choiceList("--category <name>", "Category: listedCompany/broker/government/media (repeat); omit for all incl. uncategorized", "category", ["listedCompany", "broker", "government", "media"]),
         top(10),
         format(), output(),
     ],
 });
+query(reference, "overseas-account-search", {
+    description: "Search overseas opinion account IDs by name fragment, for 'insight overseas-opinion list --account' (free)",
+    endpoint: "reference.overseas-account-search",
+    fields: [
+        required("--keyword <text>", "Account name fragment: substring match anywhere in the name, case-insensitive (e.g. elo matches Elon Musk and Financelot)", "accountName"),
+        from(), size(),
+        format(), output(),
+    ],
+});

package/dist/src/commands/shared.js

@@ -1,18 +1,19 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { Option } from "commander";
+import { InvalidArgumentError, 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 { placeStreamedDownload, releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
+import { assertOutputFilePath, placeStreamedDownload, releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
+import { isDryRun } from "../core/dryRun.js";
 import { ENDPOINTS } from "../core/endpoints.js";
 import { ValidationError } from "../core/errors.js";
 import { parseOutputFormat, stagingPath } from "../core/output.js";
-import { printData } from "../core/printer.js";
+import { columnsSelected, printData } from "../core/printer.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;
+    const sink = stream?.output && (stream.format === "jsonl" || stream.format === "csv") && !columnsSelected() ? new ExportSink(stream.output, stream.format, stream.cache) : undefined;
     const client = new GangtiseClient(loadConfig(), sink);
     client.allowCostlyFetch = Boolean(stream?.yes);
     return client;
@@ -89,6 +90,7 @@ export function noteLateStart(data, requestedStart, field, label, cause = "The s
 }
 export async function runDownload(client, endpointKey, query, options) {
     if (options.output) {
+        await assertOutputFilePath(options.output);
         const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
         await saveDownloadResult(result, options.fallbackName, options.output);
         return;
@@ -120,7 +122,7 @@ export async function runDownload(client, endpointKey, query, options) {
     }
 }
 export function addDownloadCommand(parent, spec) {
-    const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`);
+    const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`, `The ${spec.idField} of the record, from the matching list command`);
     if (spec.fileType) {
         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));
@@ -132,7 +134,7 @@ export function addDownloadCommand(parent, spec) {
     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");
     }
-    cmd.option("--output <path>").action((options) => withClient(async (client) => {
+    cmd.option("--output <path>", DOWNLOAD_OUTPUT_HELP).action((options) => withClient(async (client) => {
         const id = options[spec.idField];
         const qp = { [spec.idField]: id };
         if (spec.fileType && options.fileType)
@@ -151,7 +153,7 @@ export function addDownloadCommand(parent, spec) {
 }
 export function assertConfirmed(endpointKey, confirmed, target) {
     const destructive = ENDPOINTS[endpointKey]?.destructive;
-    if (!destructive || confirmed)
+    if (!destructive || confirmed || isDryRun())
         return;
     throw new ValidationError(`${destructive.warning} 确认要对 ${target} 执行就加上 --yes。`);
 }
@@ -201,8 +203,18 @@ export const rankType = () => numberEnum("--rank-type <number>", "Rank type: 1=c
 export const searchType = () => numberEnum("--search-type <number>", "Search type: 1=title 2=fulltext", "searchType", ["1", "2"], "1");
 export const top = (max) => field(new Option("--top <number>", `Max results (default: 10, max: ${max})`).default("10"), (v) => ({ top: parseNumberOption(v, "--top", { integer: true, min: 1, max }) }));
 export const flag = (flags, description) => field(new Option(flags, description));
+export const OUTPUT_HELP = "Write the result to this file instead of stdout (a file path, not a directory)";
+export const DOWNLOAD_OUTPUT_HELP = "Save the file to this path (a file path, not a directory); omit for an automatic name in the current directory";
+export const SECURITY_CODE_FLAGS = "--security, --security-code <code>";
+export const SECURITY_CODE_HELP = "Security code, e.g. 600519.SH";
+export const oneSecurityCode = (value) => {
+    if (value.includes(","))
+        throw new InvalidArgumentError("takes one security code; run the command once per code");
+    return value;
+};
 export const format = (fallback = "table") => field(new Option("--format <format>", "Output format").default(fallback));
-export const output = (description) => field(new Option("--output <path>", description));
+export const output = (description = OUTPUT_HELP) => field(new Option("--output <path>", description));
+export const securityCode = (description = SECURITY_CODE_HELP) => field(new Option(SECURITY_CODE_FLAGS, description).makeOptionMandatory().argParser(oneSecurityCode), (v) => ({ securityCode: v }));
 export const from = () => field(new Option("--from <number>", "Starting offset").default("0"), (v) => ({ from: parseFrom(v) }));
 export const size = (description = "Total rows to return; omit to fetch all") => field(new Option("--size <number>", description), (v) => ({ size: parseSize(v) }));
 const asTyped = (v) => v;