@qverisai/cli 0.3.0 → 0.5.0

package/src/commands/login.mjs

@@ -5,11 +5,10 @@ import { resolve } from "../config/resolve.mjs";
 import { setConfigValue, deleteConfigValue } from "../config/store.mjs";
 import { discoverTools } from "../client/api.mjs";
 import { VERSION } from "../config/defaults.mjs";
+import { resolveBaseUrl, getSiteUrl } from "../config/region.mjs";
 import { bold, green, red, dim, cyan } from "../output/colors.mjs";
 import { printLoginBanner } from "../output/banner.mjs";
 
-const ACCOUNT_URL = "https://qveris.ai/account?page=api-keys";
-
 function openBrowser(url) {
   const cmds = { darwin: "open", win32: "cmd", linux: "xdg-open" };
   const cmd = cmds[platform()] || "xdg-open";
@@ -87,9 +86,54 @@ function prompt(question) {
   });
 }
 
+/**
+ * Prompt user to select region interactively.
+ * Skipped if region is already determined via --base-url, QVERIS_REGION, or QVERIS_BASE_URL.
+ */
+function promptRegion() {
+  return new Promise((pResolve, pReject) => {
+    console.log(`  ${bold("Select your region / 选择站点区域:")}\n`);
+    console.log(`    ${cyan("1)")} Global  — qveris.ai  (International users)`);
+    console.log(`    ${cyan("2)")} China   — qveris.cn  (中国大陆用户)\n`);
+
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question("  Enter 1 or 2: ", (answer) => { rl.close(); pResolve(answer.trim()); });
+      return;
+    }
+
+    process.stderr.write("  Enter 1 or 2: ");
+
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      try { process.stdin.setRawMode(false); } catch {}
+      process.stdin.pause();
+    };
+    const onExit = () => { try { process.stdin.setRawMode(false); } catch {} };
+    process.once("exit", onExit);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+
+    const onData = (chunk) => {
+      const ch = chunk[0];
+      if (ch === "\x03") { cleanup(); process.removeListener("exit", onExit); process.stderr.write("\n"); pReject(new Error("Aborted")); return; }
+      if (ch === "1" || ch === "2") {
+        cleanup();
+        process.removeListener("exit", onExit);
+        process.stderr.write(`${ch}\n`);
+        pResolve(ch);
+      }
+      // Ignore other keys
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
 export async function runLogin(flags) {
   if (flags.token) {
-    await validateAndSave(flags.token);
+    await validateAndSave(flags.token, flags.baseUrl);
     return;
   }
 
@@ -97,10 +141,29 @@ export async function runLogin(flags) {
     printLoginBanner({ version: VERSION, noColor: flags.noColor });
   }
 
-  console.log(`  Get your API key at: ${cyan(ACCOUNT_URL)}\n`);
+  // Determine region: if already set via flag/env, use that; otherwise ask the user.
+  const { region: presetRegion, baseUrl: presetBaseUrl, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl });
+  let region;
+  let baseUrl = presetBaseUrl;
+  if (regionSource !== "default") {
+    // Region explicitly configured — use it directly
+    region = presetRegion;
+  } else {
+    // No explicit region — let user choose interactively
+    let choice;
+    try {
+      choice = await promptRegion();
+    } catch {
+      return; // Ctrl+C
+    }
+    region = choice === "2" ? "cn" : "global";
+  }
+
+  const accountUrl = `${getSiteUrl(region, baseUrl)}/account?page=api-keys`;
+  console.log(`\n  Get your API key at: ${cyan(accountUrl)}\n`);
 
   if (!flags.noBrowser) {
-    openBrowser(ACCOUNT_URL);
+    openBrowser(accountUrl);
   }
 
   let key;
@@ -116,18 +179,21 @@ export async function runLogin(flags) {
     return;
   }
 
-  await validateAndSave(key);
+  await validateAndSave(key, flags.baseUrl);
 }
 
-async function validateAndSave(key) {
+async function validateAndSave(key, baseUrlFlag) {
   process.stderr.write(`  Validating key...`);
 
+  const { baseUrl, region, source } = resolveBaseUrl({ baseUrlFlag, apiKey: key });
+
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
     setConfigValue("api_key", key);
     const masked = key.slice(0, 6) + "..." + key.slice(-4);
     console.error(`\r\x1b[K`);
     console.log(`  ${green("\u2713")} Authenticated as ${bold(masked)}`);
+    console.log(`  ${dim("Region:")} ${region} ${dim(`(${source})`)}`);
     console.log(`  ${dim("Key saved to config.")}`);
   } catch {
     console.error(`\r\x1b[K`);
@@ -151,15 +217,17 @@ export async function runWhoami(flags) {
   }
 
   const masked = key.slice(0, 6) + "..." + key.slice(-4);
+  const { baseUrl, region, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey: key });
 
   process.stderr.write(`  Validating...`);
 
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
     process.stderr.write("\r\x1b[K");
     console.log(`\n  ${green("\u2713")} Authenticated`);
     console.log(`  Key:    ${bold(masked)}`);
     console.log(`  Source: ${dim(source)}`);
+    console.log(`  Region: ${region} ${dim(`(${regionSource})`)}`);
   } catch {
     console.error(`\r\x1b[K`);
     console.log(`\n  ${red("\u2718")} Key ${masked} is ${red("invalid")}`);

package/src/commands/usage.mjs

@@ -0,0 +1,190 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { getUsageHistory, unwrapApiResponse } from "../client/api.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_EXPORT_ROWS,
+  MAX_SEARCH_SCAN_ROWS,
+  MAX_SUMMARY_ROWS,
+  buildUsageQuery,
+  buildUsageSummary,
+  buildUsageSummaryFromServer,
+  chooseBucket,
+  clampLimit,
+  extractItems,
+  extractTotal,
+  formatExportMetadata,
+  formatUsageRows,
+  formatUsageSummary,
+  matchesUsageFilters,
+  pickUsageRow,
+  resolveDateRange,
+  resolveMode,
+  writeJsonlExport,
+} from "../output/audit.mjs";
+
+export async function runUsage(flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const mode = resolveMode(flags.mode);
+  const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
+  const limit = clampLimit(flags.limit);
+  const { startDate, endDate } = resolveDateRange(flags);
+  const bucket = chooseBucket(startDate, endDate, flags.bucket);
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Querying usage history...");
+
+  try {
+    if (mode === "search") {
+      const { rows, total, partial } = await collectUsageRows({
+        apiKey,
+        flags,
+        timeoutMs,
+        limit,
+        maxRows: MAX_SEARCH_SCAN_ROWS,
+        stopWhenLimitReached: true,
+      });
+      spinner.stop();
+      const payload = {
+        mode,
+        start_date: startDate,
+        end_date: endDate,
+        shown_records: rows.length,
+        matched_records: total,
+        truncated: partial,
+        items: rows.map(pickUsageRow),
+      };
+      if (flags.json) outputJson(payload);
+      else console.log(formatUsageRows(rows, { total, partial }));
+      return;
+    }
+
+    if (mode === "export_file") {
+      const { rows, total, partial } = await collectUsageRows({
+        apiKey,
+        flags,
+        timeoutMs,
+        limit: MAX_EXPORT_ROWS,
+        maxRows: MAX_EXPORT_ROWS,
+        stopWhenLimitReached: false,
+      });
+      spinner.stop();
+      const metadata = writeJsonlExport("usage_history", rows, {
+        start_date: startDate,
+        end_date: endDate,
+        matched_records: total,
+        truncated: partial,
+        filters: usageFilters(flags),
+      });
+      if (flags.json) outputJson(metadata);
+      else console.log(formatExportMetadata(metadata));
+      return;
+    }
+
+    const summaryResponse = unwrapApiResponse(await getUsageHistory({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query: buildUsageQuery(flags, {
+        page: 1,
+        pageSize: limit,
+        mode: "summary",
+      }),
+      timeoutMs,
+    }));
+    if (summaryResponse?.summary) {
+      spinner.stop();
+      const rows = extractItems(summaryResponse);
+      const total = extractTotal(summaryResponse, rows.length);
+      const summary = buildUsageSummaryFromServer(summaryResponse.summary, { startDate, endDate, bucket });
+      if (flags.json) {
+        outputJson({
+          mode,
+          summary,
+          scanned_records: rows.length,
+          matched_records: total,
+          truncated: false,
+        });
+      } else {
+        console.log(formatUsageSummary(summary, { scannedRows: rows.length, total, partial: false }));
+      }
+      return;
+    }
+
+    const { rows, total, partial, scannedRows } = await collectUsageRows({
+      apiKey,
+      flags,
+      timeoutMs,
+      limit: MAX_SUMMARY_ROWS,
+      maxRows: MAX_SUMMARY_ROWS,
+      stopWhenLimitReached: false,
+    });
+    spinner.stop();
+    const summary = buildUsageSummary(rows, { startDate, endDate, bucket });
+    if (flags.json) {
+      outputJson({
+        mode,
+        summary,
+        scanned_records: scannedRows,
+        matched_records: total,
+        truncated: partial,
+      });
+    } else {
+      console.log(formatUsageSummary(summary, { scannedRows, total, partial }));
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}
+
+async function collectUsageRows({ apiKey, flags, timeoutMs, limit, maxRows, stopWhenLimitReached }) {
+  const rows = [];
+  let page = 1;
+  let total;
+  let scannedRows = 0;
+  let partial = false;
+
+  while (rows.length < limit && scannedRows < maxRows) {
+    const query = buildUsageQuery(flags, { page, pageSize: Math.min(DEFAULT_PAGE_SIZE, maxRows - scannedRows) });
+    const response = unwrapApiResponse(await getUsageHistory({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query,
+      timeoutMs,
+    }));
+    const items = extractItems(response);
+    if (total === undefined) total = extractTotal(response, undefined);
+    if (items.length === 0) break;
+    scannedRows += items.length;
+    for (const item of items) {
+      if (!matchesUsageFilters(item, flags)) continue;
+      rows.push(item);
+      if (stopWhenLimitReached && rows.length >= limit) break;
+    }
+    if (stopWhenLimitReached && rows.length >= limit) {
+      partial = Boolean(total && total > scannedRows);
+      break;
+    }
+    if (total !== undefined && scannedRows >= total) break;
+    if (items.length < DEFAULT_PAGE_SIZE) break;
+    page += 1;
+  }
+
+  if (total !== undefined && scannedRows < total) partial = true;
+  if (scannedRows >= maxRows && (total === undefined || scannedRows < total)) partial = true;
+
+  return { rows: rows.slice(0, limit), total, partial, scannedRows };
+}
+
+function usageFilters(flags) {
+  return {
+    execution_id: flags.executionId,
+    search_id: flags.searchId,
+    event_type: flags.eventType,
+    kind: flags.kind,
+    success: flags.success,
+    charge_outcome: flags.chargeOutcome,
+    min_credits: flags.minCredits,
+    max_credits: flags.maxCredits,
+  };
+}

package/src/compat/aliases.mjs

@@ -13,6 +13,7 @@ const FLAG_ALIASES = {
 export function normalizeLegacyArgs(args) {
   const result = [...args];
   const warnings = [];
+  const originalCommand = result[0];
 
   if (result.length > 0 && COMMAND_ALIASES[result[0]]) {
     warnings.push(`'${result[0]}' is deprecated; use '${COMMAND_ALIASES[result[0]]}' instead.`);
@@ -20,6 +21,9 @@ export function normalizeLegacyArgs(args) {
   }
 
   for (let i = 0; i < result.length; i++) {
+    if (originalCommand === "usage" && result[i] === "--search-id") {
+      continue;
+    }
     if (FLAG_ALIASES[result[i]]) {
       warnings.push(`'${result[i]}' is deprecated; use '${FLAG_ALIASES[result[i]]}' instead.`);
       result[i] = FLAG_ALIASES[result[i]];

package/src/config/region.mjs

@@ -13,6 +13,26 @@ const REGION_URLS = {
   cn: "https://qveris.cn/api/v1",
 };
 
+const SITE_URLS = {
+  global: "https://qveris.ai",
+  cn: "https://qveris.cn",
+};
+
+/**
+ * Get the site URL (not API URL) for a given region.
+ * For custom regions, attempts to infer from the base URL domain.
+ * @param {string} region
+ * @param {string} [baseUrl] - The resolved API base URL (used to infer site for custom regions)
+ * @returns {string}
+ */
+export function getSiteUrl(region, baseUrl) {
+  if (region === "custom" && baseUrl) {
+    if (baseUrl.includes("qveris.cn")) return SITE_URLS.cn;
+    if (baseUrl.includes("qveris.ai")) return SITE_URLS.global;
+  }
+  return SITE_URLS[region] || SITE_URLS.global;
+}
+
 /**
  * Detect region from API key prefix.
  * @param {string} apiKey

package/src/main.mjs

@@ -72,6 +72,16 @@ export async function main(argv) {
         await runCredits(flags);
         break;
       }
+      case "usage": {
+        const { runUsage } = await import("./commands/usage.mjs");
+        await runUsage(flags);
+        break;
+      }
+      case "ledger": {
+        const { runLedger } = await import("./commands/ledger.mjs");
+        await runLedger(flags);
+        break;
+      }
       case "config": {
         const subcommand = rest[0];
         const subArgs = rest.slice(1);
@@ -119,6 +129,11 @@ const VALUE_FLAGS = {
   "api-key": "apiKey", "base-url": "baseUrl", timeout: "timeout",
   limit: "limit", "discovery-id": "discoveryId", params: "params",
   "max-size": "maxSize", codegen: "codegen", token: "token",
+  mode: "mode", "start-date": "startDate", "end-date": "endDate",
+  bucket: "bucket", "execution-id": "executionId", "search-id": "searchId",
+  "event-type": "eventType", kind: "kind", success: "success",
+  "charge-outcome": "chargeOutcome", "entry-type": "entryType",
+  direction: "direction", "min-credits": "minCredits", "max-credits": "maxCredits",
 };
 
 function takeNext(args, i, flag) {
@@ -199,6 +214,34 @@ function extractGlobalFlags(args) {
         flags.codegen = takeNext(args, i++, arg); break;
       case "--token":
         flags.token = takeNext(args, i++, arg); break;
+      case "--mode":
+        flags.mode = takeNext(args, i++, arg); break;
+      case "--start-date":
+        flags.startDate = takeNext(args, i++, arg); break;
+      case "--end-date":
+        flags.endDate = takeNext(args, i++, arg); break;
+      case "--bucket":
+        flags.bucket = takeNext(args, i++, arg); break;
+      case "--execution-id":
+        flags.executionId = takeNext(args, i++, arg); break;
+      case "--search-id":
+        flags.searchId = takeNext(args, i++, arg); break;
+      case "--event-type":
+        flags.eventType = takeNext(args, i++, arg); break;
+      case "--kind":
+        flags.kind = takeNext(args, i++, arg); break;
+      case "--success":
+        flags.success = takeNext(args, i++, arg); break;
+      case "--charge-outcome":
+        flags.chargeOutcome = takeNext(args, i++, arg); break;
+      case "--entry-type":
+        flags.entryType = takeNext(args, i++, arg); break;
+      case "--direction":
+        flags.direction = takeNext(args, i++, arg); break;
+      case "--min-credits":
+        flags.minCredits = takeNext(args, i++, arg); break;
+      case "--max-credits":
+        flags.maxCredits = takeNext(args, i++, arg); break;
       default:
         flags._positional.push(arg);
     }
@@ -228,6 +271,8 @@ function printUsage(flags = {}) {
     ${cyan("logout")}                       Remove stored API key
     ${cyan("whoami")}                       Show current auth status
     ${cyan("credits")}                      Show credit balance
+    ${cyan("usage")}                        Summarize or search usage audit history
+    ${cyan("ledger")}                       Summarize or search credit ledger entries
 
   ${bold("Configuration:")}
     ${cyan("config")}   set|get|list|reset  Manage CLI settings
@@ -241,19 +286,32 @@ function printUsage(flags = {}) {
   ${bold("Global Flags:")}
     --json, -j             Output raw JSON
     --api-key <key>        Override API key
+    --base-url <url>       Override API base URL
     --timeout <seconds>    Request timeout
+    --mode <mode>          summary | search | export-file for usage/ledger
+    --start-date <date>    Usage/ledger range start (YYYY-MM-DD)
+    --end-date <date>      Usage/ledger range end (YYYY-MM-DD)
+    --min-credits <n>      Usage/ledger amount lower bound
+    --max-credits <n>      Usage/ledger amount upper bound
     --no-color             Disable colors
     --verbose, -v          Show request details
     --version, -V          Print version
     --help, -h             Show help
 
+  ${bold("Environment Variables:")}
+    QVERIS_API_KEY         API key
+    QVERIS_REGION          Region override (global | cn)
+    QVERIS_BASE_URL        Custom API base URL
+
   ${bold("Examples:")}
     qveris discover "weather forecast API"
     qveris inspect 1
     qveris call 1 --params '{"city": "London"}'
     qveris call 1 --params @params.json --codegen curl
+    qveris usage --mode search --execution-id <id>
+    qveris ledger --mode search --min-credits 50 --direction consume
     qveris interactive
 
-  ${dim("https://qveris.ai")}
+  ${dim("https://qveris.ai (global) / https://qveris.cn (China)")}
 `);
 }