@qverisai/cli 0.4.0 → 0.5.0

package/README.md

@@ -9,12 +9,12 @@ Found 5 capabilities matching your query
 1. gridpoint_forecast  by Weather.gov
    weather_gov.gridpoints.forecast.retrieve.v1
    Returns a textual forecast for a 2.5km grid area
-   relevance: 95%  ·  success: 99.8%  ·  latency: ~180ms  ·  cost: 3 cr
+   relevance: 95%  ·  success: 99.8%  ·  latency: ~180ms  ·  billing: 3 credits / request
 
 2. current_weather  by OpenWeather
    openweathermap.weather.current.v1
    Get current weather data for any location
-   relevance: 87%  ·  success: 99.5%  ·  latency: ~200ms  ·  cost: 2 cr
+   relevance: 87%  ·  success: 99.5%  ·  latency: ~200ms  ·  billing: 2 credits / request
 
 $ qveris inspect 1
 gridpoint_forecast
@@ -23,7 +23,7 @@ Returns a textual forecast for a 2.5km grid area
   Provider:   Weather.gov
   Latency:    ~180ms
   Success:    99.8%
-  Cost:       3 credits
+  Billing:    3 credits / request
 
   Parameters:
     wfo     string   required
@@ -38,9 +38,13 @@ Returns a textual forecast for a 2.5km grid area
     {"wfo": "LWX", "x": 90, "y": 90}
 
 $ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
-✓ success  ·  523ms  ·  10 credits  ·  (1368087.93 remaining)
+✓ success  ·  523ms  ·  10 credits pre-settlement  ·  (1368087.93 remaining)
 tool: weather_gov...  ·  id: 7ebcaf9d-...
 
+Billing:
+  10 credits per successful request
+  Pre-settlement: 10 credits
+
 {
   "type": "Feature",
   "properties": {
@@ -96,9 +100,9 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 
 | Command | Description |
 |---------|-------------|
-| `qveris discover <query>` | Find capabilities by natural language. Shows tool ID, provider, description, relevance, success rate, latency, and cost for each result. |
+| `qveris discover <query>` | Find capabilities by natural language. Shows tool ID, provider, description, relevance, success rate, latency, and billing rule when available. |
 | `qveris inspect <id\|index>` | View full tool details: parameters (type, required, description, enum values), example, provider info, execution history. |
-| `qveris call <id\|index>` | Execute a capability. Shows result data, execution time, cost, and remaining credits. |
+| `qveris call <id\|index>` | Execute a capability. Shows result data, execution time, pre-settlement billing, and remaining credits. |
 
 ### Account
 
@@ -108,6 +112,8 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 | `qveris logout` | Remove stored key |
 | `qveris whoami` | Show current auth status, key source, and region |
 | `qveris credits` | Check credit balance |
+| `qveris usage` | Context-safe usage audit summary/search/export |
+| `qveris ledger` | Context-safe credits ledger summary/search/export |
 
 ### Utilities
 
@@ -146,7 +152,7 @@ qveris inspect 1 2 3
 
 ### Call
 
-Execute a tool. Results are automatically truncated for terminal display (4KB). Large results get an OSS download link.
+Execute a tool. Results are automatically truncated for terminal display (4KB). Large results get an OSS download link. Billing shown here is pre-settlement; use `qveris usage` or `qveris ledger` for final charge status.
 
 ```bash
 # Inline params
@@ -178,7 +184,7 @@ For terminal use, results larger than 4KB are automatically truncated. The CLI s
 - The response schema so you know the data structure
 
 ```
-✓ success  ·  1200ms  ·  5 credits
+✓ success  ·  1200ms  ·  5 credits pre-settlement
 
 Response truncated (32KB → 4KB preview)
 
@@ -199,6 +205,40 @@ Preview:
 
 For agent/script use (`--json` or piped output), the default increases to 20KB (matching the MCP server). Use `--max-size -1` for unlimited.
 
+### Usage Audit
+
+Use `qveris usage` to answer whether recent calls succeeded, failed, or charged credits. It defaults to `summary` mode to protect Agent context.
+Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
+
+```bash
+# Aggregate recent usage by hour/day/week
+qveris usage --mode summary --bucket hour
+
+# Check one execution precisely
+qveris usage --mode search --execution-id <execution_id> --json
+
+# Find high-cost or suspicious records
+qveris usage --mode search --min-credits 30 --max-credits 100 --json
+qveris usage --mode search --charge-outcome failed_charged_review --json
+
+# Export raw matching rows to a local JSONL file instead of stdout
+qveris usage --mode export-file --start-date 2026-05-01 --end-date 2026-05-04
+```
+
+### Credits Ledger
+
+Use `qveris ledger` to explain final credit balance movements. It also defaults to `summary` mode.
+Summary mode requests service-side `summary=true` aggregates when available and falls back to bounded client-side aggregation for older deployments.
+
+```bash
+qveris ledger --mode summary --bucket day
+qveris ledger --mode search --direction consume --min-credits 50 --json
+qveris ledger --mode search --entry-type consume_tool_execute --json
+qveris ledger --mode export-file --start-date 2026-05-01 --end-date 2026-05-04
+```
+
+`summary` and `search` never print full history. Large record sets are written to `.qveris/exports/*.jsonl` with `--mode export-file`.
+
 ### Interactive Mode
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qverisai/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "QVeris CLI -- discover, inspect, and call 10,000+ capabilities",
   "type": "module",
   "bin": {

package/src/client/api.mjs

@@ -36,7 +36,12 @@ async function requestJson(path, { method = "POST", query = {}, body, timeoutMs
         errorDetail = jsonBody.error_message || jsonBody.message || null;
       } catch { /* not JSON */ }
       if (status === 401 || status === 403) throw new CliError("AUTH_INVALID_KEY", errorDetail);
-      if (status === 402) throw new CliError("CREDITS_INSUFFICIENT", errorDetail);
+      if (status === 402) {
+        const pricingHost = baseUrl.includes("qveris.cn") ? "https://qveris.cn" : "https://qveris.ai";
+        const err = new CliError("CREDITS_INSUFFICIENT", errorDetail);
+        err.hint = `Purchase credits at ${pricingHost}/pricing`;
+        throw err;
+      }
       if (status === 429) throw new CliError("RATE_LIMITED", errorDetail);
       const err = new CliError("API_ERROR", `HTTP ${status}: ${errorDetail || rawText}`);
       if (jsonBody) err.responseData = jsonBody;
@@ -57,6 +62,21 @@ async function requestJson(path, { method = "POST", query = {}, body, timeoutMs
   }
 }
 
+export function unwrapApiResponse(response) {
+  if (
+    response &&
+    typeof response === "object" &&
+    Object.prototype.hasOwnProperty.call(response, "status") &&
+    Object.prototype.hasOwnProperty.call(response, "data")
+  ) {
+    if (response.status === "failure") {
+      throw new CliError("API_ERROR", response.message || "API request failed");
+    }
+    return response.data;
+  }
+  return response;
+}
+
 export async function discoverTools({ apiKey, baseUrl: baseUrlFlag, query, limit = 5, timeoutMs = 30000 }) {
   const baseUrl = getBaseUrl(baseUrlFlag, apiKey);
   return requestJson("/search", { apiKey, baseUrl, body: { query, limit }, timeoutMs });
@@ -91,3 +111,45 @@ export async function callTool({
     timeoutMs,
   });
 }
+
+export async function getCredits({ apiKey, baseUrl: baseUrlFlag, timeoutMs = 30000 }) {
+  const baseUrl = getBaseUrl(baseUrlFlag, apiKey);
+  return requestJson("/auth/credits", {
+    method: "GET",
+    apiKey,
+    baseUrl,
+    timeoutMs,
+  });
+}
+
+export async function getUsageHistory({
+  apiKey,
+  baseUrl: baseUrlFlag,
+  query = {},
+  timeoutMs = 30000,
+}) {
+  const baseUrl = getBaseUrl(baseUrlFlag, apiKey);
+  return requestJson("/auth/usage/history/v2", {
+    method: "GET",
+    apiKey,
+    baseUrl,
+    query,
+    timeoutMs,
+  });
+}
+
+export async function getCreditsLedger({
+  apiKey,
+  baseUrl: baseUrlFlag,
+  query = {},
+  timeoutMs = 30000,
+}) {
+  const baseUrl = getBaseUrl(baseUrlFlag, apiKey);
+  return requestJson("/auth/credits/ledger", {
+    method: "GET",
+    apiKey,
+    baseUrl,
+    query,
+    timeoutMs,
+  });
+}

package/src/commands/completions.mjs

@@ -1,6 +1,6 @@
 const COMMANDS = [
   "discover", "inspect", "call",
-  "login", "logout", "whoami", "credits",
+  "login", "logout", "whoami", "credits", "usage", "ledger",
   "config", "interactive", "history", "doctor", "completions",
 ];
 

package/src/commands/credits.mjs

@@ -1,5 +1,5 @@
 import { resolveApiKey } from "../client/auth.mjs";
-import { discoverTools } from "../client/api.mjs";
+import { getCredits, unwrapApiResponse } from "../client/api.mjs";
 import { resolveBaseUrl, getSiteUrl } from "../config/region.mjs";
 import { bold, dim, cyan, yellow, green } from "../output/colors.mjs";
 import { outputJson } from "../output/json.mjs";
@@ -13,16 +13,19 @@ export async function runCredits(flags) {
   const spinner = flags.json ? { stop() {} } : createSpinner("Checking credits...");
 
   try {
-    // The backend returns remaining_credits in every /search response
-    const result = await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "credit balance", limit: 1, timeoutMs: 10000 });
+    const result = unwrapApiResponse(await getCredits({ apiKey, baseUrl, timeoutMs: 10000 }));
     spinner.stop();
 
     const credits = result.remaining_credits;
 
     if (flags.json) {
-      outputJson({ remaining_credits: credits ?? null });
+      outputJson(result);
     } else if (credits !== undefined && credits !== null) {
       console.log(`\n  ${green("\u2713")} Credits remaining: ${bold(yellow(String(credits)))}`);
+      printBucket("Daily free", result.daily_free, "remaining", "total");
+      printBucket("Invite reward", result.invite_reward, "remaining", "total");
+      printBucket("Welcome bonus", result.welcome_bonus, "remaining", "initial");
+      printBucket("Purchased", result.purchased, "remaining", "total");
       console.log(`  ${dim("Manage at:")} ${cyan(accountUrl)}\n`);
     } else {
       console.log(`\n  ${dim("Credit balance not available in API response.")}`);
@@ -33,3 +36,14 @@ export async function runCredits(flags) {
     throw err;
   }
 }
+
+function printBucket(label, bucket, remainingKey, totalKey) {
+  if (!bucket || typeof bucket !== "object") return;
+  const remaining = bucket[remainingKey];
+  const total = bucket[totalKey];
+  if (remaining === undefined && total === undefined) return;
+  const parts = [];
+  if (remaining !== undefined) parts.push(`remaining ${yellow(String(remaining))}`);
+  if (total !== undefined) parts.push(`${dim("of")} ${String(total)}`);
+  console.log(`  ${dim(label + ":")} ${parts.join(" ")}`);
+}

package/src/commands/discover.mjs

@@ -8,6 +8,7 @@ import { createSpinner } from "../output/spinner.mjs";
 
 export async function runDiscover(query, flags) {
   const apiKey = resolveApiKey(flags.apiKey);
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
 
@@ -16,7 +17,7 @@ export async function runDiscover(query, flags) {
   try {
     const result = await discoverTools({
       apiKey,
-      baseUrl: flags.baseUrl,
+      baseUrl: resolvedBaseUrl,
       query,
       limit,
       timeoutMs,
@@ -26,7 +27,6 @@ export async function runDiscover(query, flags) {
 
     // Store richer session data for index resolution
     const tools = result.results ?? [];
-    const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
     writeSession({
       discoveryId: result.search_id,
       query,

package/src/commands/doctor.mjs

@@ -30,7 +30,7 @@ export async function runDoctor(flags) {
     // Test connectivity
     process.stderr.write(`  \u2026 Testing API connectivity...\r`);
     try {
-      await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
+      await discoverTools({ apiKey, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
       console.log(`  ${green("\u2713")} API connectivity OK                `);
     } catch (err) {
       console.log(`  ${red("\u2718")} API connectivity failed: ${err.message}  `);

package/src/commands/interactive.mjs

@@ -14,8 +14,7 @@ import { createSpinner } from "../output/spinner.mjs";
 
 export async function runInteractive(flags) {
   const apiKey = resolveApiKey(flags.apiKey);
-  const baseUrl = flags.baseUrl;
-  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: baseUrl, apiKey });
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const discoverTimeout = (parseInt(flags.timeout, 10) || 30) * 1000;
   const callTimeout = (parseInt(flags.timeout, 10) || 60) * 1000;
@@ -58,7 +57,7 @@ export async function runInteractive(flags) {
           const query = rest.join(" ");
           if (!query) { console.log("  Usage: discover <query>"); break; }
           const sp = createSpinner("Discovering...");
-          const result = await discoverTools({ apiKey, baseUrl, query, limit, timeoutMs: discoverTimeout });
+          const result = await discoverTools({ apiKey, baseUrl: resolvedBaseUrl, query, limit, timeoutMs: discoverTimeout });
           sp.stop();
           state.discoveryId = result.search_id;
           state.results = (result.results ?? []).map((t, i) => ({
@@ -73,7 +72,7 @@ export async function runInteractive(flags) {
           const toolId = resolveId(rest[0], state);
           if (!toolId) { console.log("  Usage: inspect <index|tool_id>"); break; }
           const sp2 = createSpinner("Inspecting...");
-          const result = await inspectToolsByIds({ apiKey, baseUrl, toolIds: [toolId], discoveryId: state.discoveryId, timeoutMs: discoverTimeout });
+          const result = await inspectToolsByIds({ apiKey, baseUrl: resolvedBaseUrl, toolIds: [toolId], discoveryId: state.discoveryId, timeoutMs: discoverTimeout });
           sp2.stop();
           console.log(formatInspectResult(result));
           break;
@@ -85,7 +84,7 @@ export async function runInteractive(flags) {
           const paramsStr = rest.slice(1).join(" ") || "{}";
           const parameters = resolveParams(paramsStr);
           const sp3 = createSpinner("Calling...");
-          const result = await callTool({ apiKey, baseUrl, toolId, discoveryId: state.discoveryId, parameters, timeoutMs: callTimeout });
+          const result = await callTool({ apiKey, baseUrl: resolvedBaseUrl, toolId, discoveryId: state.discoveryId, parameters, timeoutMs: callTimeout });
           sp3.stop();
           console.log(formatCallResult(result));
           if (result.success) {

package/src/commands/ledger.mjs

@@ -0,0 +1,186 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { getCreditsLedger, 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,
+  buildLedgerQuery,
+  buildLedgerSummary,
+  buildLedgerSummaryFromServer,
+  chooseBucket,
+  clampLimit,
+  extractItems,
+  extractTotal,
+  formatExportMetadata,
+  formatLedgerRows,
+  formatLedgerSummary,
+  matchesLedgerFilters,
+  pickLedgerRow,
+  resolveDateRange,
+  resolveMode,
+  writeJsonlExport,
+} from "../output/audit.mjs";
+
+export async function runLedger(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 credits ledger...");
+
+  try {
+    if (mode === "search") {
+      const { rows, total, partial } = await collectLedgerRows({
+        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(pickLedgerRow),
+      };
+      if (flags.json) outputJson(payload);
+      else console.log(formatLedgerRows(rows, { total, partial }));
+      return;
+    }
+
+    if (mode === "export_file") {
+      const { rows, total, partial } = await collectLedgerRows({
+        apiKey,
+        flags,
+        timeoutMs,
+        limit: MAX_EXPORT_ROWS,
+        maxRows: MAX_EXPORT_ROWS,
+        stopWhenLimitReached: false,
+      });
+      spinner.stop();
+      const metadata = writeJsonlExport("credits_ledger", rows, {
+        start_date: startDate,
+        end_date: endDate,
+        matched_records: total,
+        truncated: partial,
+        filters: ledgerFilters(flags),
+      });
+      if (flags.json) outputJson(metadata);
+      else console.log(formatExportMetadata(metadata));
+      return;
+    }
+
+    const summaryResponse = unwrapApiResponse(await getCreditsLedger({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query: buildLedgerQuery(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 = buildLedgerSummaryFromServer(summaryResponse.summary, { startDate, endDate, bucket });
+      if (flags.json) {
+        outputJson({
+          mode,
+          summary,
+          scanned_records: rows.length,
+          matched_records: total,
+          truncated: false,
+        });
+      } else {
+        console.log(formatLedgerSummary(summary, { scannedRows: rows.length, total, partial: false }));
+      }
+      return;
+    }
+
+    const { rows, total, partial, scannedRows } = await collectLedgerRows({
+      apiKey,
+      flags,
+      timeoutMs,
+      limit: MAX_SUMMARY_ROWS,
+      maxRows: MAX_SUMMARY_ROWS,
+      stopWhenLimitReached: false,
+    });
+    spinner.stop();
+    const summary = buildLedgerSummary(rows, { startDate, endDate, bucket });
+    if (flags.json) {
+      outputJson({
+        mode,
+        summary,
+        scanned_records: scannedRows,
+        matched_records: total,
+        truncated: partial,
+      });
+    } else {
+      console.log(formatLedgerSummary(summary, { scannedRows, total, partial }));
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}
+
+async function collectLedgerRows({ 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 = buildLedgerQuery(flags, { page, pageSize: Math.min(DEFAULT_PAGE_SIZE, maxRows - scannedRows) });
+    const response = unwrapApiResponse(await getCreditsLedger({
+      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 (!matchesLedgerFilters(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 ledgerFilters(flags) {
+  return {
+    entry_type: flags.entryType,
+    direction: flags.direction,
+    min_credits: flags.minCredits,
+    max_credits: flags.maxCredits,
+  };
+}