@aisa-one/cli 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.6] — 2026-09-30
+
+### Fixed
+
+- Open the browser on Windows. `start` is built into cmd.exe, so running it
+  directly failed with ENOENT and the error was swallowed: `aisa login`,
+  `aisa connect` and `aisa topup` never opened a page, and sign-in waited
+  for an approval that could not arrive. The browser now opens through
+  cmd.exe, with `&` and other special characters escaped so the whole URL
+  gets through.
+
+## [0.6.5] — 2026-09-30
+
+### Added
+
+- Implement `aisa usage` against the live `GET /v1/usage` endpoint: one row per
+  day with requests, failures, input and output tokens, and charged USD, plus a
+  total. `--days` (1–31, default 7), `--scope key|account`, `--limit N`, and
+  `--json`.
+
+### Fixed
+
+- Reject `aisa topup <amount>` below the console's $10 minimum before opening
+  the browser (exit 1, no URL), and mention the minimum in `topup` output.
+- Send `start_time` and `end_time` as a coherent pair so `--days 31` cannot race
+  the gateway clock past its 31-day cap.
+- Label usage buckets with UTC calendar days; the gateway buckets at UTC
+  boundaries, so local-timezone labels were off by one day in UTC-negative zones.
+
 ## [0.6.4] — 2026-09-30
 
 ### Fixed

package/README.md

@@ -200,18 +200,23 @@ Streaming is on by default; pass `--no-stream` to disable it.
 ```bash
 aisa balance                        # wallet and API key credit balance
 aisa balance --json
+aisa usage                          # last 7 days for this API key
+aisa usage --days 31 --scope account
+aisa usage --limit 3                # table shows only the latest 3 days
+aisa usage --json
 aisa topup                          # open the console billing page to add credit
-aisa topup 20                       # same, deep-linked to $20
+aisa topup 20                       # same, deep-linked to $20 (minimum $10)
 ```
 
+`aisa usage` calls `GET /v1/usage` and prints one row per day — requests,
+failed requests, input and output tokens, and charged USD — plus a total.
+`--days` accepts 1–31 and defaults to 7. `--scope key` (the default) is the
+current credential; `--scope account` sums the whole account. `--json` prints
+the gateway response. `--limit` shortens the table only.
+
 Payment always finishes in the browser: card details belong to Stripe's hosted
 page, not to us, and a bank's 3-D Secure step needs one. `topup` opens the
-right page; `--no-open` prints the URL instead.
-
-`aisa usage` is not available yet — the gateway does not serve
-`GET /v1/credits/usage` (it 404s, while `/v1/credits/balance` on the same route
-group works). Use the [console](https://console.aisa.one/logs) for usage history
-in the meantime.
+right page; `--no-open` prints the URL instead. The minimum top-up is $10.
 
 ## Skills
 

package/dist/commands/account.d.ts

@@ -2,6 +2,15 @@ export declare function formatMicrosUSD(micros: number | string | bigint): strin
 export declare function balanceAction(options?: {
     json?: boolean;
 }): Promise<void>;
+/**
+ * Minimum top-up in US dollars.
+ *
+ * Source of truth: the console constant BILLING_MIN_TOPUP_MICROS_USD
+ * (production is $10). `/api/billing/config` needs a console session, which
+ * this CLI's OAuth token cannot obtain, so the floor is fixed here instead
+ * of being read at runtime.
+ */
+export declare const MIN_TOPUP_USD = 10;
 /**
  * `aisa topup [amount]` — open the console's billing page to add credit.
  *
@@ -19,7 +28,72 @@ export declare function balanceAction(options?: {
 export declare function topupAction(amount: string | undefined, options?: {
     open?: boolean;
 }): void;
-export declare function usageAction(_options: {
+/** Gateway caps GET /v1/usage at 31 days; buckets are fixed at one day. */
+export declare const USAGE_MAX_WINDOW_DAYS = 31;
+export declare const USAGE_DEFAULT_DAYS = 7;
+export interface UsageMetrics {
+    requests: number;
+    failed_requests: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    usage_value_micros_usd: number;
+    charged_micros_usd: number;
+}
+export interface UsageBucket extends UsageMetrics {
+    start_time: number;
+    end_time: number;
+}
+export interface UsageResponse {
+    scope: string;
+    currency: string;
+    start_time: number;
+    end_time: number;
+    bucket_width: string;
+    totals: UsageMetrics;
+    buckets: UsageBucket[];
+}
+export interface UsageQuery {
+    start_time: string;
+    /** Sent alongside start_time so the window is exactly --days wide even if
+     *  the gateway's clock runs ahead of ours; a server-filled end_time could
+     *  push a 31-day request past the gateway's own cap. */
+    end_time: string;
+    scope: "key" | "account";
+}
+export interface ParsedUsageOptions {
+    query: UsageQuery;
+    /** Omitted means the table shows every daily bucket in the window. */
+    limit?: number;
+}
+export interface UsageActionOptions {
+    days?: string;
+    scope?: string;
     limit?: string;
+    json?: boolean;
+}
+/**
+ * `aisa usage` reads GET /v1/usage.
+ *
+ * start_time and end_time are both sent as a coherent pair so the window is
+ * exactly --days wide even when the gateway's clock runs ahead of ours. The
+ * window cannot exceed 31 days.
+ * scope=key is this credential; scope=account sums the whole account, which
+ * an OAuth token is allowed to request. --limit trims the table to the latest
+ * N days. --json prints the gateway body unchanged.
+ */
+export declare function parseUsageOptions(options: {
     days?: string;
-}): Promise<void>;
+    scope?: string;
+    limit?: string;
+}, nowSeconds: number): ParsedUsageOptions;
+/** UTC calendar day (YYYY-MM-DD) for a bucket's start_time. The gateway
+ *  buckets at UTC day boundaries, so a local-timezone label would show the
+ *  previous calendar day for every UTC-midnight bucket in UTC-negative zones. */
+export declare function formatUsageDate(unixSeconds: number): string;
+/** Chronological order, then the latest `limit` buckets. A missing limit keeps
+ *  the whole window. */
+export declare function selectRecentBuckets(buckets: readonly UsageBucket[], limit?: number): UsageBucket[];
+export declare function renderUsageReport(buckets: readonly UsageBucket[]): string;
+export declare function usageAction(options?: UsageActionOptions): Promise<void>;

package/dist/commands/account.js

@@ -1,8 +1,9 @@
-import { run } from "../utils/exec.js";
+import { openBrowser } from "../utils/browser.js";
 import chalk from "chalk";
 import { requireAccessToken } from "../config.js";
 import { apiRequest } from "../api.js";
-import { formatJson, hint, info, error } from "../utils/display.js";
+import { usageError } from "../cli-error.js";
+import { formatJson, hint, info, error, table } from "../utils/display.js";
 import { CONSOLE_BILLING_URL } from "../constants.js";
 export function formatMicrosUSD(micros) {
     const value = typeof micros === "bigint" ? micros : BigInt(micros);
@@ -42,6 +43,15 @@ export async function balanceAction(options = {}) {
         hint("Out of credit — run 'aisa topup' to add some");
     }
 }
+/**
+ * Minimum top-up in US dollars.
+ *
+ * Source of truth: the console constant BILLING_MIN_TOPUP_MICROS_USD
+ * (production is $10). `/api/billing/config` needs a console session, which
+ * this CLI's OAuth token cannot obtain, so the floor is fixed here instead
+ * of being read at runtime.
+ */
+export const MIN_TOPUP_USD = 10;
 /**
  * `aisa topup [amount]` — open the console's billing page to add credit.
  *
@@ -66,23 +76,166 @@ export function topupAction(amount, options = {}) {
             process.exitCode = 1;
             return;
         }
+        if (value < MIN_TOPUP_USD) {
+            error(`Minimum top-up is $${MIN_TOPUP_USD} (got ${amount}).`);
+            hint(`The minimum top-up is $${MIN_TOPUP_USD}, e.g. 'aisa topup ${MIN_TOPUP_USD}'.`);
+            process.exitCode = 1;
+            return;
+        }
         url = `${CONSOLE_BILLING_URL}?amount=${value}`;
         info(`Opening the billing page to add ${formatMicrosUSD(BigInt(Math.round(value * 1_000_000)))}`);
     }
     else {
         info("Opening the billing page — choose an amount there");
+        hint(`The minimum top-up is $${MIN_TOPUP_USD}`);
     }
     console.log(`  ${chalk.cyan(url)}`);
     if (options.open === false)
         return;
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
+    openBrowser(url);
     hint("Credit lands in your account as soon as the payment completes");
 }
-export async function usageAction(_options) {
-    await requireAccessToken();
-    // The gateway does not serve /v1/credits/usage yet — it 404s in production
-    // even though /v1/credits/balance on the same route group works.
-    console.log(chalk.yellow("  Usage API is not yet available on the gateway."));
-    hint("View usage history at https://console.aisa.one/logs");
+/** Gateway caps GET /v1/usage at 31 days; buckets are fixed at one day. */
+export const USAGE_MAX_WINDOW_DAYS = 31;
+export const USAGE_DEFAULT_DAYS = 7;
+const USAGE_DAY_SECONDS = 86_400;
+const USAGE_WINDOW_ERROR = "The usage window is at most 31 days. Pass --days as an integer from 1 to 31.";
+/**
+ * `aisa usage` reads GET /v1/usage.
+ *
+ * start_time and end_time are both sent as a coherent pair so the window is
+ * exactly --days wide even when the gateway's clock runs ahead of ours. The
+ * window cannot exceed 31 days.
+ * scope=key is this credential; scope=account sums the whole account, which
+ * an OAuth token is allowed to request. --limit trims the table to the latest
+ * N days. --json prints the gateway body unchanged.
+ */
+export function parseUsageOptions(options, nowSeconds) {
+    const days = parseUsageDays(options.days);
+    const scope = parseUsageScope(options.scope);
+    const limit = parseUsageLimit(options.limit);
+    if (!Number.isFinite(nowSeconds)) {
+        throw usageError("Usage start_time must be a positive Unix timestamp in seconds.");
+    }
+    const end = Math.floor(nowSeconds);
+    const start = end - days * USAGE_DAY_SECONDS;
+    if (start <= 0) {
+        throw usageError("Usage start_time must be a positive Unix timestamp in seconds.");
+    }
+    return limit === undefined
+        ? { query: { start_time: String(start), end_time: String(end), scope } }
+        : { query: { start_time: String(start), end_time: String(end), scope }, limit };
+}
+function parseUsageDays(raw) {
+    const text = raw === undefined || raw.trim() === "" ? String(USAGE_DEFAULT_DAYS) : raw.trim();
+    if (!/^\d+$/.test(text))
+        throw usageError(USAGE_WINDOW_ERROR);
+    const days = Number(text);
+    if (!Number.isSafeInteger(days) || days < 1 || days > USAGE_MAX_WINDOW_DAYS) {
+        throw usageError(USAGE_WINDOW_ERROR);
+    }
+    return days;
+}
+function parseUsageScope(raw) {
+    const text = raw === undefined || raw.trim() === "" ? "key" : raw.trim();
+    if (text !== "key" && text !== "account") {
+        throw usageError('Pass --scope as "key" or "account".');
+    }
+    return text;
+}
+function parseUsageLimit(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    if (!/^\d+$/.test(raw.trim()))
+        throw usageError("--limit must be a positive integer.");
+    const limit = Number(raw.trim());
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw usageError("--limit must be a positive integer.");
+    }
+    return limit;
+}
+/** UTC calendar day (YYYY-MM-DD) for a bucket's start_time. The gateway
+ *  buckets at UTC day boundaries, so a local-timezone label would show the
+ *  previous calendar day for every UTC-midnight bucket in UTC-negative zones. */
+export function formatUsageDate(unixSeconds) {
+    if (!Number.isFinite(unixSeconds))
+        return "";
+    const date = new Date(unixSeconds * 1000);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return date.toISOString().slice(0, 10);
+}
+/** Chronological order, then the latest `limit` buckets. A missing limit keeps
+ *  the whole window. */
+export function selectRecentBuckets(buckets, limit) {
+    const sorted = [...buckets].sort((a, b) => Number(a.start_time) - Number(b.start_time));
+    if (limit === undefined)
+        return sorted;
+    return sorted.slice(-limit);
+}
+export function renderUsageReport(buckets) {
+    if (buckets.length === 0)
+        return "  No usage in this window.";
+    const headers = ["Date", "Requests", "Failed", "Input tokens", "Output tokens", "Charged"];
+    const rows = buckets.map((bucket) => [
+        formatUsageDate(Number(bucket.start_time)),
+        formatCount(bucket.requests),
+        formatCount(bucket.failed_requests),
+        formatCount(bucket.input_tokens),
+        formatCount(bucket.output_tokens),
+        formatMicrosUSD(asMicros(bucket.charged_micros_usd)),
+    ]);
+    rows.push([
+        "Total",
+        formatCount(sumCount(buckets, "requests")),
+        formatCount(sumCount(buckets, "failed_requests")),
+        formatCount(sumCount(buckets, "input_tokens")),
+        formatCount(sumCount(buckets, "output_tokens")),
+        formatMicrosUSD(sumMicros(buckets)),
+    ]);
+    return table(headers, rows);
+}
+function formatCount(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n))
+        return "0";
+    return String(Math.trunc(n));
+}
+function sumCount(buckets, key) {
+    return buckets.reduce((sum, bucket) => {
+        const n = Number(bucket[key]);
+        return sum + (Number.isFinite(n) ? Math.trunc(n) : 0);
+    }, 0);
+}
+function asMicros(value) {
+    if (typeof value === "bigint")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return BigInt(Math.trunc(value));
+    if (typeof value === "string" && /^-?\d+$/.test(value.trim()))
+        return BigInt(value.trim());
+    return 0n;
+}
+function sumMicros(buckets) {
+    return buckets.reduce((sum, bucket) => sum + asMicros(bucket.charged_micros_usd), 0n);
+}
+export async function usageAction(options = {}) {
+    const parsed = parseUsageOptions(options, Math.floor(Date.now() / 1000));
+    const token = await requireAccessToken();
+    const res = await apiRequest(token, "usage", {
+        query: {
+            start_time: parsed.query.start_time,
+            end_time: parsed.query.end_time,
+            scope: parsed.query.scope,
+        },
+    });
+    if (!res.success || !res.data) {
+        throw new Error(res.error || "Failed to fetch usage");
+    }
+    if (options.json) {
+        console.log(formatJson(res.data));
+        return;
+    }
+    const buckets = Array.isArray(res.data.buckets) ? res.data.buckets : [];
+    console.log(renderUsageReport(selectRecentBuckets(buckets, parsed.limit)));
 }

package/dist/commands/connect.js

@@ -14,7 +14,7 @@ import { INSTALLERS, installAgent, isInstalled, supported } from "./install.js";
 import { writeCodexLLM, writeClaudeCodeLLM, writeOpencodeLLM, writeCodexAisaProfile, writeOpencodeAisaBackup, defaultModelsFor, patchCodexMCPAuth, DEFAULT_MODELS, } from "./llm-config.js";
 import { writeClaudeAisaSettings, installWrappers } from "./wrappers.js";
 import { signInAndStoreTokens } from "./oauth-login.js";
-import { canOpenBrowser } from "../utils/browser.js";
+import { canOpenBrowser, openBrowser } from "../utils/browser.js";
 import { vscodeDetected, vscodeUserDir, writeVSCodeLLM, writeVSCodeMCP, installVSCodeExtension, launchVSCode, VSCODE_MODELS } from "./vscode.js";
 import { formatMicrosUSD } from "./account.js";
 import { apiRequest } from "../api.js";
@@ -1812,10 +1812,6 @@ function launchCursor(dir) {
 function withBrowserEarly() {
     return canOpenBrowser();
 }
-function openBrowser(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
-}
 /**
  * Where a live run leaves its address, so a second `aisa connect` can offer
  * the first one's page instead of starting a rival server. Ephemeral by

package/dist/commands/oauth-login.js

@@ -1,5 +1,4 @@
 import chalk from "chalk";
-import { run } from "../utils/exec.js";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline/promises";
@@ -7,7 +6,7 @@ import { error, hint, info, success } from "../utils/display.js";
 import { replaceTokens, tokenExpiresAt } from "../config.js";
 import { maskKey } from "../config.js";
 import { httpFetch } from "../utils/http.js";
-import { canOpenBrowser } from "../utils/browser.js";
+import { canOpenBrowser, openBrowser } from "../utils/browser.js";
 import { SIGNIN, t } from "./flow.js";
 import { renderSignInPage } from "./signin-page.js";
 import { handOverSignInPage, SIGNIN_PAGE_TTL_MS } from "./serve-signin.js";
@@ -220,10 +219,6 @@ async function waitForPaste(expectedState, lang) {
     /* c8 ignore next */
     throw new Error(t(SIGNIN.badPaste, lang));
 }
-function openBrowser(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
-}
 export async function signInAndStoreTokens(options = {}) {
     const lang = options.lang ?? "en";
     // Unset means "work it out": a server has no browser to open and waiting

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.6.4";
+export declare const VERSION = "0.6.6";
 /** Default for chat when no model is configured or supplied explicitly. */
 export declare const DEFAULT_CHAT_MODEL = "deepseek-v4.1-flash";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.6.4";
+export const VERSION = "0.6.6";
 /** Default for chat when no model is configured or supplied explicitly. */
 export const DEFAULT_CHAT_MODEL = "deepseek-v4.1-flash";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */

package/dist/index.js

@@ -90,7 +90,7 @@ program
 // ── Account ──
 program
     .command("topup [amount]")
-    .description("Add credit — opens the console billing page (amount in USD, optional)")
+    .description("Add credit — opens the console billing page (optional USD amount, minimum $10)")
     .option("--no-open", "Print the URL instead of opening the browser")
     .action(topupAction);
 program
@@ -100,9 +100,11 @@ program
     .action(wrap(balanceAction));
 program
     .command("usage")
-    .description("Show usage history (awaiting gateway support)")
-    .option("--limit <n>", "Max records")
-    .option("--days <n>", "Lookback days")
+    .description("Show daily API usage")
+    .option("--days <n>", "Lookback window in days (1-31)", "7")
+    .option("--scope <scope>", "key or account", "key")
+    .option("--limit <n>", "Show only the most recent N daily buckets")
+    .option("--json", "Output the raw JSON response")
     .action(wrap(usageAction));
 // ── Tool Router (same operations as MCP) ──
 program

package/dist/utils/browser.d.ts

@@ -17,3 +17,29 @@
  * for a click nobody will ever make.
  */
 export declare function canOpenBrowser(): boolean;
+/**
+ * The command that hands a URL to the default browser on this platform.
+ *
+ * Windows is the one that needs care. Its opener, `start`, is not a program
+ * but a command built into cmd.exe, so running it directly fails with
+ * ENOENT, and the failure used to be swallowed: the browser never opened,
+ * and `aisa login` sat waiting for an approval that could not arrive.
+ * Going through cmd.exe fixes that, with two details:
+ *
+ *   · `start` reads its first quoted argument as a window title, so an empty
+ *     title goes first; otherwise a quoted URL would become the title.
+ *   · cmd.exe reads `&` in a query string as "run the next command", which
+ *     would cut the URL at its second parameter. Its special characters are
+ *     escaped with `^` so the whole URL reaches the browser.
+ */
+export declare function browserCommand(url: string, platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+};
+/**
+ * Open a URL in the default browser, without waiting and without failing.
+ *
+ * Every caller prints the URL as well, so a browser that does not open
+ * costs the user a click, not the command.
+ */
+export declare function openBrowser(url: string): void;

package/dist/utils/browser.js

@@ -1,3 +1,4 @@
+import { run } from "./exec.js";
 /**
  * Can this machine put a page in front of the person using it?
  *
@@ -29,3 +30,36 @@ export function canOpenBrowser() {
         return true;
     return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
 }
+/**
+ * The command that hands a URL to the default browser on this platform.
+ *
+ * Windows is the one that needs care. Its opener, `start`, is not a program
+ * but a command built into cmd.exe, so running it directly fails with
+ * ENOENT, and the failure used to be swallowed: the browser never opened,
+ * and `aisa login` sat waiting for an approval that could not arrive.
+ * Going through cmd.exe fixes that, with two details:
+ *
+ *   · `start` reads its first quoted argument as a window title, so an empty
+ *     title goes first; otherwise a quoted URL would become the title.
+ *   · cmd.exe reads `&` in a query string as "run the next command", which
+ *     would cut the URL at its second parameter. Its special characters are
+ *     escaped with `^` so the whole URL reaches the browser.
+ */
+export function browserCommand(url, platform = process.platform) {
+    if (platform === "darwin")
+        return { file: "open", args: [url] };
+    if (platform === "win32") {
+        return { file: "cmd", args: ["/c", "start", "", url.replace(/[\^&|<>()]/g, "^$&")] };
+    }
+    return { file: "xdg-open", args: [url] };
+}
+/**
+ * Open a URL in the default browser, without waiting and without failing.
+ *
+ * Every caller prints the URL as well, so a browser that does not open
+ * costs the user a click, not the command.
+ */
+export function openBrowser(url) {
+    const { file, args } = browserCommand(url);
+    void run(file, args, { timeout: 30_000 }).catch(() => { });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "CLI for the AIsa unified AI infrastructure platform - one API key for 80+ LLMs and 900+ endpoints across finance, search, social, and video APIs",
   "type": "module",
   "main": "dist/index.js",