@vib-rato/ai 0.16.0

package/src/usage/grok-cli.ts

@@ -0,0 +1,259 @@
+import { $credentialEnv } from "@vib-rato/utils";
+import type {
+	CredentialRankingStrategy,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+} from "../usage";
+
+interface BillingUsage {
+	monthlyLimit: number;
+	used: number;
+	billingPeriodEnd: string;
+}
+
+interface WeeklyBillingUsage {
+	creditUsagePercent: number;
+	billingPeriodEnd: string;
+}
+
+const DEFAULT_GROK_BUILD_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+const ALLOWED_GROK_BUILD_HOSTS = new Set(["cli-chat-proxy.grok.com"]);
+const GROK_WEEKLY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object";
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function parseValNumber(value: unknown): number | undefined {
+	return isRecord(value) ? finiteNumber(value.val) : undefined;
+}
+
+export function parseGrokCliBillingUsage(payload: unknown): BillingUsage {
+	if (!isRecord(payload) || !isRecord(payload.config)) {
+		throw new Error("invalid Grok CLI billing payload");
+	}
+	const monthlyLimit = parseValNumber(payload.config.monthlyLimit);
+	const used = parseValNumber(payload.config.used);
+	const billingPeriodEnd = payload.config.billingPeriodEnd;
+	if (
+		monthlyLimit === undefined ||
+		used === undefined ||
+		typeof billingPeriodEnd !== "string" ||
+		!Number.isFinite(new Date(billingPeriodEnd).getTime())
+	) {
+		throw new Error("invalid Grok CLI billing payload");
+	}
+	return { monthlyLimit, used, billingPeriodEnd };
+}
+
+export function parseGrokCliWeeklyBillingUsage(payload: unknown): WeeklyBillingUsage | undefined {
+	if (!isRecord(payload) || !isRecord(payload.config)) return undefined;
+	const currentPeriod = isRecord(payload.config.currentPeriod) ? payload.config.currentPeriod : undefined;
+	if (currentPeriod?.type !== "USAGE_PERIOD_TYPE_WEEKLY") return undefined;
+
+	const billingPeriodEnd = payload.config.billingPeriodEnd;
+	if (typeof billingPeriodEnd !== "string" || !Number.isFinite(new Date(billingPeriodEnd).getTime())) {
+		return undefined;
+	}
+
+	const rawCreditUsagePercent = payload.config.creditUsagePercent;
+	const creditUsagePercent = rawCreditUsagePercent === undefined ? 0 : finiteNumber(rawCreditUsagePercent);
+	if (creditUsagePercent === undefined) return undefined;
+
+	return { creditUsagePercent, billingPeriodEnd };
+}
+
+function isAllowedGrokCredentialHost(baseUrl: string): boolean {
+	try {
+		const url = new URL(baseUrl);
+		return url.protocol === "https:" && ALLOWED_GROK_BUILD_HOSTS.has(url.hostname.toLowerCase());
+	} catch {
+		return false;
+	}
+}
+
+function normalizeGrokBaseUrl(baseUrl?: string): string {
+	const normalized = (baseUrl?.trim() || DEFAULT_GROK_BUILD_BASE_URL).replace(/\/+$/, "");
+	return isAllowedGrokCredentialHost(normalized) ? normalized : DEFAULT_GROK_BUILD_BASE_URL;
+}
+function isUnsafeGrokBaseUrlOverride(baseUrl?: string): boolean {
+	const normalized = baseUrl?.trim().replace(/\/+$/, "");
+	return !!normalized && !isAllowedGrokCredentialHost(normalized);
+}
+
+function resolveAccessToken(params: UsageFetchParams): string | undefined {
+	// Trusted sources only for the env fallback: this token authenticates the
+	// billing/usage call, so whatever can set it decides which account is queried
+	// with it. `$env` merges the caller's `cwd/.env` into `process.env`, so
+	// reading it there would let repository content supply the credential.
+	// Stored credentials keep precedence.
+	const token = params.credential.accessToken ?? params.credential.apiKey ?? $credentialEnv("GROK_CLI_OAUTH_TOKEN");
+	return token?.trim() || undefined;
+}
+
+/** Test seam: the usage access token as resolved from a credential plus trusted env. */
+export function resolveGrokAccessTokenForTest(params: UsageFetchParams): string | undefined {
+	return resolveAccessToken(params);
+}
+
+function buildMonthlyUsageLimit(usage: BillingUsage, nowMs: number): UsageLimit {
+	const usedFraction = usage.monthlyLimit > 0 ? usage.used / usage.monthlyLimit : 0;
+	const percent = usedFraction * 100;
+	const resetsAt = new Date(usage.billingPeriodEnd).getTime();
+	return {
+		id: "grok-build:7d",
+		label: "SuperGrok monthly credits",
+		scope: { provider: "grok-build", shared: true, windowId: "7d" },
+		window: {
+			id: "7d",
+			label: "Monthly credits",
+			resetsAt,
+		},
+		amount: {
+			unit: "percent",
+			used: percent,
+			limit: 100,
+			remaining: Math.max(0, 100 - percent),
+			usedFraction,
+			remainingFraction: Math.max(0, 1 - usedFraction),
+		},
+		status: percent >= 95 ? "exhausted" : percent >= 80 ? "warning" : "ok",
+		notes: [
+			`${usage.used}/${usage.monthlyLimit} credits used`,
+			`resets in ${Math.max(0, Math.round((resetsAt - nowMs) / 3_600_000))}h`,
+		],
+	};
+}
+
+function buildWeeklyUsageLimit(usage: WeeklyBillingUsage): UsageLimit {
+	const percent = Math.min(Math.max(usage.creditUsagePercent, 0), 100);
+	const usedFraction = percent / 100;
+	const resetsAt = new Date(usage.billingPeriodEnd).getTime();
+	return {
+		id: "grok-build:weekly",
+		label: "SuperGrok weekly credits",
+		scope: { provider: "grok-build", shared: true, windowId: "weekly" },
+		window: {
+			id: "weekly",
+			label: "Weekly",
+			durationMs: GROK_WEEKLY_WINDOW_MS,
+			resetsAt,
+		},
+		amount: {
+			unit: "percent",
+			used: percent,
+			limit: 100,
+			remaining: 100 - percent,
+			usedFraction,
+			remainingFraction: 1 - usedFraction,
+		},
+		status: percent >= 95 ? "exhausted" : percent >= 80 ? "warning" : "ok",
+		notes: [`${percent}% used`],
+	};
+}
+
+export const grokCliUsageProvider: UsageProvider = {
+	id: "grok-build",
+
+	supports(params) {
+		return params.provider === "grok-build";
+	},
+
+	async fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+		const accessToken = resolveAccessToken(params);
+		if (!accessToken) {
+			ctx.logger?.warn("Grok Build usage: no access token", { provider: params.provider });
+			return null;
+		}
+
+		if (isUnsafeGrokBaseUrlOverride(params.baseUrl)) {
+			ctx.logger?.warn("Grok Build usage: ignoring unsafe base URL override for credential safety", {
+				provider: params.provider,
+			});
+		}
+		const billingBaseUrl = normalizeGrokBaseUrl(params.baseUrl);
+		const response = await ctx.fetch(`${billingBaseUrl}/billing`, {
+			headers: {
+				Authorization: `Bearer ${accessToken}`,
+				"x-xai-token-auth": "xai-grok-cli",
+				accept: "application/json",
+			},
+			signal: params.signal,
+		});
+		if (!response.ok) {
+			ctx.logger?.warn("Grok Build billing request failed", { status: response.status, provider: params.provider });
+			return null;
+		}
+
+		const payload = (await response.json()) as unknown;
+		let billing: BillingUsage;
+		try {
+			billing = parseGrokCliBillingUsage(payload);
+		} catch (error) {
+			ctx.logger?.warn("Grok Build billing parse failed", { error: String(error) });
+			return null;
+		}
+
+		const nowMs = Date.now();
+		let weekly: WeeklyBillingUsage | undefined;
+		try {
+			const weeklyResponse = await ctx.fetch(`${billingBaseUrl}/billing?format=credits`, {
+				headers: {
+					Authorization: `Bearer ${accessToken}`,
+					"x-xai-token-auth": "xai-grok-cli",
+					accept: "application/json",
+				},
+				signal: params.signal,
+			});
+			if (weeklyResponse.ok) {
+				weekly = parseGrokCliWeeklyBillingUsage((await weeklyResponse.json()) as unknown);
+			}
+		} catch (error) {
+			if (params.signal?.aborted && billing.monthlyLimit <= 0) throw error;
+			ctx.logger?.debug("Grok Build weekly billing request failed", { error: String(error) });
+		}
+
+		const limits: UsageLimit[] = [];
+		if (billing.monthlyLimit > 0) {
+			limits.push(buildMonthlyUsageLimit(billing, nowMs));
+		}
+		if (weekly) {
+			limits.push(buildWeeklyUsageLimit(weekly));
+		}
+		if (limits.length === 0) {
+			ctx.logger?.warn("Grok Build billing response contained no usable quota", {
+				provider: params.provider,
+			});
+			return null;
+		}
+
+		return {
+			provider: "grok-build",
+			fetchedAt: nowMs,
+			limits,
+			metadata: {
+				email: params.credential.email,
+				accountId: params.credential.accountId,
+				subscription: true,
+			},
+			raw: payload,
+		};
+	},
+};
+
+export const grokCliRankingStrategy: CredentialRankingStrategy = {
+	findWindowLimits(report) {
+		const weekly = report.limits.find(limit => limit.id === "grok-build:weekly");
+		if (weekly) return { secondary: weekly };
+		const monthly = report.limits.find(limit => limit.id === "grok-build:7d");
+		return { secondary: monthly };
+	},
+	windowDefaults: { primaryMs: 5 * 60 * 60 * 1000, secondaryMs: 30 * 24 * 60 * 60 * 1000 },
+};

package/src/usage/kimi.ts

@@ -0,0 +1,285 @@
+import { $credentialEnv } from "@vib-rato/utils";
+import type {
+	UsageAmount,
+	UsageFetchContext,
+	UsageFetchParams,
+	UsageLimit,
+	UsageProvider,
+	UsageReport,
+	UsageStatus,
+	UsageWindow,
+} from "../usage";
+import { isRecord } from "../utils";
+import { getKimiCommonHeaders } from "../utils/oauth/kimi";
+// (Refresh is the sole responsibility of AuthStorage; no provider-direct refresh here.)
+import { toNumber } from "./shared";
+
+const DEFAULT_BASE_URL = "https://api.kimi.com/coding/v1";
+const USAGE_PATH = "usages";
+
+interface KimiUsagePayload {
+	usage?: unknown;
+	limits?: unknown;
+}
+
+type KimiUsageRow = {
+	label: string;
+	used?: number;
+	limit?: number;
+	remaining?: number;
+	resetsAt?: number;
+	window?: UsageWindow;
+};
+
+/**
+ * Usage endpoint base, with the environment override resolved from trusted
+ * sources only.
+ *
+ * The result becomes the usage URL that the request sends
+ * `Authorization: Bearer <accessToken>` to, so whatever can set it receives the
+ * user's Kimi access token. `$env` merges the caller's `cwd/.env`, so reading it
+ * there would let repository content collect that token.
+ */
+function normalizeBaseUrl(baseUrl?: string): string {
+	const envBase = $credentialEnv("KIMI_CODE_BASE_URL");
+	const candidate = baseUrl?.trim() || envBase || DEFAULT_BASE_URL;
+	return candidate.replace(/\/+$/, "");
+}
+
+/** Test seam: the usage base URL as resolved from a caller value plus trusted env. */
+export function normalizeKimiUsageBaseUrlForTest(baseUrl?: string): string {
+	return normalizeBaseUrl(baseUrl);
+}
+
+function buildUsageUrl(baseUrl: string): string {
+	const normalized = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	return `${normalized}${USAGE_PATH}`;
+}
+
+function parseResetTime(data: Record<string, unknown>, nowMs: number): number | undefined {
+	const timeKeys = ["reset_at", "resetAt", "reset_time", "resetTime"] as const;
+	for (const key of timeKeys) {
+		const value = data[key];
+		if (typeof value === "string" && value.trim()) {
+			const parsed = Date.parse(value);
+			if (Number.isFinite(parsed)) return parsed;
+		}
+		if (typeof value === "number" && Number.isFinite(value)) {
+			return value > 1_000_000_000_000 ? value : value * 1000;
+		}
+	}
+
+	const secondsKeys = ["reset_in", "resetIn", "ttl", "window"] as const;
+	for (const key of secondsKeys) {
+		const seconds = toNumber(data[key]);
+		if (seconds !== undefined) return nowMs + seconds * 1000;
+	}
+
+	return undefined;
+}
+
+function formatDurationLabel(duration: number, timeUnit: string): string | undefined {
+	const upper = timeUnit.toUpperCase();
+	if (upper.includes("MINUTE")) {
+		if (duration >= 60 && duration % 60 === 0) return `${duration / 60}h limit`;
+		return `${duration}m limit`;
+	}
+	if (upper.includes("HOUR")) return `${duration}h limit`;
+	if (upper.includes("DAY")) return `${duration}d limit`;
+	if (upper.includes("SECOND")) return `${duration}s limit`;
+	return undefined;
+}
+
+function buildWindow(windowData: Record<string, unknown>, nowMs: number): UsageWindow | undefined {
+	const duration = toNumber(windowData.duration);
+	const timeUnit = typeof windowData.timeUnit === "string" ? windowData.timeUnit : "";
+	const label = duration !== undefined && timeUnit ? formatDurationLabel(duration, timeUnit) : undefined;
+	const resetsAt = parseResetTime(windowData, nowMs);
+
+	if (duration === undefined && !label && !resetsAt) return undefined;
+	let durationMs: number | undefined;
+	if (duration !== undefined) {
+		if (timeUnit.toUpperCase().includes("MINUTE")) durationMs = duration * 60_000;
+		else if (timeUnit.toUpperCase().includes("HOUR")) durationMs = duration * 3_600_000;
+		else if (timeUnit.toUpperCase().includes("DAY")) durationMs = duration * 86_400_000;
+		else if (timeUnit.toUpperCase().includes("SECOND")) durationMs = duration * 1000;
+	}
+
+	return {
+		id: duration !== undefined && timeUnit ? `${duration}${timeUnit.toLowerCase()}` : "default",
+		label: label ?? "Usage window",
+		durationMs,
+		resetsAt,
+	};
+}
+
+function buildUsageRow(data: Record<string, unknown>, defaultLabel: string, nowMs: number): KimiUsageRow | null {
+	const limit = toNumber(data.limit);
+	let used = toNumber(data.used);
+	const remaining = toNumber(data.remaining);
+	if (used === undefined && remaining !== undefined && limit !== undefined) {
+		used = limit - remaining;
+	}
+
+	if (used === undefined && limit === undefined) return null;
+	const resetsAt = parseResetTime(data, nowMs);
+	return {
+		label:
+			typeof data.name === "string" && data.name
+				? data.name
+				: typeof data.title === "string" && data.title
+					? data.title
+					: defaultLabel,
+		used,
+		limit,
+		remaining,
+		resetsAt,
+	};
+}
+
+function buildUsageAmount(row: KimiUsageRow): UsageAmount {
+	const amount: UsageAmount = { unit: "unknown" };
+	if (row.limit !== undefined) amount.limit = row.limit;
+	if (row.used !== undefined) amount.used = row.used;
+	if (row.remaining !== undefined) amount.remaining = row.remaining;
+	if (row.limit !== undefined && row.used !== undefined && row.limit > 0) {
+		amount.usedFraction = Math.min(Math.max(row.used / row.limit, 0), 1);
+		amount.remainingFraction = Math.min(Math.max((row.limit - row.used) / row.limit, 0), 1);
+		amount.remaining = amount.remaining ?? row.limit - row.used;
+	}
+	return amount;
+}
+
+function buildUsageStatus(amount: UsageAmount): UsageStatus {
+	if (amount.usedFraction === undefined) return "unknown";
+	if (amount.usedFraction >= 1) return "exhausted";
+	if (amount.usedFraction >= 0.9) return "warning";
+	return "ok";
+}
+
+function toUsageLimit(row: KimiUsageRow, provider: string, index: number, accountId?: string): UsageLimit {
+	const window: UsageWindow | undefined =
+		row.window ??
+		(row.resetsAt
+			? {
+					id: "default",
+					label: "Usage window",
+					resetsAt: row.resetsAt,
+				}
+			: undefined);
+
+	const amount = buildUsageAmount(row);
+	return {
+		id: `${provider}:${index}`,
+		label: row.label,
+		scope: {
+			provider,
+			accountId,
+			windowId: window?.id,
+			shared: true,
+		},
+		window,
+		amount,
+		status: buildUsageStatus(amount),
+	};
+}
+
+function parseUsagePayload(payload: unknown, nowMs: number): { rows: KimiUsageRow[]; raw: KimiUsagePayload } | null {
+	if (!isRecord(payload)) return null;
+	const data = payload as KimiUsagePayload;
+	const rows: KimiUsageRow[] = [];
+
+	if (isRecord(data.usage)) {
+		const summary = buildUsageRow(data.usage, "Total quota", nowMs);
+		if (summary) rows.push(summary);
+	}
+
+	if (Array.isArray(data.limits)) {
+		data.limits.forEach((item, idx) => {
+			if (!isRecord(item)) return;
+			const detail = isRecord(item.detail) ? item.detail : item;
+			const windowData = isRecord(item.window) ? item.window : {};
+			const label =
+				(typeof item.name === "string" && item.name) ||
+				(typeof item.title === "string" && item.title) ||
+				(typeof item.scope === "string" && item.scope) ||
+				(typeof detail.name === "string" && detail.name) ||
+				(typeof detail.title === "string" && detail.title) ||
+				formatDurationLabel(toNumber(windowData.duration) ?? 0, String(windowData.timeUnit || "")) ||
+				`Limit #${idx + 1}`;
+			const row = buildUsageRow(detail, label, nowMs);
+			if (row) {
+				row.window = buildWindow(windowData, nowMs);
+				rows.push(row);
+			}
+		});
+	}
+
+	return { rows, raw: data };
+}
+
+export const kimiUsageProvider: UsageProvider = {
+	id: "kimi-code",
+	supports(params: UsageFetchParams): boolean {
+		return params.provider === "kimi-code" && params.credential.type === "oauth";
+	},
+	async fetchUsage(params: UsageFetchParams, ctx: UsageFetchContext): Promise<UsageReport | null> {
+		if (params.provider !== "kimi-code") return null;
+		const { credential } = params;
+		if (credential.type !== "oauth") return null;
+
+		const accessToken = credential.accessToken;
+		if (!accessToken) return null;
+
+		const nowMs = Date.now();
+		// AuthStorage refreshes OAuth credentials pre-emptively (60s skew). If the
+		// usage probe lands with an expired token, short-circuit rather than POST
+		// the broker sentinel back to Kimi — the next cycle will carry a freshly
+		// refreshed credential.
+		if (credential.expiresAt !== undefined && credential.expiresAt <= nowMs) {
+			ctx.logger?.debug("Kimi usage token expired; skipping probe", { provider: params.provider });
+			return null;
+		}
+
+		const baseUrl = normalizeBaseUrl(params.baseUrl);
+		const url = buildUsageUrl(baseUrl);
+		let payload: unknown;
+		try {
+			const response = await ctx.fetch(url, {
+				headers: {
+					...getKimiCommonHeaders(),
+					Authorization: `Bearer ${accessToken}`,
+				},
+				signal: params.signal,
+			});
+			if (!response.ok) {
+				ctx.logger?.warn("Kimi usage request failed", { status: response.status, provider: params.provider });
+				return null;
+			}
+			payload = await response.json();
+		} catch (error) {
+			ctx.logger?.warn("Kimi usage request error", { provider: params.provider, error: String(error) });
+			return null;
+		}
+
+		const parsed = parseUsagePayload(payload, nowMs);
+		if (!parsed || parsed.rows.length === 0) {
+			ctx.logger?.warn("Kimi usage response invalid", { provider: params.provider });
+			return null;
+		}
+
+		const limits = parsed.rows.map((row, index) => toUsageLimit(row, params.provider, index, credential.accountId));
+
+		const report: UsageReport = {
+			provider: params.provider,
+			fetchedAt: nowMs,
+			limits,
+			metadata: {
+				endpoint: url,
+			},
+			raw: parsed.raw,
+		};
+
+		return report;
+	},
+};

package/src/usage/minimax-code.ts

@@ -0,0 +1,31 @@
+import type { UsageFetchContext, UsageFetchParams, UsageProvider, UsageReport } from "../usage";
+
+/**
+ * MiniMax Coding Plan usage provider.
+ *
+ * MiniMax Coding Plan is a subscription-based service with a 5-hour rolling window
+ * quota system. The quota resets automatically based on a rolling window.
+ *
+ * Currently, MiniMax does not expose a usage/quota API endpoint for the Coding Plan.
+ * Usage is tracked via the web dashboard at https://platform.minimax.io/user-center/payment/coding-plan
+ *
+ * This provider exists to register support for the minimax-code provider in the
+ * usage system. When MiniMax adds a usage API, this can be implemented.
+ */
+async function fetchMiniMaxCodeUsage(params: UsageFetchParams, _ctx: UsageFetchContext): Promise<UsageReport | null> {
+	if (params.provider !== "minimax-code" && params.provider !== "minimax-code-cn") {
+		return null;
+	}
+
+	// MiniMax Coding Plan does not currently expose a usage API
+	// Users can check their usage via the web dashboard
+	return null;
+}
+
+export const minimaxCodeUsageProvider: UsageProvider = {
+	id: "minimax-code",
+	fetchUsage: fetchMiniMaxCodeUsage,
+	supports: (params: UsageFetchParams) =>
+		(params.provider === "minimax-code" || params.provider === "minimax-code-cn") &&
+		params.credential.type === "api_key",
+};