gangtise-openapi-cli 0.10.9 → 0.10.10

package/README.md

@@ -193,6 +193,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **有时间范围时**（传了 `--start-time/--end-time` 或 `--start-date/--end-date`）：**省略 `--size`**，CLI 自动翻页查全
 - **无时间范围时**（未传时间参数）：默认 `--size 200`，防止一次查询数据量过大
 - 如果显式传了 `--size`，则按指定值翻页，直到达到 `size` 或数据取完
+- `--from` 必须是非负整数，`--size` 必须是正整数；非法数字会在本地直接报 `ValidationError`，不会继续请求 API
 - 安全上限：自动翻页最多 1000 页，防止异常循环
 - 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`），同时 stderr 输出 `Total: N, showing: M`
 
@@ -362,10 +363,23 @@ gangtise raw call insight.opinion.list --body '{"from":0,"size":120}'
 
 所有格式均支持 `--output <path>` 输出到文件（自动创建父目录）。
 
+## 参数校验
+
+CLI 会在本地校验常见数值参数，避免把明显非法的请求发到 API：
+
+- `--from`：非负整数
+- `--size` / `--limit` / `--top`：正整数
+- `--file-type` / `--resource-type` 以及数值型列表参数：有限数字
+- 公告 `--start-time` / `--end-time`：可解析的时间字符串或 Unix 时间戳
+
+校验失败会输出 `ValidationError: Invalid ...` 并以非 0 状态退出。
+
 ## 常见错误
 
-| 错误码 | 说明 |
-|--------|------|
+| 错误/错误码 | 说明 |
+|-----------|------|
+| `ValidationError` | 本地参数校验失败，检查 `--size` / `--limit` / `--from` / `--file-type` 等数值参数 |
+| `API error (HTTP 4xx/5xx)` | HTTP 层失败；CLI 会把 4xx/5xx 响应视为错误，即使响应体不是标准 `{code,msg,data}` 信封 |
 | `8000014` | `GANGTISE_ACCESS_KEY` 错误 |
 | `8000015` | `GANGTISE_SECRET_KEY` 错误 |
 | `8000016` | 开发账号状态异常 |

package/dist/src/cli.js

@@ -1,244 +1,19 @@
 #!/usr/bin/env node
 import { Command, Option } from "commander";
-import { collectKeyValue, collectList, collectNumberList, maybeArray, toTimestamp13 } from "./core/args.js";
+import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
+import { readTokenCache } from "./core/auth.js";
+import { collectKeyValue, collectList, collectNumberList, maybeArray, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
 import { loadConfig } from "./core/config.js";
-import { ApiError, ConfigError, DownloadError } from "./core/errors.js";
+import { resolveTitle, saveDownloadResult } from "./core/download.js";
+import { ApiError, ConfigError } from "./core/errors.js";
+import { normalizeRows } from "./core/normalize.js";
+import { parseOutputFormat } from "./core/output.js";
+import { printData } from "./core/printer.js";
 // --- Lazy-loaded modules (deferred to action handlers) ---
 async function createClient() {
     const { GangtiseClient } = await import("./core/client.js");
     return new GangtiseClient(loadConfig());
 }
-async function readTokenCache(...args) {
-    return (await import("./core/auth.js")).readTokenCache(...args);
-}
-async function normalizeRows(...args) {
-    return (await import("./core/normalize.js")).normalizeRows(...args);
-}
-async function renderOutput(...args) {
-    return (await import("./core/output.js")).renderOutput(...args);
-}
-async function saveOutputIfNeeded(...args) {
-    return (await import("./core/output.js")).saveOutputIfNeeded(...args);
-}
-function parseFormat(value) {
-    const format = value ?? "table";
-    if (["table", "json", "jsonl", "csv", "markdown"].includes(format)) {
-        return format;
-    }
-    throw new ConfigError(`Unsupported format: ${format}`);
-}
-// --- Title cache: list writes, download reads ---
-let _titleCachePath;
-function getTitleCachePath() {
-    if (!_titleCachePath) {
-        const path = require("node:path");
-        const os = require("node:os");
-        _titleCachePath = path.join(os.homedir(), ".config", "gangtise", "title-cache.json");
-    }
-    return _titleCachePath;
-}
-const TITLE_LOOKUP_SIZE = 200;
-const TITLE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-async function readTitleCache() {
-    try {
-        const fs = await import("node:fs/promises");
-        return JSON.parse(await fs.readFile(getTitleCachePath(), "utf8"));
-    }
-    catch {
-        return {};
-    }
-}
-async function writeTitleCache(endpoint, titles) {
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const data = await readTitleCache();
-    data[endpoint] = { titles, ts: Date.now() };
-    await fs.mkdir(path.dirname(getTitleCachePath()), { recursive: true });
-    await fs.writeFile(getTitleCachePath(), JSON.stringify(data), "utf8");
-}
-function lookupTitleCache(data, endpoint, id) {
-    const entry = data[endpoint];
-    if (!entry || Date.now() - entry.ts > TITLE_CACHE_TTL_MS)
-        return undefined;
-    return entry.titles[id];
-}
-async function printData(data, format, output, cache) {
-    const normalized = await normalizeRows(data);
-    const items = Array.isArray(normalized)
-        ? normalized
-        : (normalized && typeof normalized === "object" && Array.isArray(normalized.list))
-            ? normalized.list
-            : null;
-    if (cache && items) {
-        const titleField = cache.titleField ?? "title";
-        const titles = {};
-        for (const row of items) {
-            if (row && typeof row === "object") {
-                const r = row;
-                const id = r[cache.idField];
-                const title = r[titleField];
-                if (id != null && typeof title === "string" && title)
-                    titles[String(id)] = title;
-            }
-        }
-        if (Object.keys(titles).length > 0)
-            writeTitleCache(cache.endpointKey, titles).catch(() => { });
-    }
-    if (normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
-        const meta = normalized;
-        if (typeof meta.total === "number" && format !== "json") {
-            const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
-            process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
-        }
-    }
-    const content = await renderOutput(normalized, format);
-    if (output) {
-        await saveOutputIfNeeded(content, output);
-        process.stdout.write(`${output}\n`);
-        return;
-    }
-    process.stdout.write(`${content}\n`);
-}
-const MIME_EXT = {
-    "application/pdf": ".pdf",
-    "application/msword": ".doc",
-    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
-    "application/vnd.ms-excel": ".xls",
-    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
-    "application/vnd.ms-powerpoint": ".ppt",
-    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
-    "application/zip": ".zip",
-    "application/x-rar-compressed": ".rar",
-    "application/gzip": ".gz",
-    "application/x-7z-compressed": ".7z",
-    "application/json": ".json",
-    "application/xml": ".xml",
-    "text/plain": ".txt",
-    "text/html": ".html",
-    "text/csv": ".csv",
-    "image/png": ".png",
-    "image/jpeg": ".jpg",
-    "image/gif": ".gif",
-    "image/webp": ".webp",
-    "image/svg+xml": ".svg",
-    "audio/mpeg": ".mp3",
-    "video/mp4": ".mp4",
-    "application/octet-stream": ".bin",
-};
-function extFromContentType(contentType) {
-    if (!contentType)
-        return "";
-    const mime = contentType.split(";")[0].trim().toLowerCase();
-    return MIME_EXT[mime] ?? "";
-}
-/** Resolve a human-readable filename by looking up the title from cache or list endpoint. */
-async function resolveTitle(client, result, listEndpoint, idField, idValue, titleField = "title") {
-    const { extname } = await import("node:path");
-    const file = result;
-    const serverExt = file.filename ? extname(file.filename) : extFromContentType(file.contentType);
-    function buildFilename(rawTitle) {
-        let title = rawTitle.replace(/[/\\:*?"<>|]/g, "_").trim();
-        if (serverExt && !title.toLowerCase().endsWith(serverExt.toLowerCase())) {
-            title += serverExt;
-        }
-        return title;
-    }
-    // 1. Check file-based title cache (populated by prior list command)
-    try {
-        const cacheData = await readTitleCache();
-        const cached = lookupTitleCache(cacheData, listEndpoint, idValue);
-        if (cached)
-            return buildFilename(cached);
-    }
-    catch { /* ignore */ }
-    // 2. Fallback: query list API (scan recent 200 items)
-    try {
-        const resp = await client.call(listEndpoint, { from: 0, size: TITLE_LOOKUP_SIZE });
-        const items = Array.isArray(resp) ? resp : (resp.list ?? []);
-        const match = items.find(f => String(f[idField]) === String(idValue));
-        const rawTitle = match?.[titleField];
-        if (typeof rawTitle === "string" && rawTitle)
-            return buildFilename(rawTitle);
-    }
-    catch { /* ignore */ }
-    return undefined;
-}
-async function saveDownloadResult(result, fallbackName, output) {
-    if (!(result && typeof result === "object")) {
-        throw new DownloadError("Unexpected download response");
-    }
-    const file = result;
-    if (file.data instanceof Uint8Array) {
-        const outputPath = output ?? file.filename ?? (fallbackName + extFromContentType(file.contentType));
-        await saveOutputIfNeeded(file.data, outputPath);
-        process.stdout.write(`${outputPath}\n`);
-        return;
-    }
-    if (typeof file.text === 'string') {
-        const outputPath = output ?? `${fallbackName}.txt`;
-        await saveOutputIfNeeded(file.text, outputPath);
-        process.stdout.write(`${outputPath}\n`);
-        return;
-    }
-    if (typeof file.url === 'string') {
-        if (output) {
-            await saveOutputIfNeeded(file.url, output);
-            process.stdout.write(`${output}\n`);
-            return;
-        }
-        process.stdout.write(`${file.url}\n`);
-        return;
-    }
-    throw new DownloadError("Unexpected download response");
-}
-const POLL_MAX_ATTEMPTS = 12;
-const POLL_DELAY_MS = 15_000;
-function isAsyncPending(error) {
-    return error instanceof ApiError && error.code === "410110";
-}
-async function pollAsyncContent(client, getContentEndpoint, dataId, format, output) {
-    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
-        try {
-            const result = await client.call(getContentEndpoint, { dataId });
-            if (result?.content != null) {
-                await printData(result, format, output);
-                return true;
-            }
-        }
-        catch (error) {
-            if (error instanceof ApiError && error.code === "410111") {
-                process.stderr.write("Content generation failed (terminal). Do not retry.\n");
-                return false;
-            }
-            if (!isAsyncPending(error))
-                throw error;
-        }
-        if (attempt < POLL_MAX_ATTEMPTS) {
-            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in 15s...\n`);
-            await new Promise(resolve => setTimeout(resolve, POLL_DELAY_MS));
-        }
-    }
-    return false;
-}
-async function checkAsyncContent(client, getContentEndpoint, dataId, format, output) {
-    try {
-        const result = await client.call(getContentEndpoint, { dataId });
-        if (result?.content != null) {
-            await printData(result, format, output);
-            return;
-        }
-    }
-    catch (error) {
-        if (error instanceof ApiError && error.code === "410111") {
-            process.stderr.write("Content generation failed (terminal). Do not retry.\n");
-            process.exitCode = 1;
-            return;
-        }
-        if (!isAsyncPending(error))
-            throw error;
-    }
-    process.stdout.write(`${JSON.stringify({ dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
-}
 function addTimeFilters(command) {
     return command
         .option("--from <number>", "Starting offset", "0")
@@ -257,48 +32,48 @@ program
     .option("--format <format>", "Output format", "json")
     .action(async (options) => {
     const client = await createClient();
-    await printData(await client.login(), parseFormat(options.format));
+    await printData(await client.login(), parseOutputFormat(options.format));
 }))
     .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 }, parseFormat(options.format));
+    await printData({ hasEnvToken: Boolean(config.token), hasCachedToken: Boolean(cache?.accessToken), cache }, parseOutputFormat(options.format));
 }));
 const lookup = new Command("lookup").description("Lookup helper APIs");
 lookup
     .addCommand(new Command("research-area").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.research-areas.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.research-areas.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("broker-org").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.broker-orgs.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.broker-orgs.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("meeting-org").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.meeting-orgs.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.meeting-orgs.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("industry").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.industries.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.industries.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("region").description("Foreign report region codes").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.regions.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.regions.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("announcement-category").description("Announcement category codes").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.announcement-categories.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.announcement-categories.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("industry-code").description("Shenwan industry codes for security-clue --gts-code").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.industry-codes.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.industry-codes.list"), parseOutputFormat(options.format));
 })))
     .addCommand(new Command("theme-id").description("Theme IDs for theme-tracking --theme-id").addCommand(new Command("list").option("--format <format>", "Output format", "table").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("lookup.theme-ids.list"), parseFormat(options.format));
+    await printData(await client.call("lookup.theme-ids.list"), parseOutputFormat(options.format));
 })));
 program.addCommand(lookup);
 const insight = new Command("insight").description("Insight APIs");
@@ -314,20 +89,20 @@ const announcement = new Command("announcement");
 addTimeFilters(opinion.command("list").option("--rank-type <number>", "Rank type", "1").option("--research-area <id>", "Research area ID", collectList, []).option("--chief <id>", "Chief ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--concept <id>", "Concept ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--source <source>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.opinion.list", {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime,
-        rankType: Number(options.rankType), keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), chiefList: maybeArray(options.chief),
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
+        rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), chiefList: maybeArray(options.chief),
         securityList: maybeArray(options.security), brokerList: maybeArray(options.broker), industryList: maybeArray(options.industry), conceptList: maybeArray(options.concept),
         llmTagList: maybeArray(options.llmTag), sourceList: maybeArray(options.source),
-    }), parseFormat(options.format), options.output);
+    }), parseOutputFormat(options.format), options.output);
 });
 addTimeFilters(summary.command("list").option("--search-type <number>", "Search type", "1").option("--rank-type <number>", "Rank type", "1").option("--source <number>", "Source type", collectNumberList, []).option("--research-area <id>", "Research area", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Category", collectList, []).option("--market <name>", "Market", collectList, []).option("--participant-role <name>", "Participant role", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.summary.list", {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime,
-        searchType: Number(options.searchType), rankType: Number(options.rankType), keyword: options.keyword, sourceList: options.source.length ? options.source : undefined,
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
+        searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword, sourceList: options.source.length ? options.source : undefined,
         researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution),
         categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
-    }), parseFormat(options.format), options.output, { endpointKey: "insight.summary.list", idField: "summaryId" });
+    }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.summary.list", idField: "summaryId" });
 });
 summary.command("download").requiredOption("--summary-id <id>").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -338,11 +113,11 @@ summary.command("download").requiredOption("--summary-id <id>").option("--output
 const addScheduleList = (command, endpointKey) => addTimeFilters(command.command("list").option("--research-area <id>", "Research area", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--category <name>", "Category", collectList, []).option("--market <name>", "Market", collectList, []).option("--participant-role <name>", "Participant role", collectList, []).option("--broker-type <name>", "Broker type", collectList, []).option("--object <type>", "Object type: company/industry", collectList, []).option("--permission <number>", "Permission", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call(endpointKey, {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
         researchAreaList: maybeArray(options.researchArea), institutionList: maybeArray(options.institution), securityList: maybeArray(options.security),
         categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
         brokerTypeList: maybeArray(options.brokerType), objectList: maybeArray(options.object), permission: options.permission.length ? options.permission : undefined,
-    }), parseFormat(options.format), options.output);
+    }), parseOutputFormat(options.format), options.output);
 });
 addScheduleList(roadshow, "insight.roadshow.list");
 addScheduleList(siteVisit, "insight.site-visit.list");
@@ -351,49 +126,49 @@ addScheduleList(forum, "insight.forum.list");
 addTimeFilters(research.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--broker <id>", "Broker ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--source <type>", "Source type", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.research.list", {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
-        searchType: Number(options.searchType), rankType: Number(options.rankType),
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
+        searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
         brokerList: maybeArray(options.broker), securityList: maybeArray(options.security), industryList: maybeArray(options.industry),
         categoryList: maybeArray(options.category), llmTagList: maybeArray(options.llmTag), ratingList: maybeArray(options.rating),
-        ratingChangeList: maybeArray(options.ratingChange), minReportPages: options.minPages ? Number(options.minPages) : undefined,
-        maxReportPages: options.maxPages ? Number(options.maxPages) : undefined, sourceList: maybeArray(options.source),
-    }), parseFormat(options.format), options.output, { endpointKey: "insight.research.list", idField: "reportId" });
+        ratingChangeList: maybeArray(options.ratingChange), minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }),
+        maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }), sourceList: maybeArray(options.source),
+    }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.research.list", idField: "reportId" });
 });
 research.command("download").requiredOption("--report-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.research.download", undefined, { reportId: options.reportId, fileType: Number(options.fileType) });
+    const result = await client.call("insight.research.download", undefined, { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
     const title = options.output ? undefined : await resolveTitle(client, result, "insight.research.list", "reportId", options.reportId);
     await saveDownloadResult(result, `research-${options.reportId}`, options.output ?? title);
 });
 addTimeFilters(foreignReport.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--region <id>", "Region ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.foreign-report.list", {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
-        searchType: Number(options.searchType), rankType: Number(options.rankType),
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
+        searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
         securityList: maybeArray(options.security), regionList: maybeArray(options.region), categoryList: maybeArray(options.category),
         industryList: maybeArray(options.industry), brokerList: maybeArray(options.broker), llmTagList: maybeArray(options.llmTag),
         ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
-        minReportPages: options.minPages ? Number(options.minPages) : undefined, maxReportPages: options.maxPages ? Number(options.maxPages) : undefined,
-    }), parseFormat(options.format), options.output, { endpointKey: "insight.foreign-report.list", idField: "reportId" });
+        minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }), maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }),
+    }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.foreign-report.list", idField: "reportId" });
 });
 foreignReport.command("download").requiredOption("--report-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.foreign-report.download", undefined, { reportId: options.reportId, fileType: Number(options.fileType) });
+    const result = await client.call("insight.foreign-report.download", undefined, { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
     const title = options.output ? undefined : await resolveTitle(client, result, "insight.foreign-report.list", "reportId", options.reportId);
     await saveDownloadResult(result, `foreign-report-${options.reportId}`, options.output ?? title);
 });
 addTimeFilters(announcement.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--announcement-type <type>", "Announcement type", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.announcement.list", {
-        from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size),
-        startTime: toTimestamp13(options.startTime), endTime: toTimestamp13(options.endTime),
-        searchType: Number(options.searchType), rankType: Number(options.rankType), keyword: options.keyword,
+        from: parseFrom(options.from), size: parseSize(options.size),
+        startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time"),
+        searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword,
         securityList: maybeArray(options.security), announcementTypeList: maybeArray(options.announcementType), categoryList: maybeArray(options.category),
-    }), parseFormat(options.format), options.output, { endpointKey: "insight.announcement.list", idField: "announcementId" });
+    }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.announcement.list", idField: "announcementId" });
 });
 announcement.command("download").requiredOption("--announcement-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.announcement.download", undefined, { announcementId: options.announcementId, fileType: Number(options.fileType) });
+    const result = await client.call("insight.announcement.download", undefined, { announcementId: options.announcementId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
     const title = options.output ? undefined : await resolveTitle(client, result, "insight.announcement.list", "announcementId", options.announcementId);
     await saveDownloadResult(result, `announcement-${options.announcementId}`, options.output ?? title);
 });
@@ -410,45 +185,45 @@ program.addCommand(insight);
 const quote = new Command("quote").description("Quote APIs");
 quote.command("day-kline").option("--security <code>", "Security code (A-share: .SH/.SZ/.BJ, or 'all' for full market)", collectList, []).option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: latest)").option("--limit <number>", "Max rows per request (default: 6000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.day-kline", { securityList: maybeArray(options.security), startDate: options.startDate, endDate: options.endDate, limit: options.limit ? Number(options.limit) : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("quote.day-kline", { securityList: maybeArray(options.security), startDate: options.startDate, endDate: options.endDate, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 quote.command("day-kline-hk").option("--security <code>", "Security code (HK stock: .HK, or 'all' for full market)", collectList, []).option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: latest)").option("--limit <number>", "Max rows per request (default: 6000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.day-kline-hk", { securityList: maybeArray(options.security), startDate: options.startDate, endDate: options.endDate, limit: options.limit ? Number(options.limit) : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("quote.day-kline-hk", { securityList: maybeArray(options.security), startDate: options.startDate, endDate: options.endDate, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 quote.command("minute-kline").option("--security <code>", "Security code (A-share only: .SH/.SZ/.BJ)").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)").option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)").option("--limit <number>", "Max rows per request (default: 5000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.minute-kline", { securityCode: options.security, startTime: options.startTime, endTime: options.endTime, limit: options.limit ? Number(options.limit) : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("quote.minute-kline", { securityCode: options.security, startTime: options.startTime, endTime: options.endTime, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 program.addCommand(quote);
 const fundamental = new Command("fundamental").description("Fundamental APIs");
 fundamental.command("income-statement").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period", collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.income-statement", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.income-statement", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("income-statement-quarterly").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/q2/q3/q4/latest", collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.income-statement-quarterly", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.income-statement-quarterly", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("balance-sheet").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period", collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.balance-sheet", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.balance-sheet", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("cash-flow").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period", collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.cash-flow", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.cash-flow", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("cash-flow-quarterly").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/q2/q3/q4/latest", collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.cash-flow-quarterly", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.cash-flow-quarterly", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("main-business").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").addOption(new Option("--breakdown <type>", "Breakdown: product/industry/region").choices(["product", "industry", "region"]).default("product")).option("--period <type>", "Period: interim/annual", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.main-business", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, breakdown: options.breakdown, periodList: maybeArray(options.period), fieldList: maybeArray(options.field) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.main-business", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, breakdown: options.breakdown, periodList: maybeArray(options.period), fieldList: maybeArray(options.field) }), parseOutputFormat(options.format), options.output);
 });
 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>").option("--end-date <date>").option("--limit <number>").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(async (options) => {
     const client = await createClient();
-    let data = await client.call("fundamental.valuation-analysis", { securityCode: options.securityCode, indicator: options.indicator, startDate: options.startDate, endDate: options.endDate, limit: options.limit ? Number(options.limit) : undefined, fieldList: maybeArray(options.field) });
+    let data = await client.call("fundamental.valuation-analysis", { securityCode: options.securityCode, indicator: options.indicator, startDate: options.startDate, endDate: options.endDate, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) });
     if (options.skipNull) {
         const normalized = await normalizeRows(data);
         if (normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
@@ -464,43 +239,43 @@ fundamental.command("valuation-analysis").requiredOption("--security-code <code>
             }
         }
     }
-    await printData(data, parseFormat(options.format), options.output);
+    await printData(data, parseOutputFormat(options.format), options.output);
 });
 fundamental.command("top-holders").requiredOption("--security-code <code>").addOption(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory()).option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/interim/q3/annual/latest", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("fundamental.top-holders", { securityCode: options.securityCode, holderType: options.holderType, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.top-holders", { securityCode: options.securityCode, holderType: options.holderType, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined }), parseOutputFormat(options.format), options.output);
 });
 fundamental.command("earning-forecast").requiredOption("--security-code <code>").option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: today)").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(async (options) => {
     const client = await createClient();
     const endDate = options.endDate ?? new Date().toISOString().slice(0, 10);
     const startDate = options.startDate ?? new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
-    await printData(await client.call("fundamental.earning-forecast", { securityCode: options.securityCode, startDate, endDate, consensusList: maybeArray(options.consensus) }), parseFormat(options.format), options.output);
+    await printData(await client.call("fundamental.earning-forecast", { securityCode: options.securityCode, startDate, endDate, consensusList: maybeArray(options.consensus) }), parseOutputFormat(options.format), options.output);
 });
 program.addCommand(fundamental);
 const ai = new Command("ai").description("AI APIs");
 ai.command("knowledge-batch").requiredOption("--query <text>", "Query", collectList, []).option("--top <number>", "Top", "10").option("--resource-type <number>", "Resource type", collectNumberList, []).option("--knowledge-name <name>", "Knowledge name", collectList, []).option("--start-time <ms>").option("--end-time <ms>").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.knowledge-batch", { queries: options.query, top: Number(options.top), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: options.startTime ? Number(options.startTime) : undefined, endTime: options.endTime ? Number(options.endTime) : undefined }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseOptionalNumberOption(options.startTime, "--start-time", { integer: true, min: 0 }), endTime: parseOptionalNumberOption(options.endTime, "--end-time", { integer: true, min: 0 }) }), parseOutputFormat(options.format), options.output);
 });
 ai.command("knowledge-resource-download").requiredOption("--resource-type <number>").requiredOption("--source-id <id>").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await saveDownloadResult(await client.call("ai.knowledge-resource.download", undefined, { resourceType: Number(options.resourceType), sourceId: options.sourceId }), `resource-${options.sourceId}`, options.output);
+    await saveDownloadResult(await client.call("ai.knowledge-resource.download", undefined, { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }), `resource-${options.sourceId}`, options.output);
 });
 ai.command("security-clue").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").requiredOption("--start-time <datetime>").requiredOption("--end-time <datetime>").addOption(new Option("--query-mode <mode>").choices(["bySecurity", "byIndustry"]).makeOptionMandatory()).option("--gts-code <code>", "GTS code", collectList, []).option("--source <name>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.security-clue.list", { from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, queryMode: options.queryMode, gtsCodeList: maybeArray(options.gtsCode), source: maybeArray(options.source) }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.security-clue.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, queryMode: options.queryMode, gtsCodeList: maybeArray(options.gtsCode), source: maybeArray(options.source) }), parseOutputFormat(options.format), options.output);
 });
 ai.command("one-pager").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.one-pager", { securityCode: options.securityCode }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.one-pager", { securityCode: options.securityCode }), parseOutputFormat(options.format), options.output);
 });
 ai.command("investment-logic").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.investment-logic", { securityCode: options.securityCode }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.investment-logic", { securityCode: options.securityCode }), parseOutputFormat(options.format), options.output);
 });
 ai.command("peer-comparison").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.peer-comparison", { securityCode: options.securityCode }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.peer-comparison", { securityCode: options.securityCode }), parseOutputFormat(options.format), options.output);
 });
 ai.command("earnings-review").requiredOption("--security-code <code>").requiredOption("--period <period>", "Report period (e.g. 2025q3, 2025interim, 2025annual)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -517,36 +292,36 @@ ai.command("earnings-review").requiredOption("--security-code <code>").requiredO
         return;
     }
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    if (!await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, parseFormat(options.format), options.output)) {
+    if (!await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, parseOutputFormat(options.format), options.output)) {
         process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
         process.exitCode = 1;
     }
 });
 ai.command("earnings-review-check").requiredOption("--data-id <id>", "dataId from earnings-review").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await checkAsyncContent(client, "ai.earnings-review.get-content", options.dataId, parseFormat(options.format), options.output);
+    await checkAsyncContent(client, "ai.earnings-review.get-content", options.dataId, parseOutputFormat(options.format), options.output);
 });
 ai.command("theme-tracking").requiredOption("--theme-id <id>", "Theme ID (use lookup theme-id list)").requiredOption("--date <date>", "Date (yyyy-MM-dd)").option("--type <name>", "Report type: morning/night", collectList, []).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
     const typeList = options.type.length ? options.type : undefined;
-    await printData(await client.call("ai.theme-tracking", { themeId: options.themeId, date: options.date, type: typeList }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.theme-tracking", { themeId: options.themeId, date: options.date, type: typeList }), parseOutputFormat(options.format), options.output);
 });
 ai.command("research-outline").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("ai.research-outline", { securityCode: options.securityCode }), parseFormat(options.format), options.output);
+    await printData(await client.call("ai.research-outline", { securityCode: options.securityCode }), parseOutputFormat(options.format), options.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)").option("--end-date <date>", "End date (yyyy-MM-dd)").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(async (options) => {
     const client = await createClient();
     const ALL_CATEGORIES = ["morningBriefing", "noonBriefing", "afternoonFlash", "eveningBriefing"];
     await printData(await client.call("ai.hot-topic", {
-        from: Number(options.from),
-        size: options.size === undefined ? undefined : Number(options.size),
+        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 ? undefined : true,
         withCloseReading: options.withCloseReading === false ? undefined : true,
-    }), parseFormat(options.format), options.output);
+    }), parseOutputFormat(options.format), options.output);
 });
 ai.command("management-discuss-announcement").requiredOption("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)").requiredOption("--security-code <code>", "Security code (e.g. 000001.SZ)").addOption(new Option("--dimension <name>", "Discussion dimension").choices(["businessOperation", "financialPerformance", "developmentAndRisk"]).makeOptionMandatory()).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -554,7 +329,7 @@ ai.command("management-discuss-announcement").requiredOption("--report-date <dat
         reportDate: options.reportDate,
         securityCode: options.securityCode,
         discussionDimension: options.dimension,
-    }), parseFormat(options.format), options.output);
+    }), parseOutputFormat(options.format), options.output);
 });
 ai.command("management-discuss-earnings-call").requiredOption("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)").requiredOption("--security-code <code>", "Security code (e.g. 000001.SZ)").addOption(new Option("--dimension <name>", "Discussion dimension").choices(["businessOperation", "financialPerformance", "developmentAndRisk"]).makeOptionMandatory()).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -562,7 +337,7 @@ ai.command("management-discuss-earnings-call").requiredOption("--report-date <da
         reportDate: options.reportDate,
         securityCode: options.securityCode,
         discussionDimension: options.dimension,
-    }), parseFormat(options.format), options.output);
+    }), parseOutputFormat(options.format), options.output);
 });
 ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint text (max 1000 chars)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -579,19 +354,19 @@ ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint t
         return;
     }
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    if (!await pollAsyncContent(client, "ai.viewpoint-debate.get-content", dataId, parseFormat(options.format), options.output)) {
+    if (!await pollAsyncContent(client, "ai.viewpoint-debate.get-content", dataId, parseOutputFormat(options.format), options.output)) {
         process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai viewpoint-debate-check --data-id ${dataId}\n`);
         process.exitCode = 1;
     }
 });
 ai.command("viewpoint-debate-check").requiredOption("--data-id <id>", "dataId from viewpoint-debate").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseFormat(options.format), options.output);
+    await checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseOutputFormat(options.format), options.output);
 });
 const vault = new Command("vault").description("Vault APIs");
 vault.command("drive-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--file-type <number>", "File type", collectNumberList, []).option("--space-type <number>", "Space type", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("vault.drive.list", { from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, fileTypeList: options.fileType.length ? options.fileType : undefined, spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), parseFormat(options.format), options.output, { endpointKey: "vault.drive.list", idField: "fileId" });
+    await printData(await client.call("vault.drive.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, fileTypeList: options.fileType.length ? options.fileType : undefined, spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), parseOutputFormat(options.format), options.output, { endpointKey: "vault.drive.list", idField: "fileId" });
 });
 vault.command("drive-download").requiredOption("--file-id <id>").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -601,7 +376,7 @@ vault.command("drive-download").requiredOption("--file-id <id>").option("--outpu
 });
 vault.command("record-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--category <name>", "Recording type: upload/link/mobile/gtNote/pc/share", collectList, []).option("--space-type <number>", "Space type: 1=my records / 2=tenant records", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("vault.record.list", { from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, categoryList: maybeArray(options.category), spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), parseFormat(options.format), options.output, { endpointKey: "vault.record.list", idField: "recordId" });
+    await printData(await client.call("vault.record.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, categoryList: maybeArray(options.category), spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), parseOutputFormat(options.format), options.output, { endpointKey: "vault.record.list", idField: "recordId" });
 });
 vault.command("record-download").requiredOption("--record-id <id>").requiredOption("--content-type <type>", "Content type: original/asr/summary").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -611,7 +386,7 @@ vault.command("record-download").requiredOption("--record-id <id>").requiredOpti
 });
 vault.command("my-conference-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--research-area <id>", "Research area ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Conference category: earningsCall/strategyMeeting/fundRoadshow/shareholdersMeeting/maMeeting/specialMeeting/companyAnalysis/industryAnalysis/other", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await printData(await client.call("vault.my-conference.list", { from: Number(options.from), size: options.size === undefined ? undefined : Number(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution), categoryList: maybeArray(options.category) }), parseFormat(options.format), options.output, { endpointKey: "vault.my-conference.list", idField: "conferenceId" });
+    await printData(await client.call("vault.my-conference.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution), categoryList: maybeArray(options.category) }), parseOutputFormat(options.format), options.output, { endpointKey: "vault.my-conference.list", idField: "conferenceId" });
 });
 vault.command("my-conference-download").requiredOption("--conference-id <id>").requiredOption("--content-type <type>", "Content type: asr/summary").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -637,7 +412,7 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
         await saveDownloadResult(data, "download.bin", options.output);
         return;
     }
-    await printData(data, parseFormat(options.format), options.output);
+    await printData(data, parseOutputFormat(options.format), options.output);
 }));
 async function main() {
     try {

package/dist/src/core/args.js

@@ -1,3 +1,4 @@
+import { ValidationError } from "./errors.js";
 export function splitCsv(value) {
     return value
         .split(",")
@@ -7,10 +8,35 @@ export function splitCsv(value) {
 export function collectList(value, previous = []) {
     return [...previous, ...splitCsv(value)];
 }
+export function parseNumberOption(value, optionName, config = {}) {
+    if (value === undefined || String(value).trim() === "") {
+        throw new ValidationError(`Invalid ${optionName}: expected a number`);
+    }
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new ValidationError(`Invalid ${optionName}: expected a finite number`);
+    }
+    if (config.integer && !Number.isInteger(parsed)) {
+        throw new ValidationError(`Invalid ${optionName}: expected an integer`);
+    }
+    if (config.min !== undefined && parsed < config.min) {
+        throw new ValidationError(`Invalid ${optionName}: expected a number >= ${config.min}`);
+    }
+    return parsed;
+}
+export function parseOptionalNumberOption(value, optionName, config = {}) {
+    return value === undefined ? undefined : parseNumberOption(value, optionName, config);
+}
+export function parseFrom(value) {
+    return parseNumberOption(value ?? "0", "--from", { integer: true, min: 0 });
+}
+export function parseSize(value) {
+    return parseOptionalNumberOption(value, "--size", { integer: true, min: 1 });
+}
 export function collectNumberList(value, previous = []) {
     return [
         ...previous,
-        ...splitCsv(value).map((item) => Number(item)).filter((item) => !Number.isNaN(item)),
+        ...splitCsv(value).map((item) => parseNumberOption(item, "number list item")),
     ];
 }
 export function collectKeyValue(value, previous = {}) {
@@ -44,3 +70,12 @@ export function toTimestamp13(value) {
         return undefined;
     return ms;
 }
+export function parseTimestamp13(value, optionName) {
+    if (value === undefined)
+        return undefined;
+    const parsed = toTimestamp13(value);
+    if (parsed === undefined) {
+        throw new ValidationError(`Invalid ${optionName}: expected a Unix timestamp or date string`);
+    }
+    return parsed;
+}

package/dist/src/core/asyncContent.js

@@ -0,0 +1,50 @@
+import { ApiError } from "./errors.js";
+import { printData } from "./printer.js";
+export const POLL_MAX_ATTEMPTS = 12;
+export const POLL_DELAY_MS = 15_000;
+function isAsyncPending(error) {
+    return error instanceof ApiError && error.code === "410110";
+}
+export async function pollAsyncContent(client, getContentEndpoint, dataId, format, output) {
+    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            const result = await client.call(getContentEndpoint, { dataId });
+            if (result?.content != null) {
+                await printData(result, format, output);
+                return true;
+            }
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === "410111") {
+                process.stderr.write("Content generation failed (terminal). Do not retry.\n");
+                return false;
+            }
+            if (!isAsyncPending(error))
+                throw error;
+        }
+        if (attempt < POLL_MAX_ATTEMPTS) {
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in 15s...\n`);
+            await new Promise(resolve => setTimeout(resolve, POLL_DELAY_MS));
+        }
+    }
+    return false;
+}
+export async function checkAsyncContent(client, getContentEndpoint, dataId, format, output) {
+    try {
+        const result = await client.call(getContentEndpoint, { dataId });
+        if (result?.content != null) {
+            await printData(result, format, output);
+            return;
+        }
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.code === "410111") {
+            process.stderr.write("Content generation failed (terminal). Do not retry.\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (!isAsyncPending(error))
+            throw error;
+    }
+    process.stdout.write(`${JSON.stringify({ dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
+}

package/dist/src/core/client.js

@@ -37,8 +37,18 @@ export class GangtiseClient {
         });
         return accessToken;
     }
+    isEnvelope(parsed) {
+        return Boolean(parsed && typeof parsed === 'object' && 'code' in parsed);
+    }
+    throwHttpError(parsed, statusCode) {
+        if (this.isEnvelope(parsed)) {
+            const code = parsed.code === undefined ? undefined : String(parsed.code);
+            throw new ApiError(parsed.msg || `API request failed (HTTP ${statusCode})`, code, statusCode, parsed);
+        }
+        throw new ApiError(`API request failed (HTTP ${statusCode})`, undefined, statusCode, parsed);
+    }
     unwrapEnvelope(parsed, statusCode) {
-        if (!parsed || typeof parsed !== 'object' || !('code' in parsed)) {
+        if (!this.isEnvelope(parsed)) {
             return parsed;
         }
         const code = parsed.code === undefined ? undefined : String(parsed.code);
@@ -167,15 +177,18 @@ export class GangtiseClient {
             bodyTimeout: this.config.timeoutMs,
         });
         const text = await response.body.text();
-        if (response.statusCode >= 500) {
-            throw new ApiError(`Server error (HTTP ${response.statusCode})`, undefined, response.statusCode, text.slice(0, 500));
-        }
         let parsed;
         try {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new ApiError('Failed to parse API response', undefined, response.statusCode, text.slice(0, 500));
+            const message = response.statusCode >= 400
+                ? `API request failed (HTTP ${response.statusCode})`
+                : 'Failed to parse API response';
+            throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500));
+        }
+        if (response.statusCode >= 400) {
+            this.throwHttpError(parsed, response.statusCode);
         }
         return this.unwrapEnvelope(parsed, response.statusCode);
     }
@@ -206,6 +219,9 @@ export class GangtiseClient {
                 }
                 return { text, contentType };
             }
+            if (response.statusCode >= 400) {
+                this.throwHttpError(parsed, response.statusCode);
+            }
             const data = this.unwrapEnvelope(parsed, response.statusCode);
             if (data && typeof data === 'object' && 'url' in data && typeof data.url === 'string') {
                 return { url: String(data.url), contentType };

package/dist/src/core/config.js

@@ -8,7 +8,7 @@ export function loadConfig() {
     const timeoutMs = timeoutValue ? Number(timeoutValue) : DEFAULT_TIMEOUT_MS;
     return {
         baseUrl: process.env.GANGTISE_BASE_URL ?? DEFAULT_BASE_URL,
-        timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : DEFAULT_TIMEOUT_MS,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS,
         accessKey: process.env.GANGTISE_ACCESS_KEY,
         secretKey: process.env.GANGTISE_SECRET_KEY,
         token: process.env.GANGTISE_TOKEN,

package/dist/src/core/download.js

@@ -0,0 +1,96 @@
+import { extname } from "node:path";
+import { DownloadError } from "./errors.js";
+import { saveOutputIfNeeded } from "./output.js";
+import { lookupTitleCache, readTitleCache, TITLE_LOOKUP_SIZE } from "./titleCache.js";
+const MIME_EXT = {
+    "application/pdf": ".pdf",
+    "application/msword": ".doc",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+    "application/vnd.ms-excel": ".xls",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.ms-powerpoint": ".ppt",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "application/zip": ".zip",
+    "application/x-rar-compressed": ".rar",
+    "application/gzip": ".gz",
+    "application/x-7z-compressed": ".7z",
+    "application/json": ".json",
+    "application/xml": ".xml",
+    "text/plain": ".txt",
+    "text/html": ".html",
+    "text/csv": ".csv",
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+    "audio/mpeg": ".mp3",
+    "video/mp4": ".mp4",
+    "application/octet-stream": ".bin",
+};
+export function extFromContentType(contentType) {
+    if (!contentType)
+        return "";
+    const mime = contentType.split(";")[0].trim().toLowerCase();
+    return MIME_EXT[mime] ?? "";
+}
+export async function resolveTitle(client, result, listEndpoint, idField, idValue, titleField = "title") {
+    const file = result;
+    const serverExt = file.filename ? extname(file.filename) : extFromContentType(file.contentType);
+    function buildFilename(rawTitle) {
+        let title = rawTitle.replace(/[/\\:*?"<>|]/g, "_").trim();
+        if (serverExt && !title.toLowerCase().endsWith(serverExt.toLowerCase())) {
+            title += serverExt;
+        }
+        return title;
+    }
+    try {
+        const cacheData = await readTitleCache();
+        const cached = lookupTitleCache(cacheData, listEndpoint, idValue);
+        if (cached)
+            return buildFilename(cached);
+    }
+    catch {
+        // Ignore corrupt cache data and fall back to the list endpoint.
+    }
+    try {
+        const resp = await client.call(listEndpoint, { from: 0, size: TITLE_LOOKUP_SIZE });
+        const items = Array.isArray(resp) ? resp : (resp.list ?? []);
+        const match = items.find(item => String(item[idField]) === String(idValue));
+        const rawTitle = match?.[titleField];
+        if (typeof rawTitle === "string" && rawTitle)
+            return buildFilename(rawTitle);
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export async function saveDownloadResult(result, fallbackName, output) {
+    if (!(result && typeof result === "object")) {
+        throw new DownloadError("Unexpected download response");
+    }
+    const file = result;
+    if (file.data instanceof Uint8Array) {
+        const outputPath = output ?? file.filename ?? (fallbackName + extFromContentType(file.contentType));
+        await saveOutputIfNeeded(file.data, outputPath);
+        process.stdout.write(`${outputPath}\n`);
+        return;
+    }
+    if (typeof file.text === "string") {
+        const outputPath = output ?? `${fallbackName}.txt`;
+        await saveOutputIfNeeded(file.text, outputPath);
+        process.stdout.write(`${outputPath}\n`);
+        return;
+    }
+    if (typeof file.url === "string") {
+        if (output) {
+            await saveOutputIfNeeded(file.url, output);
+            process.stdout.write(`${output}\n`);
+            return;
+        }
+        process.stdout.write(`${file.url}\n`);
+        return;
+    }
+    throw new DownloadError("Unexpected download response");
+}

package/dist/src/core/output.js

@@ -1,4 +1,13 @@
 import fs from "node:fs/promises";
+import { ConfigError } from "./errors.js";
+const OUTPUT_FORMATS = ["table", "json", "jsonl", "csv", "markdown"];
+export function parseOutputFormat(value) {
+    const format = value ?? "table";
+    if (OUTPUT_FORMATS.includes(format)) {
+        return format;
+    }
+    throw new ConfigError(`Unsupported format: ${format}`);
+}
 function formatScalar(value) {
     if (value === null || value === undefined) {
         return "";

package/dist/src/core/printer.js

@@ -0,0 +1,31 @@
+import { normalizeRows } from "./normalize.js";
+import { renderOutput, saveOutputIfNeeded } from "./output.js";
+import { extractTitles, writeTitleCache } from "./titleCache.js";
+export async function printData(data, format, output, cache) {
+    const normalized = normalizeRows(data);
+    const items = Array.isArray(normalized)
+        ? normalized
+        : (normalized && typeof normalized === "object" && Array.isArray(normalized.list))
+            ? normalized.list
+            : null;
+    if (cache && items) {
+        const titles = extractTitles(items, cache);
+        if (Object.keys(titles).length > 0) {
+            writeTitleCache(cache.endpointKey, titles).catch(() => { });
+        }
+    }
+    if (normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
+        const meta = normalized;
+        if (typeof meta.total === "number" && format !== "json") {
+            const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
+            process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
+        }
+    }
+    const content = renderOutput(normalized, format);
+    if (output) {
+        await saveOutputIfNeeded(content, output);
+        process.stdout.write(`${output}\n`);
+        return;
+    }
+    process.stdout.write(`${content}\n`);
+}

package/dist/src/core/titleCache.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_TITLE_CACHE_PATH = path.join(os.homedir(), ".config", "gangtise", "title-cache.json");
+export const TITLE_LOOKUP_SIZE = 200;
+const TITLE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+export async function readTitleCache(filePath = DEFAULT_TITLE_CACHE_PATH) {
+    try {
+        const content = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return {};
+    }
+    return {};
+}
+export async function writeTitleCache(endpoint, titles, filePath = DEFAULT_TITLE_CACHE_PATH) {
+    const data = await readTitleCache(filePath);
+    data[endpoint] = { titles, ts: Date.now() };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(data), { encoding: "utf8", mode: 0o600 });
+}
+export function lookupTitleCache(data, endpoint, id) {
+    const entry = data[endpoint];
+    if (!entry || Date.now() - entry.ts > TITLE_CACHE_TTL_MS)
+        return undefined;
+    return entry.titles[id];
+}
+export function extractTitles(items, cache) {
+    const titleField = cache.titleField ?? "title";
+    const titles = {};
+    for (const row of items) {
+        if (!row || typeof row !== "object")
+            continue;
+        const record = row;
+        const id = record[cache.idField];
+        const title = record[titleField];
+        if (id != null && typeof title === "string" && title) {
+            titles[String(id)] = title;
+        }
+    }
+    return titles;
+}

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.10.9";
+export const CLI_VERSION = "0.10.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.10.9",
+  "version": "0.10.10",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {