gangtise-openapi-cli 0.41.0 → 0.42.0

package/dist/src/commands/ai.js

@@ -0,0 +1,155 @@
+import { Command, Option } from "commander";
+import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "../core/asyncContent.js";
+import { collectList, numberListArg, collectText, dateArg, datetimeArg, maybeArray, parseFrom, parseNumberOption, parseSize, parseTimestamp13 } from "../core/args.js";
+import { ValidationError } from "../core/errors.js";
+import { markFailed } from "../core/exitStatus.js";
+import { parseOutputFormat } from "../core/output.js";
+import { printData } from "../core/printer.js";
+import { emit, withClient, runDownload, field, required, date, list, flag, format, output, from, size, requestBody, query } from "./shared.js";
+import { checkMarketKeywords } from "./quote.js";
+export const ai = new Command("ai").description("AI APIs");
+function addGenerationTask(name, spec) {
+    const command = ai.command(name);
+    for (const f of [...spec.fields, flag("--wait", "Wait for content generation (blocking, up to ~5 min)"), format("json"), output()])
+        command.addOption(f.option);
+    command.action((options) => withClient(async (client) => {
+        const format = parseOutputFormat(options.format);
+        const idResult = await client.call(spec.submit, requestBody(spec.fields, options));
+        const dataId = idResult?.dataId;
+        if (!dataId) {
+            process.stderr.write(`${spec.idFailure}\n`);
+            markFailed();
+            return;
+        }
+        if (!options.wait) {
+            process.stderr.write(`${spec.label} task submitted. dataId: ${dataId}\n`);
+            await printData({ dataId, status: "pending", hint: `Run 'gangtise ai ${name}-check --data-id ${dataId}' in ~2 minutes to get results` }, format, options.output);
+            return;
+        }
+        process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
+        const outcome = await pollAsyncContent(client, spec.content, dataId, format, options.output);
+        if (outcome !== "ok") {
+            if (outcome === "timeout") {
+                process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai ${name}-check --data-id ${dataId}\n`);
+            }
+            markFailed();
+        }
+    }));
+    ai.command(`${name}-check`).requiredOption("--data-id <id>", `dataId from ${name}`).option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient((client) => checkAsyncContent(client, spec.content, options.dataId, parseOutputFormat(options.format), options.output)));
+}
+ai.command("knowledge-batch")
+    .option("--query <text>", "Query text; repeat for up to 5. Each --query is taken whole — commas inside it are part of the question, not separators", collectText, [])
+    .option("--top <number>", "Max results (default: 10, max: 20)", "10")
+    .option("--resource-type <number>", "Resource type", numberListArg("--resource-type"), [])
+    .option("--knowledge-name <name>", "Knowledge name", collectList, [])
+    .option("--start-time <datetime>", "13/10-digit epoch or YYYY-MM-DD[ HH:mm[:ss]] (space or T)")
+    .option("--end-time <datetime>", "13/10-digit epoch or YYYY-MM-DD[ HH:mm[:ss]] (space or T)")
+    .option("--format <format>", "Output format", "json")
+    .option("--output <path>")
+    .action((options) => {
+    if (!options.query.length)
+        throw new ValidationError("--query is required: pass at least one --query");
+    return emit(options, (client) => client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 20 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time") }));
+});
+ai.command("knowledge-resource-download").requiredOption("--resource-type <number>").requiredOption("--source-id <id>").option("--output <path>").action((options) => withClient(async (client) => {
+    await runDownload(client, "ai.knowledge-resource.download", { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }, {
+        output: options.output,
+        fallbackName: `resource-${options.sourceId}`,
+    });
+}));
+query(ai, "security-clue", {
+    endpoint: "ai.security-clue.list",
+    fields: [
+        from(), size(),
+        field(new Option("--start-time <datetime>", "Start time").argParser(datetimeArg("--start-time")).makeOptionMandatory(), (v) => ({ startTime: v })),
+        field(new Option("--end-time <datetime>", "End time").argParser(datetimeArg("--end-time")).makeOptionMandatory(), (v) => ({ endTime: v })),
+        field(new Option("--query-mode <mode>").choices(["bySecurity", "byIndustry"]).makeOptionMandatory(), (v) => ({ queryMode: v })),
+        list("--gts-code <code>", "GTS code", "gtsCodeList"),
+        list("--source <name>", "Source", "source"),
+        format(), output(),
+    ],
+});
+query(ai, "one-pager", { endpoint: "ai.one-pager", fields: [required("--security-code <code>", undefined, "securityCode"), format("json"), output()] });
+query(ai, "investment-logic", { endpoint: "ai.investment-logic", fields: [required("--security-code <code>", undefined, "securityCode"), format("json"), output()] });
+query(ai, "peer-comparison", { endpoint: "ai.peer-comparison", fields: [required("--security-code <code>", undefined, "securityCode"), format("json"), output()] });
+addGenerationTask("earnings-review", {
+    submit: "ai.earnings-review.get-id",
+    content: "ai.earnings-review.get-content",
+    label: "Earnings review",
+    idFailure: "Failed to get earnings review ID. The report may not be available yet.",
+    fields: [required("--security-code <code>", undefined, "securityCode"), required("--period <period>", "Report period (e.g. 2025q3, 2025interim, 2025annual)", "period")],
+});
+query(ai, "theme-tracking", {
+    endpoint: "ai.theme-tracking",
+    fields: [
+        required("--theme-id <id>", "Theme ID (use 'reference concept-search')", "themeId"),
+        date("--date <date>", "Date (yyyy-MM-dd)", "date", { required: true }),
+        list("--type <name>", "Report type: morning/night", "type"),
+        format("json"), output(),
+    ],
+});
+query(ai, "research-outline", { endpoint: "ai.research-outline", fields: [required("--security-code <code>", undefined, "securityCode"), format("json"), output()] });
+ai.command("hot-topic")
+    .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)", dateArg("--start-date"))
+    .option("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date"))
+    .option("--category <name>", "Report type: morningBriefing/noonBriefing/afternoonFlash/eveningBriefing", collectList, [])
+    .option("--with-related-securities", "Include related securities info")
+    .option("--no-with-related-securities", "Exclude related securities info")
+    .option("--with-close-reading", "Include close reading content")
+    .option("--no-with-close-reading", "Exclude close reading content")
+    .option("--format <format>", "Output format", "json")
+    .option("--output <path>")
+    .action((options) => emit(options, (client) => {
+    const ALL_CATEGORIES = ["morningBriefing", "noonBriefing", "afternoonFlash", "eveningBriefing"];
+    return client.call("ai.hot-topic", {
+        from: parseFrom(options.from),
+        size: parseSize(options.size),
+        startDate: options.startDate,
+        endDate: options.endDate,
+        categoryList: options.category.length > 0 ? options.category : ALL_CATEGORIES,
+        withRelatedSecurities: options.withRelatedSecurities !== false,
+        withCloseReading: options.withCloseReading !== false,
+    });
+}));
+query(ai, "management-discuss-announcement", {
+    endpoint: "ai.management-discuss-announcement",
+    fields: [
+        date("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)", "reportDate", { required: true }),
+        required("--security-code <code>", "Security code (e.g. 000001.SZ)", "securityCode"),
+        field(new Option("--dimension <name>", "Discussion dimension: businessOperation/financialPerformance/developmentAndRisk/all").choices(["businessOperation", "financialPerformance", "developmentAndRisk", "all"]).makeOptionMandatory(), (v) => ({ discussionDimension: v })),
+        format("json"), output(),
+    ],
+});
+query(ai, "management-discuss-earnings-call", {
+    endpoint: "ai.management-discuss-earnings-call",
+    fields: [
+        date("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)", "reportDate", { required: true }),
+        required("--security-code <code>", "Security code (e.g. 000001.SZ)", "securityCode"),
+        field(new Option("--dimension <name>", "Discussion dimension").choices(["businessOperation", "financialPerformance", "developmentAndRisk"]).makeOptionMandatory(), (v) => ({ discussionDimension: v })),
+        format("json"), output(),
+    ],
+});
+addGenerationTask("viewpoint-debate", {
+    submit: "ai.viewpoint-debate.get-id",
+    content: "ai.viewpoint-debate.get-content",
+    label: "Viewpoint debate",
+    idFailure: "Failed to get viewpoint debate ID.",
+    fields: [required("--viewpoint <text>", "Viewpoint text (max 1000 chars)", "viewpoint")],
+});
+const STOCK_SUMMARY_MAX_SECURITIES = 6000;
+ai.command("stock-summary")
+    .description("Stock highlights: refined research summary per security (A-share / HK)")
+    .option("--security <code>", `Security code (e.g. 600519.SH / 00700.HK), up to ${STOCK_SUMMARY_MAX_SECURITIES} per call; market keywords are NOT supported by this endpoint`, collectList, [])
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => {
+    if (!options.security.length)
+        throw new ValidationError(`--security is required: pass one or more security codes (A-share / HK), up to ${STOCK_SUMMARY_MAX_SECURITIES} per call`);
+    if (options.security.length > STOCK_SUMMARY_MAX_SECURITIES) {
+        throw new ValidationError(`ai stock-summary: ${options.security.length} securities in one call — the endpoint takes at most ${STOCK_SUMMARY_MAX_SECURITIES}. Split the codes into batches of at most ${STOCK_SUMMARY_MAX_SECURITIES} and run one call per batch.`);
+    }
+    checkMarketKeywords(options.security, [], "ai stock-summary");
+    return emit(options, (client) => client.call("ai.stock-summary.list", { securityList: maybeArray(options.security) }));
+});

package/dist/src/commands/alternative.js

@@ -0,0 +1,56 @@
+import { Command, Option } from "commander";
+import { collectList, dateArg, parseNumberOption } from "../core/args.js";
+import { assertColumnarHeader, zipFieldRow } from "../core/normalize.js";
+import { parseOutputFormat } from "../core/output.js";
+import { printData } from "../core/printer.js";
+import { withClient, field, required, flag, format, output, query } from "./shared.js";
+export const alternative = new Command("alternative").description("Alternative data APIs");
+query(alternative, "edb-search", {
+    endpoint: "alternative.edb-search",
+    fields: [
+        required("--keyword <text>", "Search keyword (e.g. '空调')", "keyword"),
+        field(new Option("--limit <number>", "Max results (default: 100, max: 200)").default("100"), (v) => ({ limit: parseNumberOption(v, "--limit", { integer: true, min: 1, max: 200 }) })),
+        format(), output(),
+    ],
+});
+alternative.command("edb-data")
+    .option("--indicator-id <id>", "Indicator ID (repeat, max 10)", collectList, [])
+    .requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date"))
+    .requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date"))
+    .option("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const raw = await client.call("alternative.edb-data", {
+        indicatorIdList: options.indicatorId,
+        startDate: options.startDate,
+        endDate: options.endDate,
+    });
+    let data = raw;
+    if (raw && Array.isArray(raw.fieldList) && Array.isArray(raw.dataList)) {
+        const fields = raw.fieldList;
+        assertColumnarHeader(fields, raw);
+        const list = raw.dataList.map((row) => zipFieldRow(fields, row, raw));
+        data = { list, total: list.length };
+    }
+    await printData(data, format, options.output);
+}));
+const CONCEPT_ID = "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'";
+query(alternative, "concept-info", {
+    description: "Concept profile: definition, investment logic, industry space, competitive landscape (50 credits/call)",
+    endpoint: (options) => options.full ? "alternative.concept-info-full" : "alternative.concept-info",
+    fields: [
+        required("--concept-id <id>", CONCEPT_ID, "conceptId"),
+        flag("--full", "Also return catalyst events (keyEvents) via the v1 endpoint — 500 credits/call instead of 50"),
+        format("json"), output(),
+    ],
+});
+query(alternative, "concept-securities", {
+    description: "Concept constituents, grouped (50 credits/call; free when the concept has none)",
+    endpoint: (options) => options.full ? "alternative.concept-securities-full" : "alternative.concept-securities",
+    fields: [
+        required("--concept-id <id>", CONCEPT_ID, "conceptId"),
+        flag("--full", "Also return the key-stock flag (isKey) and inclusion reason via the v1 endpoint — 500 credits/call instead of 50"),
+        format("json"), output(),
+    ],
+});

package/dist/src/commands/auth.js

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { readTokenCache, redactTokenCache } from "../core/auth.js";
+import { loadConfig } from "../core/config.js";
+import { parseOutputFormat } from "../core/output.js";
+import { printData } from "../core/printer.js";
+import { emit } from "./shared.js";
+export const auth = new Command("auth")
+    .description("Authentication commands")
+    .addCommand(new Command("login")
+    .option("--show-token", "Show the raw access token (default: redacted)")
+    .option("--format <format>", "Output format", "json")
+    .action((options) => emit(options, async (client) => {
+    const result = await client.login();
+    const note = result.source === "env-token"
+        ? "GANGTISE_TOKEN is set, so this is the token every command will send — no login was performed. Unset it to use GANGTISE_ACCESS_KEY / GANGTISE_SECRET_KEY instead."
+        : undefined;
+    const base = { source: result.source, ...(note ? { note } : {}) };
+    return options.showToken
+        ? { ...base, authorization: result.authorization, cache: result.cache }
+        : { ...base, authorization: "<redacted>", cache: redactTokenCache(result.cache) };
+})))
+    .addCommand(new Command("status")
+    .option("--format <format>", "Output format", "json")
+    .action(async (options) => {
+    const config = loadConfig();
+    const cache = await readTokenCache(config.tokenCachePath);
+    await printData({ hasEnvToken: Boolean(config.token), hasCachedToken: Boolean(cache?.accessToken), cache: redactTokenCache(cache) }, parseOutputFormat(options.format));
+}));
+export const lookup = new Command("lookup").description("Local lookup tables (IDs not covered by 'reference constant-list')");
+const addLookupList = (name, endpointKey, description) => {
+    const cmd = new Command(name);
+    if (description)
+        cmd.description(description);
+    lookup.addCommand(cmd.addCommand(new Command("list").option("--format <format>", "Output format", "table").action((options) => emit(options, (client) => client.call(endpointKey)))));
+};
+addLookupList("broker-org", "lookup.broker-orgs.list");
+addLookupList("meeting-org", "lookup.meeting-orgs.list");

package/dist/src/commands/bond.js

@@ -0,0 +1,76 @@
+import { Command, Option } from "commander";
+import { collectList, dateArg, maybeArray, parseNumberOption } from "../core/args.js";
+import { ValidationError } from "../core/errors.js";
+import { emit } from "./shared.js";
+export const bond = new Command("bond").description("Bond APIs: profiles, issuers, quotes, valuations, cash flows, ratings, announcements");
+function requireBondCodes(codes, max) {
+    if (!codes.length)
+        throw new ValidationError("--security is required: pass one or more bond codes, e.g. --security 019742.SH --security 220205.IB");
+    const unique = [...new Set(codes)];
+    if (max && unique.length > max)
+        throw new ValidationError(`${unique.length} distinct bond codes in one call — this endpoint takes at most ${max}. Split them into batches of ${max} and run one call per batch.`);
+    return unique;
+}
+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' 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>");
+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"))
+    .action((options) => emit(options, (client) => client.call(endpointKey, { securityList: requireBondCodes(options.security, max), startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) })));
+bondSecurityOption(bond.command("basic-info").description("Bond static profiles: issuance, term, coupon, rating, guarantee, special terms"))
+    .action((options) => emit(options, (client) => client.call("bond.basic-info", { securityList: requireBondCodes(options.security, 10000), fieldList: maybeArray(options.field) })));
+bondSecurityOption(bond.command("rating-overview").description("Bond, issuer and guarantor ratings side by side"))
+    .action((options) => emit(options, (client) => client.call("bond.rating-overview", { securityList: requireBondCodes(options.security, 10), fieldList: maybeArray(options.field) })));
+addBondRange("cash-flow", "bond.cash-flow", "Interest payment and redemption schedule per bond", "Payment date");
+addBondRange("issuance-detail", "bond.issuance-detail", "Issuance and re-issuance records: bidding, pricing, cover ratios", "Issue announcement date");
+addBondRange("rating-change", "bond.rating-change", "Bond rating change history: current vs previous rating, direction, outlook, agency (max 10 bonds per call)", "Announcement date", 10);
+addBondRange("exercise-notice", "bond.exercise-notice", "Put/call exercise schedule and results for option-embedded bonds", "Exercise date");
+bondSecurityOption(bond.command("daily-quote").description("Daily close quotes (exchange + CFETS): dirty/clean price, YTM, duration, convexity"))
+    .requiredOption("--start-date <date>", "Trade date range start (yyyy-MM-dd)", dateArg("--start-date"))
+    .requiredOption("--end-date <date>", "Trade date range end (yyyy-MM-dd)", dateArg("--end-date"))
+    .action((options) => emit(options, (client) => client.call("bond.daily-quote", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) })));
+bondSecurityOption(bond.command("valuation").description("Shanghai Clearing House valuations: price, yield, duration, convexity, PVBP"))
+    .requiredOption("--start-date <date>", "Valuation date range start (yyyy-MM-dd)", dateArg("--start-date"))
+    .requiredOption("--end-date <date>", "Valuation date range end (yyyy-MM-dd)", dateArg("--end-date"))
+    .addOption(new Option("--confidence-level <level>", "Valuation confidence; defaults to 推荐 server-side, which already filters out 不推荐").choices(["推荐", "不推荐"]))
+    .action((options) => emit(options, (client) => client.call("bond.valuation", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, confidenceLevel: options.confidenceLevel, fieldList: maybeArray(options.field) })));
+function issuerSelector(security, issuer) {
+    if (security.length && issuer.length)
+        throw new ValidationError("--security and --issuer are mutually exclusive: pass bond codes or issuer names, not both");
+    if (!security.length && !issuer.length)
+        throw new ValidationError("pass either --security (bond codes) or --issuer (issuer names)");
+    return security.length ? { securityList: security } : { issuerNameList: issuer };
+}
+const issuerNameOption = (command) => command.option("--issuer <name>", "Issuer name, full or short (repeatable); fuzzy-matched, one best hit per name", collectList, []);
+issuerNameOption(bondSecurityOption(bond.command("issuer-info").description("Issuer profiles: nature, SW industry, registration, rating, outstanding bonds")))
+    .action((options) => emit(options, (client) => client.call("bond.issuer-info", { ...issuerSelector(options.security, options.issuer), fieldList: maybeArray(options.field) })));
+issuerNameOption(bondSecurityOption(bond.command("issuer-rating-change").description("Issuer rating change history (at most 10 issuers matched per call)")))
+    .option("--start-date <date>", "Announcement date range start (yyyy-MM-dd); omit for all history", dateArg("--start-date"))
+    .option("--end-date <date>", "Announcement date range end (yyyy-MM-dd); omit for all history", dateArg("--end-date"))
+    .action((options) => emit(options, (client) => client.call("bond.issuer-rating-change", { ...issuerSelector(options.security, options.issuer), startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) })));
+bond.command("issuance-plan").description("Rate-bond issuance calendar over a date range")
+    .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>")
+    .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"))
+    .option("--end-date <date>", "Announcement date range end (yyyy-MM-dd); mutually exclusive with --security", dateArg("--end-date"))
+    .option("--page-no <number>", "Page number, from 1. No total is returned: increment until a page comes back empty", "1")
+    .option("--page-size <number>", "Rows per page, 1-200", "50")
+    .action((options) => emit(options, (client) => {
+    const byDate = Boolean(options.startDate || options.endDate);
+    if (options.security.length && byDate)
+        throw new ValidationError("--security and --start-date/--end-date are mutually exclusive on bond announcement: filter by bond codes or by date range, not both");
+    if (!options.security.length && !byDate)
+        throw new ValidationError("pass either --security (bond codes) or --start-date/--end-date (announcement date range)");
+    return client.call("bond.announcement", {
+        securityList: maybeArray(options.security), startDate: options.startDate, endDate: options.endDate,
+        pageNo: parseNumberOption(options.pageNo, "--page-no", { integer: true, min: 1 }),
+        pageSize: parseNumberOption(options.pageSize, "--page-size", { integer: true, min: 1, max: 200 }),
+        fieldList: maybeArray(options.field),
+    });
+}));

package/dist/src/commands/fundamental.js

@@ -0,0 +1,137 @@
+import { Command, Option } from "commander";
+import { collectList, dateArg, localDateString, maybeArray, parseOptionalNumberOption } from "../core/args.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";
+export const fundamental = new Command("fundamental").description("Fundamental APIs");
+const addFinancialReport = (name, endpointKey, periodHelp = "Period") => query(fundamental, name, {
+    endpoint: endpointKey,
+    fields: [
+        required("--security-code <code>", undefined, "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("--report-type <type>", "Report type", "reportType"),
+        list("--field <field>", "Field", "fieldList"),
+        format(), output(),
+    ],
+});
+addFinancialReport("income-statement", "fundamental.income-statement");
+addFinancialReport("income-statement-quarterly", "fundamental.income-statement-quarterly", "Period: q1/q2/q3/q4/latest");
+addFinancialReport("balance-sheet", "fundamental.balance-sheet");
+addFinancialReport("cash-flow", "fundamental.cash-flow");
+addFinancialReport("cash-flow-quarterly", "fundamental.cash-flow-quarterly", "Period: q1/q2/q3/q4/latest");
+addFinancialReport("income-statement-hk", "fundamental.income-statement-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
+addFinancialReport("balance-sheet-hk", "fundamental.balance-sheet-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
+addFinancialReport("cash-flow-hk", "fundamental.cash-flow-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
+addFinancialReport("income-statement-us", "fundamental.income-statement-us", "Period: q1/h1/q3/nsd/annual/latest");
+addFinancialReport("balance-sheet-us", "fundamental.balance-sheet-us", "Period: q1/h1/q3/nsd/annual/latest");
+addFinancialReport("cash-flow-us", "fundamental.cash-flow-us", "Period: q1/h1/q3/nsd/annual/latest");
+query(fundamental, "main-business", {
+    endpoint: "fundamental.main-business",
+    fields: [
+        required("--security-code <code>", undefined, "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 })),
+        list("--period <type>", "Period: interim/annual", "periodList"),
+        list("--field <field>", "Field", "fieldList"),
+        format(), output(),
+    ],
+});
+const VALUATION_DEFAULT_LIMIT = 2000;
+function valuationFieldsToSend(fields) {
+    const unique = [...new Set(fields)];
+    const values = unique.filter((field) => field !== "tradeDate");
+    return values.length > 0 ? values : unique;
+}
+const VALUATION_VALUE_COLUMNS = ["value", "percentileRank", "average", "median", "upper1Std", "lower1Std"];
+function rowsIn(data) {
+    const normalized = normalizeRows(data);
+    const list = Array.isArray(normalized) ? normalized : normalized?.list;
+    return Array.isArray(list) ? list.length : 0;
+}
+function firstRowTradeDate(data) {
+    const normalized = normalizeRows(data);
+    const list = Array.isArray(normalized) ? normalized : normalized?.list;
+    const first = Array.isArray(list) ? list[0] : undefined;
+    const value = first && typeof first === "object" ? first.tradeDate : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+fundamental.command("valuation-analysis")
+    .requiredOption("--security-code <code>")
+    .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"))
+    .option("--limit <number>", "Max rows (default: 2000). One row per calendar day, weekends included, and the most recent are kept — a range longer than the limit loses its START (flagged partial, exit 3)")
+    .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>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const requested = maybeArray(options.field);
+    const filterFields = options.skipNull && requested ? ["value", "percentileRank"].filter((field) => !requested.includes(field)) : [];
+    const fieldList = requested && valuationFieldsToSend([...requested, ...filterFields]);
+    const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }) ?? VALUATION_DEFAULT_LIMIT;
+    let data = await client.call("fundamental.valuation-analysis", { securityCode: options.securityCode, indicator: options.indicator, startDate: options.startDate, endDate: options.endDate, limit, fieldList });
+    if (fieldList && !fieldList.some((field) => VALUATION_VALUE_COLUMNS.includes(field)) && rowsIn(data) === 0) {
+        process.stderr.write(`[gangtise] note: no rows came back, and --field names no value column (${fieldList.join(", ")}). This endpoint answers such a request with an empty list rather than an error, so it says nothing about whether data exists: add one of ${VALUATION_VALUE_COLUMNS.join(" / ")}, or drop --field.\n`);
+    }
+    const firstDate = firstRowTradeDate(data);
+    if (!(options.startDate && firstDate === options.startDate)) {
+        flagIfLimitTruncated(data, limit, "fundamental valuation-analysis", "--start-date", `The API keeps the most recent rows, so it is the START of the range that is missing. The series has one row per calendar day (weekends included): raise --limit to at least the number of days in the range (e.g. --limit 4000 for ten years within your account's history window), or move --start-date later.`);
+    }
+    if (options.startDate && firstDate && firstDate > options.startDate && !data.partial) {
+        process.stderr.write(`[gangtise] note: the series starts at ${firstDate}, later than --start-date ${options.startDate}. Either the security listed later, or the range reaches past your account's history window — this endpoint returns what lies inside the window without an error.\n`);
+    }
+    if (options.skipNull) {
+        const normalized = normalizeRows(data);
+        const rec = (Array.isArray(normalized) ? { list: normalized } : normalized);
+        if (rec && typeof rec === "object") {
+            if (Array.isArray(rec.list)) {
+                const filtered = rec.list.filter((row) => {
+                    if (!row || typeof row !== "object")
+                        return false;
+                    const r = row;
+                    return r.value != null && r.percentileRank != null;
+                }).map((row) => {
+                    if (filterFields.length === 0)
+                        return row;
+                    const r = { ...row };
+                    for (const field of filterFields)
+                        delete r[field];
+                    return r;
+                });
+                data = { ...rec, list: filtered, total: filtered.length };
+            }
+        }
+    }
+    await printData(data, format, options.output);
+}));
+query(fundamental, "top-holders", {
+    endpoint: "fundamental.top-holders",
+    fields: [
+        required("--security-code <code>", undefined, "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"),
+        list("--fiscal-year <year>", "Fiscal year", "fiscalYear"),
+        list("--period <period>", "Period: q1/interim/q3/annual/latest", "period"),
+        format(), output(),
+    ],
+});
+fundamental.command("earning-forecast")
+    .requiredOption("--security-code <code>")
+    .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("--format <format>", "Output format", "table")
+    .option("--output <path>")
+    .action((options) => emit(options, (client) => {
+    const endDate = options.endDate ?? localDateString(new Date());
+    const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    return client.call("fundamental.earning-forecast", { securityCode: options.securityCode, startDate, endDate, consensusList: maybeArray(options.consensus) });
+}));

package/dist/src/commands/indicator.js

@@ -0,0 +1,134 @@
+import { Command, Option } from "commander";
+import { collectList, dateArg, screenerExpressionFields, parseNumberOption, parseScreenerIndicators } from "../core/args.js";
+import { buildIndicatorCrossSectionBody, buildIndicatorScreenerBody, buildIndicatorTimeSeriesBody } from "../core/commandBodies.js";
+import { checkScreenerBindings, droppedFromMatrix, flattenCrossSection, flattenTimeSeries, isEmptyMatrix, requireIndicatorMatrix, unwrapIndicatorData } from "../core/indicatorMatrix.js";
+import { resolveCalendarType } from "../core/calendarType.js";
+import { ValidationError } from "../core/errors.js";
+import { parseOutputFormat } from "../core/output.js";
+import { printData } from "../core/printer.js";
+import { withClient } from "./shared.js";
+function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
+    if (isEmptyMatrix(data)) {
+        process.stderr.write("[gangtise] note: the query returned no data at all. Since a real coverage gap now comes back as a null cell rather than an empty table, this usually means NOTHING in the request resolved — every security code or every indicator code was unrecognised — or a parameter name is wrong. Cross-check codes against 'gangtise indicator search --format json' and 'gangtise reference securities-search'.\n");
+        return;
+    }
+    const { securities, indicators } = droppedFromMatrix(data, requestedSecurities, requestedIndicators);
+    if (securities.length === 0 && indicators.length === 0)
+        return;
+    if (rows && typeof rows === "object" && !Array.isArray(rows)) {
+        const rec = rows;
+        rec.partial = true;
+        if (indicators.length > 0)
+            rec.omittedIndicators = indicators;
+        if (securities.length > 0)
+            rec.omittedSecurities = securities;
+    }
+    const parts = [];
+    if (indicators.length > 0)
+        parts.push(`indicators ${indicators.join(", ")}`);
+    if (securities.length > 0)
+        parts.push(`securities ${securities.join(", ")}`);
+    process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely — no row/column at all, not a null one. A code the server merely has no data for still comes back as null, so this normally means the code itself was not recognised: check it for typos and, for securities, for the wrong market suffix (US tickers are .O/.N, not .US). Result marked partial (exit 3).\n`);
+}
+function requireIndicatorScope(indicators, securities) {
+    const missing = [indicators.length === 0 ? "--indicator" : "", securities.length === 0 ? "--security" : ""].filter(Boolean);
+    if (missing.length > 0) {
+        throw new ValidationError(`${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} required (repeat the flag for multiple values)`);
+    }
+}
+export const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series, screener");
+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>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const raw = await client.call("indicator.search", {
+        keyword: options.keyword,
+        limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 100 }),
+    });
+    await printData(unwrapIndicatorData(raw), format, options.output);
+}));
+indicator.command("cross-section")
+    .option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, [])
+    .option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, [])
+    .requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate. Report-period indicators (is_*, financial statements) REJECT tradeDate and require --indicator-param 'code:reportDate=yyyy-MM-dd' instead — check parameterList in 'indicator search'", dateArg("--date"))
+    .option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)")
+    .option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)")
+    .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", collectList, [])
+    .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>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
+    const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
+    const data = requireIndicatorMatrix(raw);
+    const rows = flattenCrossSection(data, options.keyBy);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
+}));
+indicator.command("time-series")
+    .option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, [])
+    .option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, [])
+    .requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date"))
+    .requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date"))
+    .option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday. Omit it and the CLI picks: a free 'indicator search' reads each parameterList and sends TD only when EVERY indicator is trading-day typed, otherwise it leaves the server on ND (report-period indicators land on dates a trading calendar lacks, and TD would answer them with an all-null grid). An explicit value is sent as given, with no lookup")
+    .option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)")
+    .option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)")
+    .option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, [])
+    .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>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
+    const body = buildIndicatorTimeSeriesBody(options);
+    if (!body.calendarType) {
+        const resolved = await resolveCalendarType(client, options.indicator);
+        if (resolved) {
+            body.calendarType = resolved;
+            process.stderr.write(`[gangtise] note: every requested indicator takes tradeDate, so this series was fetched on the trading-day calendar (calendarType=TD) instead of the server default ND — no all-null non-trading rows, and fewer cells against the 30000 cap. Pass --calendar-type ND to override.\n`);
+        }
+    }
+    const raw = await client.call("indicator.time-series", body);
+    const data = requireIndicatorMatrix(raw);
+    const rows = flattenTimeSeries(data, options.keyBy, options.security);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
+}));
+indicator.command("screener")
+    .description("Screen securities by an expression over indicator values (条件选股)")
+    .option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (REQUIRED, repeat)", collectList, [])
+    .option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, [])
+    .requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators")
+    .requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — omitting it leaves date-bearing indicators unfiltered and silently yields an empty screen. Report-period indicators (is_*) reject tradeDate: give them --indicator-param 'F1:reportDate=yyyy-MM-dd'", dateArg("--date"))
+    .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", collectList, [])
+    .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>")
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
+    const bindings = parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression);
+    const raw = await client.call("indicator.screener", buildIndicatorScreenerBody(options));
+    const data = requireIndicatorMatrix(raw);
+    const rows = flattenCrossSection(data, options.keyBy);
+    const filteredOn = screenerExpressionFields(options.expression);
+    const unbound = checkScreenerBindings(data, bindings, options.expression);
+    if (data.securityCodeList.length === 0) {
+        process.stderr.write("[gangtise] note: nothing matched the expression. That is a normal answer — but an empty result is ALSO what an unrecognised code or a wrong parameter name produces. Cross-check the indicator codes and parameters against 'gangtise indicator search --format json'.\n");
+    }
+    if (unbound.length > 0) {
+        const rec = rows;
+        rec.partial = true;
+        rec.omittedIndicators = unbound.map((field) => bindings.find((b) => b.field === field)?.indicatorCode ?? field);
+        const alsoFiltered = unbound.filter((field) => filteredOn.includes(field));
+        const filterNote = alsoFiltered.length > 0
+            ? ` The expression also filters on ${alsoFiltered.join(", ")}, so that condition was applied to none of these rows — another branch of the expression could still have matched them legitimately, but verify before relying on that filter.`
+            : "";
+        process.stderr.write(`[gangtise] warning: ${unbound.join(", ")} produced no column at all — those output values are missing. An indicator the server merely has no data for still returns a null column, so this normally means the bound code was not recognised; check it against 'gangtise indicator search'.${filterNote} Result marked partial (exit 3).\n`);
+    }
+    await printData(rows, format, options.output);
+}));