@qverisai/cli 0.4.0 → 0.5.0

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/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
@@ -243,6 +288,11 @@ function printUsage(flags = {}) {
     --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
@@ -258,6 +308,8 @@ function printUsage(flags = {}) {
     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 (global) / https://qveris.cn (China)")}