gangtise-openapi-cli 0.51.0 → 0.52.0

package/dist/src/commands/vault.js

@@ -3,13 +3,13 @@ import { collectList, collectNames, parseFrom, parseSize } from "../core/args.js
 import { uploadDriveFile } from "../core/driveUpload.js";
 import { ValidationError } from "../core/errors.js";
 import { flagFailedItems } from "../core/normalize.js";
-import { emit, addDownloadCommand, assertConfirmed, field, value, required, requiredList, list, numberList, format, output, from, size, startTime, endTime, query, RESEARCH_AREA_CITIC_OR_DIRECTION } from "./shared.js";
+import { emit, addDownloadCommand, assertConfirmed, field, value, required, requiredList, list, numberList, format, output, from, size, startTime, endTime, query, RESEARCH_AREA_CITIC_OR_DIRECTION, OUTPUT_HELP } from "./shared.js";
 export const vault = new Command("vault").description("Vault APIs");
 query(vault, "drive-list", {
     endpoint: "vault.drive.list",
     cache: { endpointKey: "vault.drive.list", idField: "fileId" },
     fields: [
-        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        from(), size(), startTime(), endTime(), value("--keyword <text>", "Keyword", "keyword"),
         numberList("--file-type <number>", "File type", "fileTypeList"),
         numberList("--space-type <number>", "Space type", "spaceTypeList"),
         format(), output(),
@@ -32,7 +32,7 @@ vault.command("drive-upload").description("Upload a file to the AI drive (free;
     .addOption(driveSpaceOption("Target space: 1=my drive 2=tenant drive (shared with your whole tenant)"))
     .option("--folder-id <id>", "Target folder ID in that space; omit (or 'root') for the space's root")
     .option("--title <name>", "Name in the drive, max 200 characters; defaults to the local file name")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => uploadDriveFile(client, options.file, { spaceType: Number(options.spaceType), folderId: options.folderId, title: options.title })));
 query(vault, "drive-create-folder", {
     description: "Create a drive folder (free). Same-name folders are allowed, so re-running creates a second one",
@@ -57,7 +57,7 @@ query(vault, "drive-rename", {
 vault.command("drive-move-file").description("Move drive files into a folder of the SAME space (free)")
     .requiredOption("--file-id <id>", "File ID (repeat or comma-separate)", collectList)
     .requiredOption("--target-folder-id <id>", "Destination folder ID, or 'root'. Files of the other space land in failList (空间不一致)")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, async (client) => {
     const data = await client.call("vault.drive.move-file", { fileIdList: options.fileId, targetFolderId: options.targetFolderId });
     flagFailedItems(data, "vault drive-move-file");
@@ -77,7 +77,7 @@ vault.command("drive-copy").description("Copy files, or one folder with everythi
     .option("--target-folder-id <id>", "Destination folder ID in the other space, or 'root' for that space's root")
     .option("--folder-id <id>", "Source folder ID; use with --target-parent-id")
     .option("--target-parent-id <id>", "Destination parent folder ID in the other space, or 'root' for that space's root")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     const byFile = options.fileId.length > 0 || options.targetFolderId !== undefined;
     const byFolder = options.folderId !== undefined || options.targetParentId !== undefined;
@@ -101,7 +101,7 @@ vault.command("drive-copy").description("Copy files, or one folder with everythi
 vault.command("drive-delete-file").description("Delete drive files — irreversible (free)")
     .requiredOption("--file-id <id>", "File ID to delete (repeat or comma-separate)", collectList)
     .option("--yes", "Required: confirm the deletion")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action(async (options) => {
     assertConfirmed("vault.drive.delete-file", Boolean(options.yes), options.fileId.join("、"));
     await emit(options, async (client) => {
@@ -113,7 +113,7 @@ vault.command("drive-delete-file").description("Delete drive files — irreversi
 vault.command("drive-delete-folder").description("Delete a drive folder AND every subfolder and file inside it — irreversible (free)")
     .requiredOption("--folder-id <id>", "Folder ID to delete")
     .option("--yes", "Required: confirm the deletion")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action(async (options) => {
     assertConfirmed("vault.drive.delete-folder", Boolean(options.yes), options.folderId);
     await emit(options, (client) => client.call("vault.drive.delete-folder", { folderId: options.folderId }));
@@ -122,7 +122,7 @@ query(vault, "record-list", {
     endpoint: "vault.record.list",
     cache: { endpointKey: "vault.record.list", idField: "recordId" },
     fields: [
-        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        from(), size(), startTime(), endTime(), value("--keyword <text>", "Keyword", "keyword"),
         list("--category <name>", "Recording type: upload/link/mobile/gtNote/pc/share", "categoryList"),
         numberList("--space-type <number>", "Space type: 1=my records / 2=tenant records", "spaceTypeList"),
         format(), output(),
@@ -133,7 +133,7 @@ query(vault, "my-conference-list", {
     endpoint: "vault.my-conference.list",
     cache: { endpointKey: "vault.my-conference.list", idField: "conferenceId" },
     fields: [
-        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        from(), size(), startTime(), endTime(), value("--keyword <text>", "Keyword", "keyword"),
         list("--research-area <id>", RESEARCH_AREA_CITIC_OR_DIRECTION, "researchAreaList"),
         list("--security <code>", "Security code", "securityList"),
         list("--institution <id>", "Institution ID", "institutionList"),
@@ -146,7 +146,7 @@ addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "
 query(vault, "wechat-message-list", {
     endpoint: "vault.wechat-message.list",
     fields: [
-        from(), size(), startTime(), endTime(), value("--keyword <text>", undefined, "keyword"),
+        from(), size(), startTime(), endTime(), value("--keyword <text>", "Keyword", "keyword"),
         list("--security <code>", "Security code (e.g. 000001.SZ)", "securityList"),
         list("--wechat-group-id <id>", "WeChat group ID", "wechatGroupIdList"),
         list("--industry <id>", "Industry ID -- citicIndustry codes (1008001xx) only; swIndustry codes and unknown values are rejected with 100005", "industryIdList"),
@@ -193,7 +193,7 @@ vault.command("stock-pool-add-stock")
     .requiredOption("--pool-id <id>", "Target pool ID from 'stock-pool-list'")
     .requiredOption("--security <code>", "Security code, e.g. 600519.SH (repeat or comma-separate)", collectList)
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, async (client) => {
     const data = await client.call("vault.stock-pool.add-stock", { poolId: options.poolId, securityCodeList: options.security });
     flagFailedItems(data, "vault stock-pool-add-stock");
@@ -203,7 +203,7 @@ vault.command("stock-pool-remove-stock")
     .requiredOption("--pool-id <id>", "Target pool ID from 'stock-pool-list'")
     .requiredOption("--security <code>", "Security code, e.g. 600519.SH (repeat or comma-separate)", collectList)
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, async (client) => {
     const data = await client.call("vault.stock-pool.remove-stock", { poolId: options.poolId, securityCodeList: options.security });
     flagFailedItems(data, "vault stock-pool-remove-stock");
@@ -213,7 +213,7 @@ vault.command("stock-pool-delete")
     .requiredOption("--pool-id <id>", "Pool ID to delete; repeat or comma-separate for multiple", collectList)
     .option("--yes", "Required: confirm the deletion")
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action(async (options) => {
     assertConfirmed("vault.stock-pool.delete", Boolean(options.yes), options.poolId.join("、"));
     await emit(options, async (client) => {
@@ -227,7 +227,7 @@ vault.command("stock-note-list").description("List your stock notes: all, by sec
     .option("--note-id <id>", "Note ID (repeat or comma-separate); not together with --security", collectList)
     .option("--from <number>", "Starting offset", "0")
     .option("--size <number>", "Total rows to return; omit to fetch all")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     if (options.security?.length && options.noteId?.length)
         throw new ValidationError("pass --security or --note-id, not both");
@@ -256,7 +256,7 @@ query(vault, "stock-note-update", {
 vault.command("stock-note-delete").description("Delete stock notes — irreversible (free)")
     .requiredOption("--note-id <id>", "Note ID to delete; repeat or comma-separate, max 100", collectList)
     .option("--yes", "Required: confirm the deletion")
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action(async (options) => {
     assertConfirmed("vault.stock-note.delete", Boolean(options.yes), options.noteId.join("、"));
     await emit(options, async (client) => {

package/dist/src/core/client.js

@@ -9,13 +9,16 @@ import { ApiError, attachEnvelopeTraceId, markStructural, ValidationError } from
 import { COSTLY_FETCH_CREDITS, ENDPOINTS, resolveTimeoutMs } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
 import { stagingPath } from "./output.js";
-import { decodeResponseBody, getDispatcher, isVerbose, JSON_TOTAL_FACTOR, logTiming, markAuthReplay, PAGE_CONCURRENCY, parseRetryAfterMs, quoteBigIntFields, runInOrder, TRANSFER_TOTAL_FACTOR, withRetry } from "./transport.js";
+import { decodeResponseBody, getDispatcher, isVerbose, JSON_TOTAL_FACTOR, logTiming, markAuthReplay, noteRequestSent, PAGE_CONCURRENCY, parseRetryAfterMs, quoteBigIntFields, runInOrder, TRANSFER_TOTAL_FACTOR, withRetry } from "./transport.js";
 import { attachRowSink } from "./rowSink.js";
 import { markIncomplete } from "./exitStatus.js";
+import { isDryRun, stopForDryRun } from "./dryRun.js";
 const AUTH_RETRY_CODES = new Set(["8000014", "8000015", "0000001008", "999002"]);
 function hasExpectedShape(expects, payload) {
     if (expects === "array")
         return Array.isArray(payload);
+    if (expects === "object")
+        return Boolean(payload && typeof payload === "object" && !Array.isArray(payload));
     return Boolean(payload && typeof payload === "object" && Array.isArray(payload.list));
 }
 const PROBE_ABOVE_CREDITS = 50;
@@ -79,7 +82,7 @@ export class GangtiseClient {
         return this.refreshPromise;
     }
     async doTokenRefresh() {
-        const credentials = requireAccessCredentials(this.config.accessKey, this.config.secretKey);
+        const credentials = isDryRun() ? { accessKey: "", secretKey: "" } : requireAccessCredentials(this.config.accessKey, this.config.secretKey);
         const envelope = await this.requestJson(ENDPOINTS["auth.login"], {
             accessKey: credentials.accessKey,
             secretKey: credentials.secretKey,
@@ -472,6 +475,8 @@ export class GangtiseClient {
         if (endpoint.path.startsWith('/guide/')) {
             return this.readLocalLookup(endpoint);
         }
+        if (isDryRun())
+            return stopForDryRun({ endpoint, url: this.buildUrl(endpoint.path), body });
         const dispatcher = getDispatcher();
         const url = this.buildUrl(endpoint.path);
         const authState = {};
@@ -488,6 +493,7 @@ export class GangtiseClient {
                 usedAuthorization = await this.getAuthorizationHeader();
                 headers.Authorization = usedAuthorization;
             }
+            noteRequestSent();
             const startedAt = Date.now();
             const response = await request(url, {
                 method: endpoint.method,
@@ -562,6 +568,10 @@ export class GangtiseClient {
         if (!endpoint || endpoint.kind !== 'upload') {
             throw new ApiError(`Not an upload endpoint: ${endpointKey}`);
         }
+        if (isDryRun()) {
+            const sent = Object.fromEntries(Object.entries(fields ?? {}).filter(([, value]) => value !== undefined));
+            return stopForDryRun({ endpoint, url: this.buildUrl(endpoint.path), body: sent, file: { name: file.filename, bytes: file.data.byteLength } });
+        }
         const form = new FormData();
         form.append('file', new Blob([file.data], { type: file.contentType ?? 'application/octet-stream' }), file.filename);
         for (const [name, value] of Object.entries(fields ?? {})) {
@@ -580,6 +590,7 @@ export class GangtiseClient {
         const timeoutMs = resolveTimeoutMs(this.config.timeoutMs, endpoint);
         return withRetry(async () => {
             const authorization = await this.getAuthorizationHeader();
+            noteRequestSent();
             const startedAt = Date.now();
             const signal = AbortSignal.timeout(timeoutMs * TRANSFER_TOTAL_FACTOR);
             let currentUrl = url;
@@ -731,6 +742,11 @@ export class GangtiseClient {
         if (endpoint.kind === 'upload') {
             throw new ValidationError(`${endpointKey} takes a file upload — use its dedicated command ('gangtise tool file-parse --file <path>' / 'gangtise vault drive-upload --file <path>'); 'raw call' cannot send files`);
         }
+        if (isDryRun() && !endpoint.path.startsWith('/guide/')) {
+            const url = this.buildUrl(endpoint.path);
+            Object.entries(query ?? {}).forEach(([key, value]) => url.searchParams.set(key, String(value)));
+            return stopForDryRun({ endpoint, url, body });
+        }
         if (endpoint.kind === 'download') {
             return this.download(endpoint, query ?? {}, options, body);
         }

package/dist/src/core/download.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
-import { dirname, extname } from "node:path";
-import { DownloadError } from "./errors.js";
+import { dirname, extname, join, sep } from "node:path";
+import { DownloadError, ValidationError } from "./errors.js";
 import { saveOutputIfNeeded, stagingPath, trackClaim } from "./output.js";
+import { assertNotStatePath } from "./statePaths.js";
 import { extractTitles, lookupTitleCache, readTitleCache, TITLE_LOOKUP_SIZE, writeTitleCache } from "./titleCache.js";
 function sanitizeFilename(name) {
     return name.replace(/[/\\:*?"<>|\u0000-\u001f]/g, "_");
@@ -147,7 +148,7 @@ async function downloadUrlTo(url, outputPath) {
     const { pipeline } = await import("node:stream/promises");
     const { dirname } = await import("node:path");
     const { request } = await import("undici");
-    const { getDispatcher, logTiming, TRANSFER_TOTAL_FACTOR, withRetry } = await import("./transport.js");
+    const { getDispatcher, logTiming, noteRequestSent, TRANSFER_TOTAL_FACTOR, withRetry } = await import("./transport.js");
     const { loadConfig } = await import("./config.js");
     const timeoutMs = loadConfig().timeoutMs;
     await fs.mkdir(dirname(outputPath), { recursive: true });
@@ -162,6 +163,7 @@ async function downloadUrlTo(url, outputPath) {
     };
     const partPath = stagingPath(outputPath);
     await withRetry(async () => {
+        noteRequestSent();
         const startedAt = Date.now();
         const requestOptions = {
             method: "GET",
@@ -206,6 +208,13 @@ async function downloadUrlTo(url, outputPath) {
         throw error;
     }
 }
+export async function assertOutputFilePath(output) {
+    const endsAsDirectory = output.endsWith("/") || output.endsWith(sep);
+    if (endsAsDirectory || (await fs.stat(output).catch(() => undefined))?.isDirectory()) {
+        throw new ValidationError(`--output ${output} is a directory: pass a file path (e.g. ${join(output, "<name>")}), or omit --output for an automatic name in the current directory`);
+    }
+    await assertNotStatePath(output, "--output");
+}
 export function autoDownloadName(file, fallbackName) {
     return truncateFilename(file.filename ? sanitizeFilename(file.filename) : sanitizeFilename(fallbackName) + extFromContentType(file.contentType));
 }

package/dist/src/core/driveUpload.js

@@ -1,12 +1,15 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ValidationError } from "./errors.js";
+import { assertNotStatePath } from "./statePaths.js";
 export const DRIVE_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
 export const DRIVE_NAME_MAX = 200;
 export async function uploadDriveFile(client, filePath, options) {
-    const resolved = path.resolve(filePath);
+    const shownAs = path.resolve(filePath);
+    let resolved;
     let stat;
     try {
+        resolved = await fs.realpath(filePath);
         stat = await fs.stat(resolved);
     }
     catch {
@@ -14,12 +17,13 @@ export async function uploadDriveFile(client, filePath, options) {
     }
     if (!stat.isFile())
         throw new ValidationError(`Not a file: ${filePath}`);
+    await assertNotStatePath(resolved, "--file");
     if (stat.size === 0)
         throw new ValidationError(`File is empty: ${filePath}`);
     if (stat.size > DRIVE_UPLOAD_MAX_BYTES) {
         throw new ValidationError(`File is ${(stat.size / 1024 / 1024).toFixed(1)}MB — the drive accepts at most 100MB per file`);
     }
-    const filename = path.basename(resolved);
+    const filename = path.basename(shownAs);
     const name = options.title ?? filename;
     if (name.length > DRIVE_NAME_MAX) {
         throw new ValidationError(`File name is ${name.length} characters — the drive accepts at most ${DRIVE_NAME_MAX} (an emoji counts as 2); pass a shorter --title`);

package/dist/src/core/dryRun.js

@@ -0,0 +1,68 @@
+import { removeStagingFiles } from "./output.js";
+let dryRun = false;
+let shown = false;
+export function setDryRun(enabled) {
+    dryRun = enabled;
+}
+export function isDryRun() {
+    return dryRun;
+}
+const toCents = (credits) => Math.round(credits * 100) / 100;
+function maxCredits(endpoint, body) {
+    const billing = endpoint.billing;
+    if (!billing)
+        return undefined;
+    const fields = body && typeof body === "object" ? body : {};
+    if (billing.per === "call" || billing.per === "document")
+        return billing.price;
+    if (endpoint.estimateBilledUnits) {
+        try {
+            return toCents(endpoint.estimateBilledUnits(fields) * billing.price);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (billing.per === "row" && endpoint.pagination?.enabled)
+        return typeof fields.size === "number" ? toCents(fields.size * billing.price) : undefined;
+    if (!billing.maxUnits)
+        return undefined;
+    const asked = billing.unitsFrom?.reduce((n, key) => n + (Array.isArray(fields[key]) ? fields[key].length : 0), 0);
+    return toCents(Math.min(billing.maxUnits, asked || billing.maxUnits) * billing.price);
+}
+export function describeRequest(plan) {
+    const { endpoint } = plan;
+    return {
+        dryRun: true,
+        endpoint: endpoint.key,
+        method: endpoint.method,
+        url: plan.url.toString(),
+        body: endpoint.key === "auth.login" ? "(credentials not shown)" : plan.body ?? null,
+        file: plan.file,
+        pagination: endpoint.pagination?.enabled
+            ? `The CLI pages this list itself, at most ${endpoint.pagination.maxPageSize} rows a request, until size rows or the total; without size it fetches every row`
+            : undefined,
+        billing: endpoint.billing
+            ? { per: endpoint.billing.per, price: endpoint.billing.price, ...(Number.isFinite(endpoint.billing.maxUnits) ? { maxUnits: endpoint.billing.maxUnits } : {}) }
+            : null,
+        maxCredits: maxCredits(endpoint, plan.body),
+        needsYes: endpoint.destructive ? true : undefined,
+        note: "Nothing was sent. Only the command's first request is shown; any later request depends on its answer.",
+    };
+}
+export function describeNoRequest(output) {
+    return {
+        dryRun: true,
+        endpoint: null,
+        output: output ?? null,
+        note: "This command sends no request. Under --dry-run it prints only this and writes no file.",
+    };
+}
+export function stopForDryRun(plan) {
+    if (!shown) {
+        shown = true;
+        removeStagingFiles();
+        process.stdout.write(`${JSON.stringify(describeRequest(plan), null, 2)}\n`, () => process.exit(0));
+    }
+    return new Promise(() => { });
+}

package/dist/src/core/endpoints.js

@@ -71,7 +71,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/chief-opinion/getDetail",
         kind: "json",
         description: "Get domestic chief opinion bodies by ID (max 20 IDs per call)",
-        billing: { per: "row", price: 30, maxUnits: 20 },
+        billing: { per: "row", price: 30, maxUnits: 20, unitsFrom: ["chiefOpinionIdList"] },
         retry: "no-replay",
         expects: "array",
     },
@@ -267,7 +267,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/foreign-opinion/getDetail",
         kind: "json",
         description: "Get foreign opinion bodies by ID (max 20 IDs per call)",
-        billing: { per: "row", price: 30, maxUnits: 20 },
+        billing: { per: "row", price: 30, maxUnits: 20, unitsFrom: ["foreignOpinionIdList"] },
         retry: "no-replay",
         expects: "array",
     },
@@ -288,6 +288,25 @@ const ENDPOINT_DEFS = {
         description: "Download foreign independent opinion file",
         billing: { per: "document", price: 30 },
     },
+    "insight.overseas-opinion.list": {
+        method: "POST",
+        path: "/application/open-insight/overseasOpinion/getList",
+        kind: "json",
+        description: "List overseas opinions (brief only; body via detail)",
+        billing: { per: "row", price: 0.1 },
+        pagination: { enabled: true, maxPageSize: 50, maxWindow: 10000 },
+        rowId: "overseasOpinionId",
+        expects: "list",
+    },
+    "insight.overseas-opinion.detail": {
+        method: "POST",
+        path: "/application/open-insight/overseasOpinion/getDetail",
+        kind: "json",
+        description: "Get overseas opinion bodies by ID (max 20 IDs per call)",
+        billing: { per: "row", price: 10, maxUnits: 20, unitsFrom: ["overseasOpinionIdList"] },
+        retry: "no-replay",
+        expects: "array",
+    },
     "insight.official-account.list": {
         method: "POST",
         path: "/application/open-insight/officialAccount/getList",
@@ -317,6 +336,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/report-image/getList",
         kind: "json",
         description: "Search research report images by keyword (returns chunkId + metadata)",
+        expects: "array",
     },
     "insight.highlight.list": {
         method: "POST",
@@ -341,54 +361,72 @@ const ENDPOINT_DEFS = {
         path: "/application/open-reference/securities/search",
         kind: "json",
         description: "Search GTS codes (securities)",
+        expects: "list",
     },
     "reference.chiefs-search": {
         method: "POST",
         path: "/application/open-reference/chiefs/search",
         kind: "json",
         description: "Search chief analyst IDs by name / institution / team",
+        expects: "list",
     },
     "reference.institution-search": {
         method: "POST",
         path: "/application/open-reference/institutions/search",
         kind: "json",
         description: "Search institution IDs by keyword (domestic broker / foreign / lead / opinion institution)",
+        expects: "list",
     },
     "reference.official-account-search": {
         method: "POST",
         path: "/application/open-reference/officialAccount/search",
         kind: "json",
         description: "Search official account (WeChat public account) IDs by name / institution / category",
+        expects: "list",
+    },
+    "reference.overseas-account-search": {
+        method: "POST",
+        path: "/application/open-reference/overseasAccount/search",
+        kind: "json",
+        description: "Search overseas opinion account IDs by name fragment",
+        pagination: { enabled: true, maxPageSize: 50 },
+        rowId: "accountId",
+        expects: "list",
     },
     "reference.constant-category": {
         method: "GET",
         path: "/application/open-reference/constants/category",
         kind: "json",
         description: "List constant categories and their API usage scopes",
+        expects: "list",
     },
     "reference.constant-list": {
         method: "POST",
         path: "/application/open-reference/constants/getList",
         kind: "json",
         description: "List all constant values of a category",
+        expects: "object",
     },
     "reference.concept-search": {
         method: "POST",
         path: "/application/open-reference/concepts/search",
         kind: "json",
         description: "Search concept (theme) IDs by keyword",
+        expects: "list",
     },
     "reference.sector-search": {
         method: "POST",
         path: "/application/open-reference/sectors/search",
         kind: "json",
         description: "Search sector IDs by keyword",
+        expects: "list",
     },
     "reference.sector-constituents": {
         method: "POST",
         path: "/application/open-reference/sectors/constituents",
         kind: "json",
         description: "List constituent securities of a sector",
+        expects: "list",
     },
     "reference.index-weight": {
         method: "POST",
@@ -458,72 +496,84 @@ const ENDPOINT_DEFS = {
         path: "/application/open-fundamental/financial-report/income-statement/accumulated",
         kind: "json",
         description: "Query A-share income statement (accumulated)",
+        expects: "list",
     },
     "fundamental.income-statement-quarterly": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/income-statement/quarterly",
         kind: "json",
         description: "Query A-share income statement (quarterly)",
+        expects: "list",
     },
     "fundamental.balance-sheet": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/balance-sheet/accumulated",
         kind: "json",
         description: "Query A-share balance sheet (accumulated)",
+        expects: "list",
     },
     "fundamental.cash-flow": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/cash-flow-statement/accumulated",
         kind: "json",
         description: "Query A-share cash flow statement (accumulated)",
+        expects: "list",
     },
     "fundamental.cash-flow-quarterly": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/cash-flow-statement/quarterly",
         kind: "json",
         description: "Query A-share cash flow statement (quarterly)",
+        expects: "list",
     },
     "fundamental.income-statement-hk": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/income-statement/hk",
         kind: "json",
         description: "Query HK income statement (China GAAP)",
+        expects: "list",
     },
     "fundamental.balance-sheet-hk": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/balance-sheet/hk",
         kind: "json",
         description: "Query HK balance sheet (China GAAP)",
+        expects: "list",
     },
     "fundamental.cash-flow-hk": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/cash-flow-statement/hk",
         kind: "json",
         description: "Query HK cash flow statement (China GAAP)",
+        expects: "list",
     },
     "fundamental.income-statement-us": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/income-statement/us",
         kind: "json",
         description: "Query US income statement",
+        expects: "list",
     },
     "fundamental.balance-sheet-us": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/balance-sheet/us",
         kind: "json",
         description: "Query US balance sheet",
+        expects: "list",
     },
     "fundamental.cash-flow-us": {
         method: "POST",
         path: "/application/open-fundamental/financial-report/cash-flow-statement/us",
         kind: "json",
         description: "Query US cash flow statement",
+        expects: "list",
     },
     "fundamental.main-business": {
         method: "POST",
         path: "/application/open-fundamental/main-business",
         kind: "json",
         description: "Query main business composition",
+        expects: "list",
     },
     "fundamental.valuation-analysis": {
         method: "POST",
@@ -537,6 +587,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-fundamental/capital-structure/top-holders",
         kind: "json",
         description: "Query top holders (top10 / top10 float)",
+        expects: "list",
     },
     "fundamental.earning-forecast": {
         method: "POST",
@@ -628,7 +679,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-fundamental/bond/rating-change",
         kind: "json",
         description: "Query bond rating change history (max 10 bonds per call)",
-        billing: { per: "security", price: 0.4, maxUnits: 10 },
+        billing: { per: "security", price: 0.4, maxUnits: 10, unitsFrom: ["securityList"] },
         retry: "no-replay",
         expects: "list",
     },
@@ -637,7 +688,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-fundamental/bond/issuer-rating-change",
         kind: "json",
         description: "Query issuer rating change history (by bond code or issuer name)",
-        billing: { per: "issuer", price: 0.4, maxUnits: 10 },
+        billing: { per: "issuer", price: 0.4, maxUnits: 10, unitsFrom: ["securityList", "issuerNameList"] },
         retry: "no-replay",
         expects: "list",
     },
@@ -835,7 +886,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/stock-summary/getList",
         kind: "json",
         description: "Stock highlights (refined research summary per security)",
-        billing: { per: "row", price: 1, maxUnits: 6000 },
+        billing: { per: "row", price: 1, maxUnits: 6000, unitsFrom: ["securityList"] },
         retry: "no-replay",
         timeoutMs: 120_000,
     },
@@ -1031,6 +1082,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/drive/getFolderList",
         kind: "json",
         description: "List the direct subfolders and files of a drive folder",
+        expects: "object",
     },
     "vault.drive.create-folder": {
         method: "POST",
@@ -1148,6 +1200,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/stock-pool/getStockList",
         kind: "json",
         description: "List securities in stock pool(s)",
+        expects: "array",
     },
     "vault.stock-pool.create": {
         method: "POST",
@@ -1218,13 +1271,14 @@ const ENDPOINT_DEFS = {
         path: "/application/open-alternative/EDB/search",
         kind: "json",
         description: "Search industry indicator list by keyword",
+        expects: "array",
     },
     "alternative.edb-data": {
         method: "POST",
         path: "/application/open-alternative/EDB/getData",
         kind: "json",
         description: "Get industry indicator time-series data by indicator ID list",
-        billing: { per: "indicator", price: 30, maxUnits: 10 },
+        billing: { per: "indicator", price: 30, maxUnits: 10, unitsFrom: ["indicatorIdList"] },
     },
     "alternative.concept-info": {
         method: "POST",
@@ -1264,6 +1318,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Search data indicators by keyword (returns indicatorCode + params)",
         retry: "no-999999",
+        expects: "array",
     },
     "indicator.cross-section": {
         method: "POST",