@aisa-one/cli 0.2.2 → 0.2.3

package/dist/api.d.ts

@@ -1,4 +1,30 @@
-import type { ApiResponse } from "./types.js";
+import type { ApiResponse, CostInfo } from "./types.js";
+export interface Bases {
+    /** LLM gateway: chat, models, credits, video. */
+    llm: string;
+    /** Integration APIs: every provider slug. */
+    domain: string;
+    /** Unauthenticated catalog and pricing endpoints. */
+    info: string;
+}
+/**
+ * Derive every base path from one configured root.
+ *
+ * `baseUrl` has shipped with a default of `https://api.aisa.one/v1`, so it is
+ * already persisted with the `/v1` suffix in every existing user's config —
+ * changing the schema default would not rewrite it. Strip whichever suffix is
+ * present and rebuild, so both the historical value and a bare root work.
+ */
+export declare function resolveBases(): Bases;
+/**
+ * Read the gateway's billing headers off a response.
+ *
+ * Returns undefined when none are present — which is the common case, since
+ * only metered integration routes report an amount. Values are passed through
+ * as strings: they are fixed-point decimals produced server-side, and parsing
+ * them into floats would only lose precision on the way to being printed.
+ */
+export declare function parseCost(res: Response): CostInfo | undefined;
 export interface RequestOptions {
     method?: "GET" | "POST" | "PUT" | "DELETE";
     query?: Record<string, string>;
@@ -10,3 +36,22 @@ export interface RequestOptions {
 }
 export declare function apiRequest<T = unknown>(apiKey: string, endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>>;
 export declare function apiRequestRaw(apiKey: string, endpoint: string, options?: RequestOptions): Promise<Response>;
+/**
+ * Cache namespace for data served by the configured gateway. Catalog, model
+ * and coin-list caches must be keyed by the host they came from: a fixed key
+ * would keep serving one server's catalog for hours after `config set baseUrl`
+ * switches to another.
+ */
+export declare function cacheScope(): string;
+/**
+ * Request an unauthenticated endpoint under /info or /pricing. Browsing the
+ * catalog does not require an API key, and demanding one would turn discovery
+ * into a signup wall.
+ */
+export declare function publicRequest<T = unknown>(path: string, options?: {
+    etag?: string;
+}): Promise<{
+    status: number;
+    data?: T;
+    etag?: string;
+}>;

package/dist/api.js

@@ -1,12 +1,49 @@
-import { CLI_BASE_URL, APIS_BASE_URL } from "./constants.js";
+import { BASE_URL } from "./constants.js";
 import { getConfig } from "./config.js";
-function getBaseUrl() {
-    const custom = getConfig("baseUrl");
-    return custom || CLI_BASE_URL;
+/**
+ * Derive every base path from one configured root.
+ *
+ * `baseUrl` has shipped with a default of `https://api.aisa.one/v1`, so it is
+ * already persisted with the `/v1` suffix in every existing user's config —
+ * changing the schema default would not rewrite it. Strip whichever suffix is
+ * present and rebuild, so both the historical value and a bare root work.
+ */
+export function resolveBases() {
+    const configured = getConfig("baseUrl") || BASE_URL;
+    const root = configured
+        .trim()
+        .replace(/\/+$/, "")
+        .replace(/\/apis\/v1$/, "")
+        .replace(/\/v1$/, "")
+        .replace(/\/+$/, "");
+    return { llm: `${root}/v1`, domain: `${root}/apis/v1`, info: root };
+}
+/**
+ * Read the gateway's billing headers off a response.
+ *
+ * Returns undefined when none are present — which is the common case, since
+ * only metered integration routes report an amount. Values are passed through
+ * as strings: they are fixed-point decimals produced server-side, and parsing
+ * them into floats would only lose precision on the way to being printed.
+ */
+export function parseCost(res) {
+    const cost = {
+        priceUsd: res.headers.get("x-aisa-price-usd") || undefined,
+        pricingStrategy: res.headers.get("x-aisa-pricing-strategy") || undefined,
+        pricingVersion: res.headers.get("x-aisa-pricing-version") || undefined,
+        creditModel: res.headers.get("x-aisa-credit-model") || undefined,
+        estimatedCredits: res.headers.get("x-aisa-estimated-credits") || undefined,
+        accountedCredits: res.headers.get("x-aisa-accounted-credits") || undefined,
+        requestMultiplier: res.headers.get("x-aisa-request-multiplier") || undefined,
+        priceKey: res.headers.get("x-aisa-price-key") || undefined,
+        requestId: res.headers.get("x-request-id") || undefined,
+    };
+    return Object.values(cost).some((v) => v !== undefined) ? cost : undefined;
 }
 export async function apiRequest(apiKey, endpoint, options = {}) {
     const { method = "GET", query, body, headers: extraHeaders, domain } = options;
-    const baseUrl = domain ? APIS_BASE_URL : getBaseUrl();
+    const bases = resolveBases();
+    const baseUrl = domain ? bases.domain : bases.llm;
     let url = `${baseUrl}/${endpoint}`;
     if (query) {
         const params = new URLSearchParams(query);
@@ -33,14 +70,15 @@ export async function apiRequest(apiKey, endpoint, options = {}) {
         catch {
             errorMsg = text;
         }
-        return { success: false, error: `${res.status}: ${errorMsg}` };
+        return { success: false, error: `${res.status}: ${errorMsg}`, cost: parseCost(res) };
     }
     const data = (await res.json());
-    return { success: true, data };
+    return { success: true, data, cost: parseCost(res) };
 }
 export async function apiRequestRaw(apiKey, endpoint, options = {}) {
     const { method = "GET", query, body, headers: extraHeaders, domain } = options;
-    const baseUrl = domain ? APIS_BASE_URL : getBaseUrl();
+    const bases = resolveBases();
+    const baseUrl = domain ? bases.domain : bases.llm;
     let url = `${baseUrl}/${endpoint}`;
     if (query) {
         const params = new URLSearchParams(query);
@@ -58,3 +96,34 @@ export async function apiRequestRaw(apiKey, endpoint, options = {}) {
         body: body ? JSON.stringify(body) : undefined,
     });
 }
+/**
+ * Cache namespace for data served by the configured gateway. Catalog, model
+ * and coin-list caches must be keyed by the host they came from: a fixed key
+ * would keep serving one server's catalog for hours after `config set baseUrl`
+ * switches to another.
+ */
+export function cacheScope() {
+    return resolveBases()
+        .info.replace(/^https?:\/\//, "")
+        .replace(/[^\w.-]/g, "_");
+}
+/**
+ * Request an unauthenticated endpoint under /info or /pricing. Browsing the
+ * catalog does not require an API key, and demanding one would turn discovery
+ * into a signup wall.
+ */
+export async function publicRequest(path, options = {}) {
+    const headers = { "x-aisa-source": "cli" };
+    if (options.etag)
+        headers["If-None-Match"] = options.etag;
+    const res = await fetch(`${resolveBases().info}/${path.replace(/^\/+/, "")}`, { headers });
+    if (res.status === 304)
+        return { status: 304 };
+    if (!res.ok)
+        return { status: res.status };
+    return {
+        status: res.status,
+        data: (await res.json()),
+        etag: res.headers.get("etag") || undefined,
+    };
+}

package/dist/cache.d.ts

@@ -0,0 +1,18 @@
+export interface CacheHit<T> {
+    data: T;
+    etag?: string;
+    /** False when the entry is past its TTL but still usable as a fallback. */
+    fresh: boolean;
+}
+export declare function cacheDir(): string;
+/**
+ * Read a cached entry. Returns stale entries too (with `fresh: false`) so
+ * callers can revalidate with an ETag or fall back to them when offline.
+ * A corrupt or unreadable file is treated as a miss, never an error.
+ */
+export declare function readCache<T>(key: string): CacheHit<T> | undefined;
+/** Write an entry. Cache failures are never fatal — a full disk shouldn't break a command. */
+export declare function writeCache<T>(key: string, data: T, ttlMs: number, etag?: string): void;
+/** Refresh an existing entry's timestamp, for HTTP 304 responses. */
+export declare function touchCache(key: string, ttlMs: number): void;
+export declare function clearCache(): number;

package/dist/cache.js

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+export function cacheDir() {
+    return process.env.AISA_CACHE_DIR || join(homedir(), ".aisa", "cache");
+}
+function cachePath(key) {
+    return join(cacheDir(), key);
+}
+/**
+ * Read a cached entry. Returns stale entries too (with `fresh: false`) so
+ * callers can revalidate with an ETag or fall back to them when offline.
+ * A corrupt or unreadable file is treated as a miss, never an error.
+ */
+export function readCache(key) {
+    try {
+        const raw = readFileSync(cachePath(key), "utf-8");
+        const env = JSON.parse(raw);
+        if (!env || typeof env !== "object" || typeof env.fetchedAt !== "number") {
+            return undefined;
+        }
+        return {
+            data: env.data,
+            etag: env.etag,
+            fresh: Date.now() - env.fetchedAt < env.ttlMs,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write an entry. Cache failures are never fatal — a full disk shouldn't break a command. */
+export function writeCache(key, data, ttlMs, etag) {
+    try {
+        const path = cachePath(key);
+        mkdirSync(dirname(path), { recursive: true });
+        const env = { fetchedAt: Date.now(), ttlMs, etag, data };
+        writeFileSync(path, JSON.stringify(env), "utf-8");
+    }
+    catch {
+        // ignore
+    }
+}
+/** Refresh an existing entry's timestamp, for HTTP 304 responses. */
+export function touchCache(key, ttlMs) {
+    const hit = readCache(key);
+    if (hit)
+        writeCache(key, hit.data, ttlMs, hit.etag);
+}
+export function clearCache() {
+    const dir = cacheDir();
+    if (!existsSync(dir))
+        return 0;
+    const count = countFiles(dir);
+    rmSync(dir, { recursive: true, force: true });
+    return count;
+}
+function countFiles(dir) {
+    let n = 0;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        n += statSync(full).isDirectory() ? countFiles(full) : 1;
+    }
+    return n;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Client for the unauthenticated /info/apis catalog.
+ *
+ * Two properties of the upstream data shape everything here:
+ *  - `endpoint_groups[].name` is an operator-entered label ("Zero", "One",
+ *    "default") with no business meaning, so callers get a flat endpoint list.
+ *  - `endpoints[].method` is hardcoded to GET server-side and must not be
+ *    treated as authoritative.
+ * The provider `id` is also not always the URL slug (provider `brave-search`
+ * serves `/apis/v1/brave/...`), so the runnable slug is derived from the paths.
+ */
+export interface CatalogPricing {
+    type: string;
+    /** Dollars per request, as a float — not micros. */
+    normal: number;
+}
+export interface CatalogProvider {
+    id: string;
+    endpoint_count: number;
+    is_active: boolean;
+    pricing?: CatalogPricing;
+    updated_at?: string;
+}
+export interface CatalogEndpoint {
+    /** Advisory only: the server hardcodes GET. */
+    method: string;
+    /** Full inner URI, e.g. /apis/v1/financial/news. */
+    path: string;
+    name?: string;
+    description?: string;
+    pricing?: CatalogPricing;
+}
+export interface CatalogDetail extends CatalogProvider {
+    endpoint_groups?: Array<{
+        id?: string;
+        name?: string;
+        endpoints: CatalogEndpoint[];
+    }>;
+}
+export interface ProviderHealth {
+    id: string;
+    status: "healthy" | "warning" | "failed" | "not_tested" | string;
+    endpoint_count: number;
+    healthy_count: number;
+    failed_count: number;
+    warning_count: number;
+    not_tested_count: number;
+    checked_at?: string;
+}
+export declare const CATALOG_CONCURRENCY: number;
+export declare function getProviders(options?: {
+    refresh?: boolean;
+}): Promise<CatalogProvider[]>;
+export declare function getProviderDetail(id: string, options?: {
+    refresh?: boolean;
+}): Promise<CatalogDetail>;
+export declare function getHealth(options?: {
+    refresh?: boolean;
+}): Promise<ProviderHealth[]>;
+/** Flatten a provider's groups — the group labels carry no meaning. */
+export declare function flatEndpoints(detail: CatalogDetail): CatalogEndpoint[];
+/** Strip the /apis/v1 prefix: what you'd pass to `aisa run`. */
+export declare function toRunPath(path: string): string;
+/**
+ * The slug an endpoint is actually served under, which is not always the
+ * provider id (provider `brave-search` serves `/apis/v1/brave/...`).
+ */
+export declare function runSlugOf(detail: CatalogDetail): string | undefined;
+export interface EndpointRef {
+    provider: string;
+    endpoint: CatalogEndpoint;
+}
+/**
+ * Load every provider's endpoints. Cold this is ~29 requests and several
+ * hundred KB, so it runs through a bounded pool with progress reporting; warm
+ * it is entirely local.
+ */
+export declare function getAllEndpoints(options: {
+    refresh?: boolean;
+    onProgress?: (done: number, total: number) => void;
+}): Promise<{
+    endpoints: EndpointRef[];
+    failed: string[];
+}>;
+/**
+ * Format a per-request price. Real values span $0.000001 to $0.08, so a fixed
+ * number of decimals either rounds the cheap endpoints to $0.00 or pads the
+ * rest with noise — keep two significant digits instead.
+ */
+export declare function formatPrice(usd?: number): string;

package/dist/catalog.js

@@ -0,0 +1,101 @@
+import { publicRequest, cacheScope } from "./api.js";
+import { readCache, writeCache, touchCache } from "./cache.js";
+import { pool } from "./utils/pool.js";
+const CATEGORY_TTL_MS = 6 * 60 * 60 * 1000;
+const DETAIL_TTL_MS = 24 * 60 * 60 * 1000;
+const HEALTH_TTL_MS = 5 * 60 * 1000;
+export const CATALOG_CONCURRENCY = Number(process.env.AISA_CATALOG_CONCURRENCY) || 6;
+/** Fetch with disk caching and ETag revalidation; falls back to stale data offline. */
+async function cachedGet(path, cacheKey, ttlMs, refresh) {
+    const cached = readCache(cacheKey);
+    if (cached?.fresh && !refresh)
+        return cached.data;
+    let res;
+    try {
+        res = await publicRequest(path, { etag: refresh ? undefined : cached?.etag });
+    }
+    catch (err) {
+        if (cached)
+            return cached.data;
+        throw err;
+    }
+    if (res.status === 304 && cached) {
+        touchCache(cacheKey, ttlMs);
+        return cached.data;
+    }
+    if (!res.data) {
+        if (cached)
+            return cached.data;
+        throw new Error(`Catalog request failed: ${path} returned ${res.status}`);
+    }
+    writeCache(cacheKey, res.data, ttlMs, res.etag);
+    return res.data;
+}
+export async function getProviders(options = {}) {
+    const data = await cachedGet("info/apis/category", `catalog/${cacheScope()}/category.json`, CATEGORY_TTL_MS, options.refresh);
+    return data.apis || [];
+}
+export async function getProviderDetail(id, options = {}) {
+    const data = await cachedGet(`info/apis/${encodeURIComponent(id)}`, `catalog/${cacheScope()}/${id.replace(/[^\w.-]/g, "_")}.json`, DETAIL_TTL_MS, options.refresh);
+    if (!data.api)
+        throw new Error(`Unknown API "${id}"`);
+    return data.api;
+}
+export async function getHealth(options = {}) {
+    const data = await cachedGet("info/apis/health", `catalog/${cacheScope()}/health.json`, HEALTH_TTL_MS, options.refresh);
+    return data.apis || [];
+}
+/** Flatten a provider's groups — the group labels carry no meaning. */
+export function flatEndpoints(detail) {
+    return (detail.endpoint_groups || [])
+        .flatMap((g) => g.endpoints || [])
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+/** Strip the /apis/v1 prefix: what you'd pass to `aisa run`. */
+export function toRunPath(path) {
+    return path.replace(/^\/apis\/v1\//, "").replace(/^\/+/, "");
+}
+/**
+ * The slug an endpoint is actually served under, which is not always the
+ * provider id (provider `brave-search` serves `/apis/v1/brave/...`).
+ */
+export function runSlugOf(detail) {
+    const first = flatEndpoints(detail)[0];
+    return first ? toRunPath(first.path).split("/")[0] : undefined;
+}
+/**
+ * Load every provider's endpoints. Cold this is ~29 requests and several
+ * hundred KB, so it runs through a bounded pool with progress reporting; warm
+ * it is entirely local.
+ */
+export async function getAllEndpoints(options) {
+    const providers = await getProviders({ refresh: options.refresh });
+    const details = await pool(providers.map((p) => () => getProviderDetail(p.id, { refresh: options.refresh })), CATALOG_CONCURRENCY, options.onProgress);
+    const endpoints = [];
+    const failed = [];
+    details.forEach((detail, i) => {
+        if (!detail) {
+            failed.push(providers[i].id);
+            return;
+        }
+        for (const endpoint of flatEndpoints(detail)) {
+            endpoints.push({ provider: providers[i].id, endpoint });
+        }
+    });
+    return { endpoints, failed };
+}
+/**
+ * Format a per-request price. Real values span $0.000001 to $0.08, so a fixed
+ * number of decimals either rounds the cheap endpoints to $0.00 or pads the
+ * rest with noise — keep two significant digits instead.
+ */
+export function formatPrice(usd) {
+    if (usd == null)
+        return "—";
+    if (usd === 0)
+        return "free";
+    const precise = Number(usd.toPrecision(2));
+    const text = precise.toString();
+    // toString switches to exponent notation below 1e-6; expand it.
+    return `$${text.includes("e") ? precise.toFixed(10).replace(/0+$/, "") : text}`;
+}

package/dist/commands/account.js

@@ -36,6 +36,8 @@ export async function balanceAction(options = {}) {
 }
 export async function usageAction(_options) {
     requireApiKey();
-    console.log(chalk.yellow("  Usage API is not yet available."));
+    // 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://aisa.one/dashboard");
 }

package/dist/commands/api.d.ts

@@ -1,10 +1,24 @@
-export declare function apiListAction(_options: {
+export declare function apiListAction(options: {
     category?: string;
+    health?: boolean;
+    json?: boolean;
+    refresh?: boolean;
 }): Promise<void>;
-export declare function apiSearchAction(_query: string, _options: {
+export declare function apiShowAction(idOrSlug: string, path?: string, options?: {
+    group?: boolean;
+    health?: boolean;
+    json?: boolean;
+    all?: boolean;
+    refresh?: boolean;
+}): Promise<void>;
+export declare function apiSearchAction(query: string, options: {
     limit?: string;
+    provider?: string;
+    json?: boolean;
+    refresh?: boolean;
 }): Promise<void>;
-export declare function apiShowAction(_slug: string, _path?: string): Promise<void>;
-export declare function apiCodeAction(_slug: string, _path: string, _options: {
+export declare function apiCodeAction(slug: string, path: string, options: {
     lang?: string;
+    method?: string;
+    refresh?: boolean;
 }): Promise<void>;