@hyav/pi-provider 0.1.3 → 0.1.4

package/status/github-copilot.ts

@@ -0,0 +1,176 @@
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+
+/**
+ * GitHub Copilot Individual usage. These endpoints are not part of public
+ * GitHub documentation, so payload shapes are parsed defensively and a 404
+ * degrades to a single explanatory entry instead of an error state.
+ */
+export const COPILOT_USAGE_URL = "https://api.individual.githubcopilot.com/usage";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+const MAX_LABEL_LENGTH = 64;
+
+function safeText(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed === "" || trimmed.length > MAX_LABEL_LENGTH || /[\u0000-\u001f\u007f]/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+interface CopilotQuota {
+	id: string;
+	name?: string;
+	used: number;
+	limit: number;
+	resetAt?: number;
+}
+
+function labelValue(value: unknown): string | undefined {
+	if (typeof value === "string") return safeText(value);
+	if (isRecord(value)) return safeText(value.value) ?? safeText(value.label);
+	return undefined;
+}
+
+function planName(value: unknown): string | undefined {
+	return labelValue(isRecord(value) ? value.planName : undefined);
+}
+
+/** Preferred shape: `modelCatalog.usage.modelQuotas`. */
+function parseModelCatalog(catalog: unknown): CopilotQuota[] {
+	if (!isRecord(catalog) || !isRecord(catalog.usage) || !isRecord(catalog.usage.modelQuotas)) return [];
+	const quotas: CopilotQuota[] = [];
+	for (const [key, value] of Object.entries(catalog.usage.modelQuotas)) {
+		if (!isRecord(value)) continue;
+		const used =
+			finiteNumber(value.usedRequestsQuantity) ?? finiteNumber(value.usedRequests) ?? finiteNumber(value.used);
+		const limit = finiteNumber(value.allowedRequestsQuantity);
+		if (used === undefined || limit === undefined || limit <= 0) continue;
+		const resetAt = finiteNumber(value.resetAt);
+		quotas.push({
+			id: key,
+			name: safeText(value.modelCopilotName),
+			used,
+			limit,
+			...(resetAt !== undefined ? { resetAt: resetAt * 1_000 } : {}),
+		});
+	}
+	return quotas;
+}
+
+/** Fallback shape: `modelQuotaByFeature[]` with nested payload. */
+function parseQuotaByFeature(payload: unknown): CopilotQuota[] {
+	if (!isRecord(payload) || !Array.isArray(payload.modelQuotaByFeature)) return [];
+	const quotas: CopilotQuota[] = [];
+	for (const [index, entry] of payload.modelQuotaByFeature.entries()) {
+		if (!isRecord(entry)) continue;
+		const quota =
+			(isRecord(entry.modelQuotaPayload) && entry.modelQuotaPayload) ||
+			(isRecord(entry.modelQuotaForFeature) && entry.modelQuotaForFeature);
+		if (!quota) continue;
+		const used = finiteNumber(quota.usedRequestsQuantity) ?? finiteNumber(quota.usedRequests);
+		const limit = finiteNumber(quota.allowedRequestsQuantity);
+		if (used === undefined || limit === undefined) continue;
+		const resetAt = finiteNumber(quota.resetAt);
+		const name = safeText(quota.modelCopilotName);
+		quotas.push({
+			id: typeof quota.quotaId === "string" && quota.quotaId.trim() !== "" ? quota.quotaId.trim() : `quota-${index}`,
+			...(name !== undefined ? { name } : {}),
+			used,
+			limit,
+			...(resetAt !== undefined ? { resetAt: resetAt * 1_000 } : {}),
+		});
+	}
+	return quotas;
+}
+
+function windowEntry(quota: CopilotQuota): StatusEntry {
+	const percent = (quota.used / quota.limit) * 100;
+	return {
+		kind: "window",
+		id: `quota-${quota.id}`,
+		label: quota.name ?? quota.id,
+		remainingPercent: Math.max(0, Math.min(100, 100 - percent)),
+		...(quota.resetAt !== undefined ? { resetAt: quota.resetAt } : {}),
+	};
+}
+
+export const githubCopilotStatusAdapter: StatusAdapter = {
+	id: "github-copilot-status",
+	providerId: "github-copilot",
+	name: "GitHub Copilot",
+	cacheTtlMs: 60_000,
+	requestTimeoutMs: 8_000,
+	async fetch(context): Promise<StatusSnapshot> {
+		const key = await context.getApiKey();
+		if (!key || key === "proxy-managed") {
+			throw new ProviderDataError("GitHub Copilot status requires Copilot OAuth", "auth");
+		}
+		const response = await context.fetch(COPILOT_USAGE_URL, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				Authorization: `Bearer ${key}`,
+				"User-Agent": "@hyav/pi-provider",
+			},
+			signal: context.signal,
+		});
+		if (response.status === 404) {
+			return {
+				entries: [{ kind: "text", id: "usage", label: "Usage", value: "unavailable for this plan" }],
+				updatedAt: context.now(),
+			};
+		}
+		if (!response.ok) {
+			throw new ProviderDataError(
+				`GitHub Copilot status failed: HTTP ${response.status}`,
+				`http${response.status}`,
+				parseRetryAfter(response.headers.get("retry-after"), context.now()),
+				response.status,
+			);
+		}
+		let payload: unknown;
+		try {
+			payload = await response.json();
+		} catch {
+			throw new ProviderDataError("GitHub Copilot status returned invalid JSON", "badjson");
+		}
+		if (!isRecord(payload)) {
+			throw new ProviderDataError("GitHub Copilot status returned an invalid usage response", "badjson");
+		}
+		const quotas = parseModelCatalog(isRecord(payload.modelCatalog) ? payload.modelCatalog : payload);
+		const modelQuotas = quotas.length > 0 ? quotas : parseQuotaByFeature(payload);
+		const entries: StatusEntry[] = [
+			{
+				kind: "text",
+				id: "plan",
+				label: "Plan",
+				value: isRecord(payload.modelCatalog) ? (planName(payload.modelCatalog) ?? "Unknown") : "Unknown",
+			},
+		];
+		for (const quota of modelQuotas) entries.push(windowEntry(quota));
+		if (entries.length === 1) {
+			entries.push({ kind: "text", id: "limits", label: "Limits", value: "not available" });
+		}
+		return { entries, updatedAt: context.now() };
+	},
+};
+
+export function createGithubCopilotStatusAdapter(requestTimeoutMs: number): StatusAdapter {
+	return { ...githubCopilotStatusAdapter, requestTimeoutMs };
+}
+
+const githubCopilotStatusExtension = defineStatusExtension({
+	id: "github-copilot-status",
+	providerId: "github-copilot",
+	create: ({ statusRequestTimeoutMs }) => createGithubCopilotStatusAdapter(statusRequestTimeoutMs),
+});
+
+export default githubCopilotStatusExtension;

package/status/groq.ts

@@ -0,0 +1,88 @@
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+import { parseRateLimitWindows } from "../core/ratelimit-headers.ts";
+
+export const GROQ_MODELS_URL = "https://api.groq.com/openai/v1/models";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function windowEntry(
+	id: string,
+	label: string,
+	window: { limit: number; remaining: number; resetAt?: number },
+): StatusEntry {
+	const percent = (window.remaining / window.limit) * 100;
+	return {
+		kind: "window",
+		id,
+		label,
+		remainingPercent: Math.max(0, Math.min(100, percent)),
+		...(window.resetAt !== undefined ? { resetAt: window.resetAt } : {}),
+	};
+}
+
+export const groqStatusAdapter: StatusAdapter = {
+	id: "groq-status",
+	providerId: "groq",
+	name: "Groq",
+	cacheTtlMs: 60_000,
+	requestTimeoutMs: 8_000,
+	async fetch(context): Promise<StatusSnapshot> {
+		const key = await context.getApiKey();
+		if (!key || key === "proxy-managed") {
+			throw new ProviderDataError("Groq status requires an API key", "auth");
+		}
+		const response = await context.fetch(GROQ_MODELS_URL, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				Authorization: `Bearer ${key}`,
+				"User-Agent": "@hyav/pi-provider",
+			},
+			signal: context.signal,
+		});
+		if (!response.ok) {
+			throw new ProviderDataError(
+				`Groq status failed: HTTP ${response.status}`,
+				`http${response.status}`,
+				parseRetryAfter(response.headers.get("retry-after"), context.now()),
+				response.status,
+			);
+		}
+		let modelCount: string | undefined;
+		try {
+			const payload: unknown = await response.json();
+			modelCount = isRecord(payload) && Array.isArray(payload.data) ? `${payload.data.length} available` : undefined;
+		} catch {
+			modelCount = undefined;
+		}
+
+		const now = context.now();
+		const { requests, tokens } = parseRateLimitWindows(response.headers, now);
+		const entries: StatusEntry[] = [
+			modelCount === undefined
+				? { kind: "text", id: "models", label: "Models", value: "unavailable" }
+				: { kind: "text", id: "models", label: "Models", value: modelCount },
+		];
+		if (requests) entries.push(windowEntry("requests-per-day", "Requests per day", requests));
+		if (tokens) entries.push(windowEntry("tokens-per-minute", "Tokens per minute", tokens));
+		if (entries.length === 1) {
+			entries.push({ kind: "text", id: "limits", label: "Limits", value: "not available" });
+		}
+		return { entries, updatedAt: now };
+	},
+};
+
+export function createGroqStatusAdapter(requestTimeoutMs: number): StatusAdapter {
+	return { ...groqStatusAdapter, requestTimeoutMs };
+}
+
+const groqStatusExtension = defineStatusExtension({
+	id: "groq-status",
+	providerId: "groq",
+	create: ({ statusRequestTimeoutMs }) => createGroqStatusAdapter(statusRequestTimeoutMs),
+});
+
+export default groqStatusExtension;

package/status/huggingface.ts

@@ -0,0 +1,94 @@
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+
+export const HF_WHOAMI_URL = "https://huggingface.co/api/whoami-v2";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+const MAX_LABEL_LENGTH = 64;
+
+function safeText(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed === "" || trimmed.length > MAX_LABEL_LENGTH || /[\u0000-\u001f\u007f]/.test(trimmed)) return undefined;
+	return trimmed;
+}
+
+export interface HuggingFaceAccount {
+	plan?: string;
+	credits?: number;
+}
+
+export function parseHuggingFaceAccount(payload: unknown): HuggingFaceAccount {
+	if (!isRecord(payload)) {
+		throw new ProviderDataError("Hugging Face status returned an invalid account response", "badjson");
+	}
+	// Response envelope: { type, id, name, emailVerified, canPay, isPro, plan, periodEnd, credits, ... }
+	const plan = safeText(payload.plan);
+	// Older token generations omit the envelope fields entirely.
+	return {
+		...(plan !== undefined ? { plan } : {}),
+		...(finiteNumber(payload.credits) !== undefined ? { credits: finiteNumber(payload.credits) } : {}),
+	};
+}
+
+export const huggingFaceStatusAdapter: StatusAdapter = {
+	id: "huggingface-status",
+	providerId: "huggingface",
+	name: "Hugging Face",
+	cacheTtlMs: 60_000,
+	requestTimeoutMs: 8_000,
+	async fetch(context): Promise<StatusSnapshot> {
+		const key = await context.getApiKey();
+		if (!key || key === "proxy-managed") {
+			throw new ProviderDataError("Hugging Face status requires a token", "auth");
+		}
+		const response = await context.fetch(HF_WHOAMI_URL, {
+			headers: {
+				Accept: "application/json",
+				"Accept-Encoding": "identity",
+				Authorization: `Bearer ${key}`,
+				"User-Agent": "@hyav/pi-provider",
+			},
+			signal: context.signal,
+		});
+		if (!response.ok) {
+			throw new ProviderDataError(
+				`Hugging Face status failed: HTTP ${response.status}`,
+				`http${response.status}`,
+				parseRetryAfter(response.headers.get("retry-after"), context.now()),
+				response.status,
+			);
+		}
+		let payload: unknown;
+		try {
+			payload = await response.json();
+		} catch {
+			throw new ProviderDataError("Hugging Face status returned invalid JSON", "badjson");
+		}
+		const account = parseHuggingFaceAccount(payload);
+		const entries: StatusEntry[] = [{ kind: "text", id: "plan", label: "Plan", value: account.plan ?? "Unknown" }];
+		if (account.credits !== undefined) {
+			entries.push({ kind: "amount", id: "credits", label: "Credits", value: account.credits, unit: "USD" });
+		}
+		return { entries, updatedAt: context.now() };
+	},
+};
+
+export function createHuggingFaceStatusAdapter(requestTimeoutMs: number): StatusAdapter {
+	return { ...huggingFaceStatusAdapter, requestTimeoutMs };
+}
+
+const huggingFaceStatusExtension = defineStatusExtension({
+	id: "huggingface-status",
+	providerId: "huggingface",
+	create: ({ statusRequestTimeoutMs }) => createHuggingFaceStatusAdapter(statusRequestTimeoutMs),
+});
+
+export default huggingFaceStatusExtension;

package/status/moonshotai-cn.ts

@@ -0,0 +1,26 @@
+import type { StatusAdapter } from "@hyav/pi-provider";
+import { defineStatusExtension } from "@hyav/pi-provider";
+import { createMoonshotStatusAdapter, MOONSHOT_CN_BALANCE_URL } from "./moonshotai.ts";
+
+export const moonshotaiCnStatusAdapter: StatusAdapter = createMoonshotStatusAdapter(
+	{
+		id: "moonshotai-cn-status",
+		providerId: "moonshotai-cn",
+		name: "Moonshot CN (Kimi)",
+		balanceUrl: MOONSHOT_CN_BALANCE_URL,
+		unit: "CNY",
+	},
+	8_000,
+);
+
+export function createMoonshotaiCnStatusAdapter(requestTimeoutMs: number): StatusAdapter {
+	return { ...moonshotaiCnStatusAdapter, requestTimeoutMs };
+}
+
+const moonshotaiCnStatusExtension = defineStatusExtension({
+	id: "moonshotai-cn-status",
+	providerId: "moonshotai-cn",
+	create: ({ statusRequestTimeoutMs }) => createMoonshotaiCnStatusAdapter(statusRequestTimeoutMs),
+});
+
+export default moonshotaiCnStatusExtension;

package/status/moonshotai.ts

@@ -0,0 +1,150 @@
+import type { StatusAdapter, StatusEntry, StatusSnapshot } from "@hyav/pi-provider";
+import { defineStatusExtension, ProviderDataError, parseRetryAfter } from "@hyav/pi-provider";
+
+/**
+ * Moonshot (Kimi) balance checks. International and China platforms keep
+ * fully independent API keys; the same response shape is shared by both
+ * endpoints, so the adapter body is factored once.
+ */
+export const MOONSHOT_BALANCE_URL = "https://api.moonshot.ai/v1/users/me/balance";
+export const MOONSHOT_CN_BALANCE_URL = "https://api.moonshot.cn/v1/users/me/balance";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export interface MoonshotBalance {
+	available: number;
+	voucher?: number;
+	cash?: number;
+}
+
+export function parseMoonshotBalance(payload: unknown): MoonshotBalance {
+	if (!isRecord(payload) || !isRecord(payload.data)) {
+		throw new ProviderDataError("Moonshot status returned an invalid balance response", "badjson");
+	}
+	const code = payload.code;
+	if (code !== 0 && code !== undefined) {
+		throw new ProviderDataError("Moonshot status returned an unsuccessful balance response", "provider");
+	}
+	const available = finiteNumber(payload.data.available_balance);
+	if (available === undefined) {
+		throw new ProviderDataError("Moonshot status returned an invalid balance response", "badjson");
+	}
+	const voucher = finiteNumber(payload.data.voucher_balance);
+	const cash = finiteNumber(payload.data.cash_balance);
+	// Voucher balances are documented as non-negative; cash may be negative.
+	if (voucher !== undefined && voucher < 0) {
+		throw new ProviderDataError("Moonshot status returned an invalid balance response", "badjson");
+	}
+	return {
+		available,
+		...(voucher !== undefined ? { voucher } : {}),
+		...(cash !== undefined ? { cash } : {}),
+	};
+}
+
+export interface MoonshotStatusConfig {
+	id: string;
+	providerId: string;
+	name: string;
+	balanceUrl: string;
+	/** Official docs: international balances are USD; China balances are CNY. */
+	unit: string;
+}
+
+export function createMoonshotStatusAdapter(config: MoonshotStatusConfig, requestTimeoutMs: number): StatusAdapter {
+	const unit = config.unit;
+	return {
+		id: config.id,
+		providerId: config.providerId,
+		name: config.name,
+		cacheTtlMs: 60_000,
+		requestTimeoutMs,
+		async fetch(context): Promise<StatusSnapshot> {
+			const key = await context.getApiKey();
+			if (!key || key === "proxy-managed") {
+				throw new ProviderDataError(`${config.name} status requires an API key`, "auth");
+			}
+			const response = await context.fetch(config.balanceUrl, {
+				headers: {
+					Accept: "application/json",
+					"Accept-Encoding": "identity",
+					Authorization: `Bearer ${key}`,
+					"User-Agent": "@hyav/pi-provider",
+				},
+				signal: context.signal,
+			});
+			if (!response.ok) {
+				throw new ProviderDataError(
+					`${config.name} status failed: HTTP ${response.status}`,
+					`http${response.status}`,
+					parseRetryAfter(response.headers.get("retry-after"), context.now()),
+					response.status,
+				);
+			}
+			let payload: unknown;
+			try {
+				payload = await response.json();
+			} catch {
+				throw new ProviderDataError(`${config.name} status returned invalid JSON`, "badjson");
+			}
+			const balance = parseMoonshotBalance(payload);
+			const entries: StatusEntry[] = [
+				{
+					kind: "amount",
+					id: "available-balance",
+					label: "Available balance",
+					value: balance.available,
+					unit,
+				},
+			];
+			if (balance.voucher !== undefined) {
+				entries.push({
+					kind: "amount",
+					id: "voucher-balance",
+					label: "Voucher balance",
+					value: balance.voucher,
+					unit,
+				});
+			}
+			if (balance.cash !== undefined) {
+				entries.push({
+					kind: "amount",
+					id: "cash-balance",
+					label: "Cash balance",
+					value: balance.cash,
+					unit,
+				});
+			}
+			return { entries, updatedAt: context.now() };
+		},
+	};
+}
+
+export const moonshotaiStatusAdapter = createMoonshotStatusAdapter(
+	{
+		id: "moonshotai-status",
+		providerId: "moonshotai",
+		name: "Moonshot (Kimi)",
+		balanceUrl: MOONSHOT_BALANCE_URL,
+		unit: "USD",
+	},
+	8_000,
+);
+
+export function createMoonshotaiStatusAdapter(requestTimeoutMs: number): StatusAdapter {
+	return { ...moonshotaiStatusAdapter, requestTimeoutMs };
+}
+
+const moonshotaiStatusExtension = defineStatusExtension({
+	id: "moonshotai-status",
+	providerId: "moonshotai",
+	create: ({ statusRequestTimeoutMs }) => createMoonshotaiStatusAdapter(statusRequestTimeoutMs),
+});
+
+export default moonshotaiStatusExtension;