@aisa-one/cli 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -2,7 +2,8 @@ import { run } from "../utils/exec.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,11 +76,18 @@ 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)
@@ -79,10 +96,147 @@ export function topupAction(amount, options = {}) {
     void run(cmd, [url], { timeout: 30_000 }).catch(() => { });
     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/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.6.4";
+export declare const VERSION = "0.6.5";
 /** 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.5";
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "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",