@investoday/investoday-api 1.1.0 → 1.8.0

package/README.md

@@ -10,10 +10,10 @@ npm install -g @investoday/investoday-api
 
 ## API key
 
-Set your API key with the `INVESTODAY_API_KEY` environment variable:
+Configure the API key once:
 
 ```bash
-export INVESTODAY_API_KEY="<your_key>"
+investoday-api init
 ```
 
 Get an API key from:
@@ -24,12 +24,13 @@ Get an API key from:
 
 ```bash
 investoday-api --help
+investoday-api init
+investoday-api config status
 investoday-api list
 investoday-api list 沪深京数据
-investoday-api schema stock/basic-info
-investoday-api example stock/basic-info
-investoday-api search-api 违规处罚
-investoday-api search-api 股票 --text
+investoday-api search-api query=违规处罚 tool_ids=list_stock_violation_penalt
+investoday-api search-api query=股票,基本面分析
+investoday-api search-api query=股票 --text
 investoday-api <endpoint> [key=value ...]
 investoday-api <endpoint> --method POST [key=value ...]
 ```
@@ -38,10 +39,10 @@ Examples:
 
 ```bash
 investoday-api list 沪深京数据/股票行情
-investoday-api schema stock/violation-penalties
-investoday-api example stock/violation-penalties
-investoday-api search-api stockCodes
-investoday-api search-api 股票 --text
+investoday-api search-api query=stockCodes
+investoday-api search-api query=股票,基本面分析
+investoday-api search-api tool_ids=list_stock_violation_penalt,list_stock_report_schema
+investoday-api search-api query=股票 --text
 investoday-api stock/basic-info stockCode=600519
 investoday-api search key=贵州茅台 type=11
 investoday-api fund/daily-quotes --method POST fundCode=000001 beginDate=2024-01-01 endDate=2024-12-31
@@ -49,8 +50,9 @@ investoday-api fund/daily-quotes --method POST fundCode=000001 beginDate=2024-01
 
 ## Notes
 
-- Only reads credentials from `INVESTODAY_API_KEY`
+- Uses the local encrypted config created by `investoday-api init`
 - Only calls `https://data-api.investoday.net/data`
-- Bundles endpoint metadata for `list`, `schema`, `example`, and `search-api`
-- `search-api` defaults to JSON output; use `--text` for a human-readable summary
+- Bundles endpoint metadata for `list` and `search-api`
+- `search-api` defaults to JSON output and includes params, response fields, and `exampleCommand`; use `--text` for a human-readable summary
+- `search-api` only accepts structured inputs such as `query=` and `tool_ids=`; `query=` accepts one value and supports comma-separated keywords
 - Prints the API response `data` field as formatted JSON

package/lib/call-api.js

@@ -1,7 +1,18 @@
 const { getMetadata, resolveApi, searchApis } = require("./metadata");
+const {
+  CONFIG_DIR_ENV,
+  getConfigDir,
+  getCredentialsPath,
+  readCredentials,
+  removeCredentials,
+  resolveApiKey,
+  saveCredentials,
+} = require("./config");
+const { version: PACKAGE_VERSION } = require("../package.json");
 
 const BASE_URL = "https://data-api.investoday.net/data";
 const REQUEST_TIMEOUT = 30_000;
+const API_KEY_MANAGE_URL = "https://data-api.investoday.net/user/api-key";
 
 function exitWithError(message) {
   process.stderr.write(`${message}\n`);
@@ -9,40 +20,203 @@ function exitWithError(message) {
 }
 
 function loadApiKey() {
-  const envKey = (process.env.INVESTODAY_API_KEY || "").trim();
-  if (envKey) {
-    return envKey;
+  const { apiKey } = resolveApiKey();
+  if (apiKey) {
+    return apiKey;
   }
 
-  exitWithError("ERROR: Please set the INVESTODAY_API_KEY environment variable first.");
+  exitWithError(
+    "ERROR: 运行环境配置失败，请使用终端Bash运行`investoday-api init`配置。"
+  );
 }
 
 function printHelp() {
   process.stdout.write(
     "investoday-api\n\n" +
     "Usage:\n" +
+    "  investoday-api init\n" +
+    "  investoday-api config status|path|remove\n" +
     "  investoday-api <endpoint> [key=value ...] [--method GET|POST]\n" +
     "  investoday-api list [group-or-subgroup]\n" +
-    "  investoday-api schema <endpoint|tool_id|api_name>\n" +
-    "  investoday-api example <endpoint|tool_id|api_name>\n" +
-    "  investoday-api search-api <query> [--text]\n" +
+    "  investoday-api search-api query=<query> [tool_ids=<tool_id,...>] [--text]\n" +
+    "  investoday-api --version\n" +
     "  investoday-api --help\n\n" +
     "Commands:\n" +
+    "  init     Initialize local InvestToday API key configuration\n" +
+    "  config   Show, locate, or remove the local encrypted credentials\n" +
     "  list     List available groups, subgroups, or endpoints from bundled metadata\n" +
-    "  schema   Show method, parameters, and response fields for one endpoint\n" +
-    "  example  Show a runnable command example for one endpoint\n\n" +
-    "  search-api Search endpoints by name, path, group, request params, or response fields\n\n" +
+    "  search-api Search endpoints and return method, params, response fields, and example command\n\n" +
     "Examples:\n" +
+    "  investoday-api init\n" +
+    "  investoday-api config status\n" +
     "  investoday-api list\n" +
     "  investoday-api list 沪深京数据\n" +
-    "  investoday-api schema stock/basic-info\n" +
-    "  investoday-api example stock/violation-penalties\n" +
-    "  investoday-api search-api 违规处罚\n" +
-    "  investoday-api search-api 股票 --text\n" +
-    "  investoday-api stock/basic-info stockCode=600519\n"
+    "  investoday-api list 沪深京数据/公司行为/基本信息\n" +
+    "  investoday-api search-api query=股票,基本面分析\n" +
+    "  investoday-api search-api tool_ids=list_stock_violation_penalt,list_stock_report_schema\n" +
+    "  investoday-api search-api query=股票 --text\n" +
+    "  investoday-api search key=贵州茅台 type=11\n" +
+    "  investoday-api stock/basic-info stockCode=600519\n" +
+    "  investoday-api fund/daily-quotes --method POST fundCode=000001 beginDate=2024-01-01 endDate=2024-12-31\n"
+  );
+}
+
+function printVersion() {
+  process.stdout.write(`${PACKAGE_VERSION}\n`);
+}
+
+function hasArg(args, name) {
+  return args.includes(name);
+}
+
+function printInitHelp() {
+  process.stdout.write(
+    "Usage:\n" +
+    "  investoday-api init\n\n" +
+    "Default flow:\n" +
+    "  Prompt for InvestToday API Key, verify it, then save it to local encrypted config.\n\n" +
+    "Options:\n" +
+    "  --skip-verify  Save without validating the API key first\n\n" +
+    `Local config: ${getCredentialsPath()}\n`
+  );
+}
+
+function askInput(query) {
+  const readline = require("node:readline");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function resolveInitApiKey(args) {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    exitWithError("ERROR: Interactive input is unavailable. Run 'investoday-api init' in an interactive terminal.");
+  }
+
+  const apiKey = await askInput("InvestToday API Key: ");
+  if (!String(apiKey || "").trim()) {
+    exitWithError("ERROR: API key cannot be empty.");
+  }
+  return apiKey.trim();
+}
+
+async function verifyApiKey(apiKey) {
+  const url = buildUrl("trade-calender/cn/is-trade-date", { tDate: "2025-12-22" });
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: { apiKey },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT),
+    });
+  } catch (error) {
+    let message = String(error.message || error);
+    if (apiKey && message.includes(apiKey)) {
+      message = message.replaceAll(apiKey, "***");
+    }
+    throw new Error(`verification request failed: ${message}`);
+  }
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status}${body ? `: ${body.slice(0, 500)}` : ""}`);
+  }
+
+  const result = await response.json().catch(() => null);
+  if (!result || result.code !== 0) {
+    throw new Error(result && result.message ? result.message : "invalid response");
+  }
+}
+
+async function runInitCommand(args) {
+  if (hasArg(args, "--help") || hasArg(args, "-h")) {
+    printInitHelp();
+    return;
+  }
+
+  const allowed = new Set(["--skip-verify"]);
+  for (const arg of args) {
+    if (!allowed.has(arg)) {
+      exitWithError(`ERROR: Unknown init option '${arg}'`);
+    }
+  }
+
+  const apiKey = await resolveInitApiKey(args);
+  if (!hasArg(args, "--skip-verify")) {
+    process.stderr.write("Verifying InvestToday API key...\n");
+    try {
+      await verifyApiKey(apiKey);
+    } catch (error) {
+      exitWithError(
+        `InvestToday API Key verification failed.\n` +
+        `Error: ${error.message}\n` +
+        `请登录 ${API_KEY_MANAGE_URL} 确认您的apiKey正确。`
+      );
+    }
+  }
+
+  try {
+    saveCredentials(apiKey);
+  } catch (error) {
+    exitWithError(`ERROR: Failed to save credentials: ${error.message}`);
+  }
+
+  process.stdout.write(
+    "InvestToday API key 配置成功\n\n" +
+    "初始化完成 ✅\n"
   );
 }
 
+function runConfigCommand(args) {
+  const action = args[0] || "status";
+  if (action === "--help" || action === "-h" || action === "help") {
+    process.stdout.write(
+      "Usage:\n" +
+      "  investoday-api config status\n" +
+      "  investoday-api config path\n" +
+      "  investoday-api config remove\n\n" +
+      `Config dir env override: ${CONFIG_DIR_ENV}\n`
+    );
+    return;
+  }
+
+  if (action === "path") {
+    process.stdout.write(`${getCredentialsPath()}\n`);
+    return;
+  }
+
+  if (action === "remove") {
+    removeCredentials();
+    process.stdout.write("InvestToday local credentials removed.\n");
+    return;
+  }
+
+  if (action === "status") {
+    const localConfigured = Boolean(readCredentials());
+    const activeSource = resolveApiKey().source;
+    process.stdout.write(
+      JSON.stringify({
+        status: activeSource === "missing" ? "missing" : "configured",
+        localConfig: localConfigured ? "configured" : "missing",
+        activeSource,
+        configDir: getConfigDir(),
+        credentialsFile: getCredentialsPath(),
+      }, null, 2) + "\n"
+    );
+    return;
+  }
+
+  exitWithError(`ERROR: Unknown config action '${action}'. Use status, path, or remove.`);
+}
+
 function normalizeExampleParameterKey(name) {
   return String(name || "").replace(/Codes$/, "Code").replace(/Ids$/, "Id").replace(/List$/, "");
 }
@@ -125,22 +299,6 @@ function printApiSuggestions(matches) {
   }
 }
 
-function getSingleApi(query) {
-  const { matches, error } = resolveApi(query);
-  if (error) {
-    exitWithError(`ERROR: ${error}`);
-  }
-  if (!matches.length) {
-    exitWithError(`ERROR: No endpoint matched '${query}'`);
-  }
-  if (matches.length > 1) {
-    printApiSuggestions(matches);
-    process.exit(1);
-  }
-
-  return matches[0];
-}
-
 function countEndpoints(node) {
   if (!node) {
     return 0;
@@ -262,7 +420,7 @@ function listGroup(query) {
     return;
   }
 
-  const { matches: fuzzyMatches } = searchApis(normalizedQuery, 20);
+  const { matches: fuzzyMatches } = searchApis({ query: [normalizedQuery] }, 20);
 
   if (!fuzzyMatches.length) {
     exitWithError(`ERROR: No group or endpoint matched '${normalizedQuery}'`);
@@ -290,41 +448,6 @@ function runListCommand(args) {
   listGroup(args.join(" "));
 }
 
-function runSchemaCommand(args) {
-  const api = getSingleApi(args.join(" "));
-  const payload = {
-    apiName: api.apiName,
-    groupPath: api.groupPath,
-    path: api.path,
-    method: api.method,
-    toolId: api.toolId,
-    toolName: api.toolName,
-    summary: api.summary,
-    description: api.description,
-    parameters: api.parameters,
-    responseFields: api.responseFields,
-  };
-
-  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-}
-
-function runExampleCommand(args) {
-  const api = getSingleApi(args.join(" "));
-  const optionalParams = api.parameters
-    .filter((parameter) => !parameter.required)
-    .map((parameter) => parameter.name);
-
-  const lines = [
-    `# ${api.apiName}`,
-    formatExample(api.path, api.method, api.parameters),
-  ];
-  if (optionalParams.length) {
-    lines.push(`# optional params: ${optionalParams.join(", ")}`);
-  }
-
-  process.stdout.write(`${lines.join("\n")}\n`);
-}
-
 function summarizeNames(items, emptyLabel) {
   if (!items || !items.length) {
     return emptyLabel;
@@ -353,20 +476,96 @@ function summarizeNames(items, emptyLabel) {
   return `${names.slice(0, 6).join(", ")} ... (+${names.length - 6})`;
 }
 
-function runSearchApiCommand(args) {
+function parseStructuredArgs(args) {
+  const params = {};
+
+  for (const arg of args) {
+    const equalIndex = arg.indexOf("=");
+    if (equalIndex <= 0) {
+      continue;
+    }
+    const key = arg.slice(0, equalIndex);
+    const value = arg.slice(equalIndex + 1);
+
+    if (Object.prototype.hasOwnProperty.call(params, key)) {
+      const existing = params[key];
+      params[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+    } else {
+      params[key] = value;
+    }
+  }
+
+  return params;
+}
+
+function normalizeSearchCriteria(args) {
   const textMode = args.includes("--text");
-  const query = args.filter((arg) => arg !== "--text").join(" ").trim();
-  const { matches, error } = searchApis(query, 10);
+  const filteredArgs = args.filter((arg) => arg !== "--text");
+  const structuredArgs = filteredArgs.filter((arg) => arg.includes("="));
+  const positionalArgs = filteredArgs.filter((arg) => !arg.includes("="));
+  if (positionalArgs.length) {
+    exitWithError("ERROR: search-api only accepts structured inputs such as query=... and tool_ids=....");
+  }
+  const params = parseStructuredArgs(structuredArgs);
+
+  const queryInputs = ["query", "q"]
+    .filter((key) => params[key] !== undefined)
+    .flatMap((key) => (Array.isArray(params[key]) ? params[key] : [params[key]]));
+  if (queryInputs.length > 1) {
+    exitWithError("ERROR: search-api only accepts one query=... value. Use commas inside query=... for multiple keywords.");
+  }
+
+  const rawQueryValues = [];
+  for (const key of ["query", "q"]) {
+    if (params[key] !== undefined) {
+      const value = params[key];
+      rawQueryValues.push(...(Array.isArray(value) ? value : [value]));
+    }
+  }
+
+  const rawToolIdValues = [];
+  for (const key of ["tool_ids", "tool_id", "toolIds"]) {
+    if (params[key] !== undefined) {
+      const value = params[key];
+      rawToolIdValues.push(...(Array.isArray(value) ? value : [value]));
+    }
+  }
+
+  const query = rawQueryValues
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const toolIds = rawToolIdValues
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  return {
+    textMode,
+    criteria: { query, toolIds },
+  };
+}
+
+function formatSearchLabel(criteria) {
+  const queryLabel = criteria.query.length ? `query='${criteria.query.join(" | ")}'` : null;
+  const toolIdLabel = criteria.toolIds.length ? `tool_ids=${criteria.toolIds.join(",")}` : null;
+  return [queryLabel, toolIdLabel].filter(Boolean).join(" ");
+}
+
+function runSearchApiCommand(args) {
+  const { textMode, criteria } = normalizeSearchCriteria(args);
+  const { matches, error } = searchApis(criteria, 10);
   if (error) {
     exitWithError(`ERROR: ${error}`);
   }
   if (!matches.length) {
-    exitWithError(`ERROR: No endpoints matched '${query}'`);
+    exitWithError(`ERROR: No endpoints matched ${formatSearchLabel(criteria) || "the provided criteria"}`);
   }
 
   if (!textMode) {
     const payload = {
-      query,
+      query: criteria.query.join(" "),
+      toolIds: criteria.toolIds,
       matches: matches.map((match) => ({
         apiName: match.apiName,
         path: match.path,
@@ -376,17 +575,22 @@ function runSearchApiCommand(args) {
         description: match.description,
         requestParams: match.parameters,
         responseFields: match.responseFields,
+        exampleCommand: formatExample(match.path, match.method, match.parameters),
       })),
     };
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
     return;
   }
 
-  const lines = [`Matches for '${query}':`];
+  const lines = [`Matches for ${formatSearchLabel(criteria) || "the provided criteria"}:`];
   for (const match of matches) {
     lines.push(`- ${match.apiName} | ${match.path} | ${match.method} | ${match.groupPath.join(" / ")}`);
+    if (match.description || match.summary) {
+      lines.push(`  desc: ${compactText(match.description || match.summary)}`);
+    }
     lines.push(`  request params: ${summarizeNames(match.parameters, "none")}`);
     lines.push(`  response fields: ${summarizeNames(match.responseFields, "none")}`);
+    lines.push(`  example: ${formatExample(match.path, match.method, match.parameters)}`);
   }
 
   process.stdout.write(`${lines.join("\n")}\n`);
@@ -536,18 +740,28 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  if (argv[0] === "list") {
-    runListCommand(argv.slice(1));
+  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version") {
+    printVersion();
     return;
   }
 
-  if (argv[0] === "schema") {
-    runSchemaCommand(argv.slice(1));
+  if (argv[0] === "init") {
+    await runInitCommand(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === "config") {
+    runConfigCommand(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === "list") {
+    runListCommand(argv.slice(1));
     return;
   }
 
-  if (argv[0] === "example") {
-    runExampleCommand(argv.slice(1));
+  if (argv[0] === "schema" || argv[0] === "example") {
+    exitWithError("ERROR: The schema and example commands were removed. Use 'investoday-api search-api <query>' instead.");
     return;
   }
 
@@ -572,11 +786,13 @@ module.exports = {
   main,
   parseArgs,
   printHelp,
+  printVersion,
+  runConfigCommand,
+  runInitCommand,
   runSearchApiCommand,
-  runExampleCommand,
   runListCommand,
-  runSchemaCommand,
   selectRequestMethod,
+  verifyApiKey,
 };
 
 if (require.main === module) {

package/lib/config.js

@@ -0,0 +1,175 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const CONFIG_DIR_ENV = "INVESTODAY_API_CONFIG_DIR";
+const API_KEY_ENV = "INVESTODAY_API_KEY";
+const CREDENTIALS_FILE = "credentials.enc";
+const KEY_FILE = ".encryption_key";
+const CIPHER_ALGORITHM = "aes-256-gcm";
+
+function getConfigDir(env = process.env) {
+  if (env[CONFIG_DIR_ENV]) {
+    return path.resolve(env[CONFIG_DIR_ENV]);
+  }
+
+  return path.join(os.homedir(), ".config", "investoday");
+}
+
+function getCredentialsPath(env = process.env) {
+  return path.join(getConfigDir(env), CREDENTIALS_FILE);
+}
+
+function getEncryptionKeyPath(env = process.env) {
+  return path.join(getConfigDir(env), KEY_FILE);
+}
+
+function ensureConfigDir(env = process.env) {
+  const dir = getConfigDir(env);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") {
+    fs.chmodSync(dir, 0o700);
+  }
+  return dir;
+}
+
+function atomicWriteFile(filePath, contents, mode = 0o600) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, contents, { mode });
+  if (process.platform !== "win32") {
+    fs.chmodSync(tempPath, mode);
+  }
+  fs.renameSync(tempPath, filePath);
+}
+
+function loadOrCreateEncryptionKey(env = process.env) {
+  ensureConfigDir(env);
+  const keyPath = getEncryptionKeyPath(env);
+  if (fs.existsSync(keyPath)) {
+    const encoded = fs.readFileSync(keyPath, "utf8").trim();
+    const key = Buffer.from(encoded, "base64");
+    if (key.length !== 32) {
+      throw new Error(`Invalid encryption key at ${keyPath}`);
+    }
+    return key;
+  }
+
+  const key = crypto.randomBytes(32);
+  atomicWriteFile(keyPath, key.toString("base64"));
+  return key;
+}
+
+function loadEncryptionKey(env = process.env) {
+  const keyPath = getEncryptionKeyPath(env);
+  if (!fs.existsSync(keyPath)) {
+    return null;
+  }
+
+  const encoded = fs.readFileSync(keyPath, "utf8").trim();
+  const key = Buffer.from(encoded, "base64");
+  if (key.length !== 32) {
+    return null;
+  }
+  return key;
+}
+
+function encryptJson(value, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(CIPHER_ALGORITHM, key, iv);
+  const plaintext = Buffer.from(JSON.stringify(value), "utf8");
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+
+  return {
+    version: 1,
+    algorithm: CIPHER_ALGORITHM,
+    iv: iv.toString("base64"),
+    tag: tag.toString("base64"),
+    data: encrypted.toString("base64"),
+  };
+}
+
+function decryptJson(payload, key) {
+  if (!payload || payload.algorithm !== CIPHER_ALGORITHM) {
+    throw new Error("Unsupported credentials format");
+  }
+
+  const decipher = crypto.createDecipheriv(
+    CIPHER_ALGORITHM,
+    key,
+    Buffer.from(payload.iv, "base64")
+  );
+  decipher.setAuthTag(Buffer.from(payload.tag, "base64"));
+  const decrypted = Buffer.concat([
+    decipher.update(Buffer.from(payload.data, "base64")),
+    decipher.final(),
+  ]);
+  return JSON.parse(decrypted.toString("utf8"));
+}
+
+function saveCredentials(apiKey, env = process.env) {
+  const trimmedKey = String(apiKey || "").trim();
+  if (!trimmedKey) {
+    throw new Error("API key cannot be empty");
+  }
+
+  const key = loadOrCreateEncryptionKey(env);
+  const payload = encryptJson({
+    apiKey: trimmedKey,
+    createdAt: new Date().toISOString(),
+  }, key);
+  atomicWriteFile(getCredentialsPath(env), `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function readCredentials(env = process.env) {
+  const credentialsPath = getCredentialsPath(env);
+  const key = loadEncryptionKey(env);
+  if (!key || !fs.existsSync(credentialsPath)) {
+    return null;
+  }
+
+  try {
+    const payload = JSON.parse(fs.readFileSync(credentialsPath, "utf8"));
+    return decryptJson(payload, key);
+  } catch {
+    return null;
+  }
+}
+
+function removeCredentials(env = process.env) {
+  for (const filePath of [getCredentialsPath(env), getEncryptionKeyPath(env)]) {
+    if (fs.existsSync(filePath)) {
+      fs.rmSync(filePath, { force: true });
+    }
+  }
+}
+
+function resolveApiKey(env = process.env) {
+  const envKey = String(env[API_KEY_ENV] || "").trim();
+  if (envKey) {
+    return { apiKey: envKey, source: "compat" };
+  }
+
+  const credentials = readCredentials(env);
+  if (credentials && credentials.apiKey) {
+    return { apiKey: String(credentials.apiKey).trim(), source: "config" };
+  }
+
+  return { apiKey: "", source: "missing" };
+}
+
+module.exports = {
+  API_KEY_ENV,
+  CONFIG_DIR_ENV,
+  CREDENTIALS_FILE,
+  KEY_FILE,
+  getConfigDir,
+  getCredentialsPath,
+  getEncryptionKeyPath,
+  readCredentials,
+  removeCredentials,
+  resolveApiKey,
+  saveCredentials,
+};

package/lib/metadata.js

@@ -295,6 +295,34 @@ function scoreRecord(record, query) {
   return score;
 }
 
+function matchesRecordQuery(record, query) {
+  return scoreRecord(record, query) > 0;
+}
+
+function normalizeSearchInput(input) {
+  const rawQueries = Array.isArray(input?.query)
+    ? input.query
+    : input?.query !== undefined && input?.query !== null && input?.query !== ""
+      ? [input.query]
+      : [];
+  const rawToolIds = Array.isArray(input?.toolIds)
+    ? input.toolIds
+    : input?.toolIds !== undefined && input?.toolIds !== null && input?.toolIds !== ""
+      ? [input.toolIds]
+      : [];
+
+  const queries = rawQueries
+    .flatMap((value) => String(value || "").split("\n"))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const toolIds = rawToolIds
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+
+  return { queries, toolIds };
+}
+
 function resolveApi(query) {
   const normalizedQuery = (query || "").trim();
   if (!normalizedQuery) {
@@ -333,17 +361,44 @@ function resolveApi(query) {
   return { matches: fuzzyMatches };
 }
 
-function searchApis(query, limit = 10) {
-  const normalizedQuery = (query || "").trim();
-  if (!normalizedQuery) {
-    return { matches: [], error: "Please provide a search query." };
+function searchApis(input, limit = 10) {
+  const { queries, toolIds } = normalizeSearchInput(input);
+  if (!queries.length && !toolIds.length) {
+    return { matches: [], error: "Please provide query=... and/or tool_ids=... ." };
   }
 
   const { records } = getMetadata();
-  const scored = records
-    .map((record) => ({ record, score: scoreRecord(record, normalizedQuery) }))
-    .filter((item) => item.score > 0)
-    .sort((left, right) => right.score - left.score || left.record.path.localeCompare(right.record.path))
+  let candidates = records;
+  const toolIdOrder = new Map(toolIds.map((toolId, index) => [toolId, index]));
+
+  if (toolIds.length) {
+    const toolIdSet = new Set(toolIds);
+    candidates = candidates.filter((record) => toolIdSet.has(record.toolId));
+    if (!queries.length) {
+      const matches = candidates
+        .sort((left, right) =>
+          (toolIdOrder.get(left.toolId) ?? Number.MAX_SAFE_INTEGER) -
+            (toolIdOrder.get(right.toolId) ?? Number.MAX_SAFE_INTEGER) ||
+          left.path.localeCompare(right.path)
+        )
+        .slice(0, limit);
+      return { matches };
+    }
+  }
+
+  const scored = candidates
+    .map((record) => ({
+      record,
+      matchedAllQueries: queries.every((query) => matchesRecordQuery(record, query)),
+      score: queries.reduce((sum, query) => sum + scoreRecord(record, query), 0),
+    }))
+    .filter((item) => item.matchedAllQueries && item.score > 0)
+    .sort((left, right) =>
+      right.score - left.score ||
+      (toolIdOrder.get(left.record.toolId) ?? Number.MAX_SAFE_INTEGER) -
+        (toolIdOrder.get(right.record.toolId) ?? Number.MAX_SAFE_INTEGER) ||
+      left.record.path.localeCompare(right.record.path)
+    )
     .slice(0, limit)
     .map((item) => item.record);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@investoday/investoday-api",
-  "version": "1.1.0",
+  "version": "1.8.0",
   "description": "CLI for accessing InvestToday China market financial data via investoday-api.",
   "license": "MIT",
   "homepage": "https://github.com/investoday-data/investoday-api-skills",