@aaroncarry/pi-usage 0.1.0

package/src/providers/auto-detect.ts

@@ -0,0 +1,343 @@
+/**
+ * Auto-detecting adapter for providers without a built-in one.
+ *
+ * Approach borrowed from pi-provider-hub: given the provider's base URL,
+ * probe well-known relay billing protocols — New API (`/dashboard/billing/*`,
+ * the most common self-hosted gateway), Sub2API (`/usage`) — plus hostname
+ * pinned endpoints for DeepSeek, MiniMax, and Zhipu (for custom ids pointing
+ * at those hosts).
+ *
+ * The first successful probe pins the winning candidate for the session; an
+ * exhausted probe (every candidate rejected terminally, e.g. HTTP 404/401)
+ * pins a "not supported" error so probing does not repeat on every refresh.
+ * Transient network errors stay unpinned and are retried next time.
+ */
+
+import { toNumber } from "../parse.ts";
+import type { AccountBalance, ProviderAdapter, ProviderFetchArgs } from "../types.ts";
+
+/** Same-origin URL join: "https://x.com/v1" + "usage" → "https://x.com/v1/usage". */
+function resolveSameOriginEndpoint(baseUrl: string, endpoint: string): string {
+	return new URL(endpoint.trim(), `${baseUrl.replace(/\/+$/, "")}/`).toString();
+}
+
+/** Base URLs to probe: a base with a path is already specific; a bare origin also tries /v1. */
+function baseUrlCandidates(baseUrl: string): string[] {
+	const parsed = new URL(baseUrl);
+	const trimmed = baseUrl.replace(/\/+$/, "");
+	if (parsed.pathname !== "" && parsed.pathname !== "/") return [trimmed];
+	return [trimmed, `${trimmed}/v1`];
+}
+
+interface CandidateContext {
+	baseUrl: string;
+	token: string;
+	signal?: AbortSignal;
+	fetchImpl: ProviderFetchArgs["fetchImpl"];
+}
+
+type Candidate = {
+	name: string;
+	run(ctx: CandidateContext): Promise<Omit<AccountBalance, "providerId" | "label" | "fetchedAt">>;
+};
+
+async function requestJson(
+	url: string,
+	token: string,
+	fetchImpl: ProviderFetchArgs["fetchImpl"],
+	signal: AbortSignal | undefined,
+	authorization: "bearer" | "raw" = "bearer",
+): Promise<unknown> {
+	const response = await fetchImpl(url, {
+		headers: {
+			Accept: "application/json",
+			Authorization: authorization === "bearer" ? `Bearer ${token}` : token,
+		},
+		signal,
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status}`);
+	return response.json();
+}
+
+function numberAt(payload: unknown, ...paths: string[][]): number | undefined {
+	for (const path of paths) {
+		let current: unknown = payload;
+		for (const segment of path) {
+			if (typeof current !== "object" || current === null) {
+				current = undefined;
+				break;
+			}
+			current = (current as Record<string, unknown>)[segment];
+		}
+		const value = toNumber(current);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
+function stringAt(payload: unknown, ...paths: string[][]): string | undefined {
+	for (const path of paths) {
+		let current: unknown = payload;
+		for (const segment of path) {
+			if (typeof current !== "object" || current === null) {
+				current = undefined;
+				break;
+			}
+			current = (current as Record<string, unknown>)[segment];
+		}
+		if (typeof current === "string" && current.trim() !== "") return current.trim();
+	}
+	return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const deepseekCandidate: Candidate = {
+	name: "deepseek",
+	async run({ baseUrl, token, signal, fetchImpl }) {
+		const payload = (await requestJson(resolveSameOriginEndpoint(baseUrl, "user/balance"), token, fetchImpl, signal)) as unknown;
+		if (!isRecord(payload) || !Array.isArray(payload.balance_infos)) {
+			throw new Error("response has no balance_infos");
+		}
+		const entries = payload.balance_infos.filter(isRecord);
+		const entry =
+			entries.find((item) => stringAt(item, ["currency"])?.toUpperCase() === "CNY") ?? entries[0] ?? payload;
+		const amount = numberAt(entry, ["total_balance"]);
+		if (amount === undefined) throw new Error("response has no total_balance");
+		return { balance: { amount, currency: stringAt(entry, ["currency"]) ?? "CNY" }, windows: [], notes: [] };
+	},
+};
+
+const minimaxCandidate: Candidate = {
+	name: "minimax",
+	async run({ baseUrl, token, signal, fetchImpl }) {
+		let lastError: Error | undefined;
+		for (const endpoint of ["v1/token_plan/remains", "v1/api/openplatform/coding_plan/remains"]) {
+			try {
+				const payload = (await requestJson(resolveSameOriginEndpoint(baseUrl, endpoint), token, fetchImpl, signal)) as unknown;
+				const data = isRecord(payload) && isRecord(payload.data) ? payload.data : isRecord(payload) ? payload : {};
+				const models = Array.isArray(data.model_remains)
+					? data.model_remains.filter(isRecord)
+					: [];
+				const model =
+					models.find((item) => stringAt(item, ["model_name"], ["modelName"])?.toLowerCase().startsWith("minimax-m")) ??
+					models[0] ??
+					data;
+				const total = numberAt(model, ["current_interval_total_count"], ["currentIntervalTotalCount"]);
+				const remainingPercent = numberAt(
+					model,
+					["current_interval_remaining_percent"],
+					["currentIntervalRemainingPercent"],
+					["remaining_percent"],
+					["remainingPercent"],
+				);
+				const remainingCount = numberAt(
+					model,
+					["current_interval_remaining"],
+					["currentIntervalRemaining"],
+					["current_interval_usage_count"],
+					["currentIntervalUsageCount"],
+				);
+				let usedPercent: number | undefined;
+				if (remainingPercent !== undefined) usedPercent = 100 - remainingPercent;
+				else if (total !== undefined && total > 0 && remainingCount !== undefined) {
+					usedPercent = (remainingCount / total) * 100;
+				}
+				if (usedPercent === undefined) throw new Error("response has no quota fields");
+				return {
+					windows: [{ label: "plan", usedPercent: Math.max(0, Math.min(100, usedPercent)) }],
+					notes: [],
+				};
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+			}
+		}
+		throw lastError ?? new Error("endpoints not found");
+	},
+};
+
+const zhipuCandidate: Candidate = {
+	name: "zhipu",
+	async run({ baseUrl, token, signal, fetchImpl }) {
+		const payload = (await requestJson(
+			resolveSameOriginEndpoint(baseUrl, "/api/monitor/usage/quota/limit"),
+			token,
+			fetchImpl,
+			signal,
+			"raw",
+		)) as unknown;
+		const data = isRecord(payload) && isRecord(payload.data) ? payload.data : isRecord(payload) ? payload : {};
+		const limits = Array.isArray(data.limits) ? data.limits.filter(isRecord) : [];
+		const limit = limits.find((item) => stringAt(item, ["type"])?.toUpperCase() === "TOKENS_LIMIT");
+		const usedPercent = numberAt(limit, ["percentage"], ["usedPercentage"]);
+		if (usedPercent === undefined) throw new Error("response has no usage percentage");
+		return {
+			windows: [{ label: "tokens", usedPercent: Math.max(0, Math.min(100, usedPercent)) }],
+			notes: [],
+		};
+	},
+};
+
+const newApiCandidate: Candidate = {
+	name: "new-api",
+	async run({ baseUrl, token, signal, fetchImpl }) {
+		let lastError: Error | undefined;
+		for (const base of baseUrlCandidates(baseUrl)) {
+			try {
+				const subscription = (await requestJson(
+					resolveSameOriginEndpoint(base, "dashboard/billing/subscription"),
+					token,
+					fetchImpl,
+					signal,
+				)) as unknown;
+				const usage = (await requestJson(
+					resolveSameOriginEndpoint(base, "dashboard/billing/usage"),
+					token,
+					fetchImpl,
+					signal,
+				)) as unknown;
+				const parsedBase = new URL(base);
+				if (parsedBase.pathname.replace(/\/+$/, "") === "/v1") parsedBase.pathname = "/";
+				let tokenData: Record<string, unknown> | undefined;
+				try {
+					const tokenUsage = (await requestJson(
+						resolveSameOriginEndpoint(parsedBase.toString(), "/api/usage/token/"),
+						token,
+						fetchImpl,
+						signal,
+					)) as unknown;
+					tokenData = isRecord(tokenUsage) && isRecord(tokenUsage.data) ? tokenUsage.data : undefined;
+				} catch {
+					// Optional endpoint; the dashboard pair alone often suffices.
+				}
+				const rawTotal = numberAt(subscription, ["hard_limit_usd"], ["soft_limit_usd"], ["system_hard_limit_usd"]);
+				const dashboardUsed = numberAt(usage, ["total_usage"]);
+				const usedFromDashboard = dashboardUsed === undefined ? undefined : dashboardUsed / 100;
+				const unlimited = tokenData?.unlimited_quota === true || rawTotal === 100_000_000;
+				const tokenTotal = toNumber(tokenData?.total_granted);
+				const tokenRemaining = toNumber(tokenData?.total_available);
+				const total = tokenTotal ?? (unlimited ? undefined : rawTotal);
+				const used =
+					tokenTotal !== undefined && tokenRemaining !== undefined
+						? Math.max(0, tokenTotal - tokenRemaining)
+						: usedFromDashboard;
+				const remaining =
+					tokenRemaining ?? (total !== undefined && used !== undefined ? Math.max(0, total - used) : undefined);
+				if (remaining === undefined && !unlimited) {
+					throw new Error("response has no quota values");
+				}
+				const notes: string[] = [];
+				if (unlimited) notes.push("unlimited quota");
+				if (used !== undefined && total !== undefined && !unlimited) {
+					notes.push(`used $${used.toFixed(2)} of $${total.toFixed(2)}`);
+				}
+				return { balance: { amount: remaining ?? 0, currency: "USD" }, windows: [], notes };
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+			}
+		}
+		throw lastError ?? new Error("endpoints not found");
+	},
+};
+
+const sub2apiCandidate: Candidate = {
+	name: "sub2api",
+	async run({ baseUrl, token, signal, fetchImpl }) {
+		let lastError: Error | undefined;
+		for (const base of baseUrlCandidates(baseUrl)) {
+			try {
+				const payload = (await requestJson(resolveSameOriginEndpoint(base, "usage"), token, fetchImpl, signal)) as unknown;
+				if (!isRecord(payload)) throw new Error("invalid response");
+				const total = numberAt(payload, ["quota", "limit"], ["total"]);
+				const used = numberAt(payload, ["quota", "used"], ["used"]);
+				const remaining =
+					numberAt(payload, ["remaining"], ["balance"], ["quota", "remaining"]) ??
+					(total !== undefined && used !== undefined ? Math.max(0, total - used) : undefined);
+				if (remaining === undefined) throw new Error("response has no balance");
+				const currency = stringAt(payload, ["unit"], ["quota", "unit"]) ?? "USD";
+				const notes: string[] = [];
+				if (used !== undefined && total !== undefined) notes.push(`used ${used} of ${total}`);
+				return { balance: { amount: remaining, currency }, windows: [], notes };
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+			}
+		}
+		throw lastError ?? new Error("endpoint not found");
+	},
+};
+
+function hostnameCandidates(baseUrl: string): Candidate[] {
+	let hostname = "";
+	try {
+		hostname = new URL(baseUrl).hostname.toLowerCase();
+	} catch {
+		return [newApiCandidate, sub2apiCandidate];
+	}
+	const candidates: Candidate[] = [];
+	if (hostname === "api.deepseek.com") candidates.push(deepseekCandidate);
+	if (["api.minimaxi.com", "www.minimaxi.com", "api.minimax.io", "www.minimax.io"].includes(hostname)) {
+		candidates.push(minimaxCandidate);
+	}
+	if (["open.bigmodel.cn", "bigmodel.cn", "api.z.ai", "z.ai"].includes(hostname)) candidates.push(zhipuCandidate);
+	candidates.push(newApiCandidate, sub2apiCandidate);
+	return candidates;
+}
+
+function isTransientError(message: string): boolean {
+	return /fetch failed|ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket|network|aborted|timed? ?out/i.test(message);
+}
+
+/**
+ * Build the auto-detecting adapter for one provider id. Detection runs on the
+ * first fetch; the winning candidate is pinned for the session, as is an
+ * exhausted "not supported" outcome. Transient network errors are not pinned.
+ */
+export function createAutoDetectAdapter(id: string): ProviderAdapter {
+	let winner: Candidate | undefined;
+	let pinnedError: string | undefined;
+
+	return {
+		id,
+		label: id,
+		async fetch(args: ProviderFetchArgs): Promise<AccountBalance> {
+			if (pinnedError) throw new Error(pinnedError);
+			if (!args.baseUrl) {
+				throw new Error(`Base URL for "${id}" is unknown; cannot auto-detect a balance endpoint`);
+			}
+			const context: CandidateContext = {
+				baseUrl: args.baseUrl,
+				token: args.token,
+				signal: args.signal,
+				fetchImpl: args.fetchImpl,
+			};
+			const finalize = (balance: Omit<AccountBalance, "providerId" | "label" | "fetchedAt">): AccountBalance => ({
+				...balance,
+				providerId: id,
+				label: id,
+				fetchedAt: Date.now(),
+			});
+			if (winner) {
+				return finalize(await winner.run(context));
+			}
+			const errors: string[] = [];
+			let sawTransient = false;
+			for (const candidate of hostnameCandidates(args.baseUrl)) {
+				try {
+					const balance = await candidate.run(context);
+					winner = candidate;
+					return finalize(balance);
+				} catch (error) {
+					if (args.signal?.aborted) throw error;
+					const message = error instanceof Error ? error.message : String(error);
+					if (isTransientError(message)) sawTransient = true;
+					errors.push(`${candidate.name}: ${message}`);
+				}
+			}
+			const summary = `no balance endpoint detected (${errors.join("; ")})`;
+			if (!sawTransient) pinnedError = summary;
+			throw new Error(summary);
+		},
+	};
+}

package/src/providers/codex.ts

@@ -0,0 +1,81 @@
+/**
+ * OpenAI Codex (ChatGPT subscription) adapter.
+ *
+ * Query method borrowed from CodexBar: the ChatGPT OAuth access token stored
+ * by pi in auth.json is accepted by the backend usage endpoint.
+ */
+
+import type { AccountBalance, ProviderAdapter, ProviderFetchArgs, UsageWindow } from "../types.ts";
+
+const ENDPOINT = "https://chatgpt.com/backend-api/wham/usage";
+
+interface CodexWindow {
+	used_percent?: unknown;
+	reset_at?: unknown;
+	limit_window_seconds?: unknown;
+}
+
+interface CodexUsageResponse {
+	plan_type?: unknown;
+	rate_limit?: { primary_window?: unknown; secondary_window?: unknown } | null;
+	credits?: { balance?: unknown } | null;
+	spend_control?: { individual_limit?: unknown } | null;
+}
+
+function windowLabel(limitWindowSeconds: number): string {
+	if (limitWindowSeconds === 18_000) return "5h";
+	if (limitWindowSeconds === 604_800) return "weekly";
+	const hours = Math.round(limitWindowSeconds / 3_600);
+	return hours > 0 ? `${hours}h` : `${limitWindowSeconds}s`;
+}
+
+function parseWindow(fallbackLabel: string, raw: unknown): UsageWindow | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const window = raw as CodexWindow;
+	if (typeof window.used_percent !== "number") return undefined;
+	const label = typeof window.limit_window_seconds === "number" ? windowLabel(window.limit_window_seconds) : fallbackLabel;
+	const resetsAt = typeof window.reset_at === "number" ? window.reset_at * 1000 : undefined;
+	return { label, usedPercent: window.used_percent, resetsAt };
+}
+
+/** Accept numbers or numeric strings ("0" from credits.balance). */
+function money(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
+	return undefined;
+}
+
+export const codexAdapter: ProviderAdapter = {
+	id: "openai-codex",
+	label: "Codex",
+	async fetch({ token, signal, fetchImpl }: ProviderFetchArgs): Promise<AccountBalance> {
+		const response = await fetchImpl(ENDPOINT, {
+			headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+			signal,
+		});
+		if (!response.ok) {
+			throw new Error(`Codex usage API returned HTTP ${response.status}`);
+		}
+		const body: unknown = await response.json();
+		if (typeof body !== "object" || body === null) {
+			throw new Error("Codex usage API returned an unexpected response");
+		}
+		const usage = body as CodexUsageResponse;
+		const windows: UsageWindow[] = [];
+		const primary = parseWindow("5h", usage.rate_limit?.primary_window);
+		if (primary) windows.push(primary);
+		const secondary = parseWindow("weekly", usage.rate_limit?.secondary_window);
+		if (secondary) windows.push(secondary);
+		const notes: string[] = [];
+		const credits = money(usage.credits?.balance);
+		if (credits !== undefined && credits > 0) notes.push(`$${credits.toFixed(2)} credits`);
+		const spendCap = money(usage.spend_control?.individual_limit);
+		if (spendCap !== undefined && spendCap > 0) notes.push(`monthly spend cap $${spendCap.toFixed(2)}`);
+		const planType = typeof usage.plan_type === "string" ? usage.plan_type : undefined;
+		const plan = planType ? planType.charAt(0).toUpperCase() + planType.slice(1) : undefined;
+		if (windows.length === 0) {
+			throw new Error("Codex usage API returned no rate limit windows");
+		}
+		return { providerId: "openai-codex", label: "Codex", plan, windows, notes, fetchedAt: Date.now() };
+	},
+};

package/src/providers/custom.ts

@@ -0,0 +1,100 @@
+/**
+ * Config-driven generic adapter: reads an arbitrary JSON endpoint and extracts
+ * a monetary balance and/or usage windows via dot paths. Used for providers
+ * without a built-in adapter (e.g. self-hosted relays).
+ */
+
+import type { CustomProviderConfig } from "../config.ts";
+import { resolveConfigValue } from "../credentials.ts";
+import type { AccountBalance, MoneyBalance, ProviderAdapter, ProviderFetchArgs, UsageWindow } from "../types.ts";
+
+/**
+ * Resolve "data.list[0].percent"-style paths. Bracket suffixes index into
+ * arrays; missing segments yield undefined.
+ */
+export function dotPath(root: unknown, path: string): unknown {
+	let current: unknown = root;
+	for (const segment of path.split(".")) {
+		if (typeof current !== "object" || current === null) return undefined;
+		const bracket = /^([^\[\]]+)\[(\d+)\]$/u.exec(segment);
+		const container = current as Record<string, unknown>;
+		if (bracket) {
+			const key = bracket[1];
+			const index = bracket[2];
+			if (!key || index === undefined) return undefined;
+			const array = container[key];
+			if (!Array.isArray(array)) return undefined;
+			current = array[Number(index)];
+			continue;
+		}
+		current = container[segment];
+	}
+	return current;
+}
+
+function toNumber(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
+	return undefined;
+}
+
+function toEpoch(value: unknown): number | undefined {
+	const number = toNumber(value);
+	if (number === undefined) return undefined;
+	return number < 1e12 ? number * 1000 : number;
+}
+
+function buildHeaders(custom: CustomProviderConfig, token: string): Record<string, string> {
+	const headers: Record<string, string> = {};
+	for (const [name, value] of Object.entries(custom.headers ?? {})) {
+		// "{token}" pulls in the provider's own auth.json credential, if any.
+		const resolved = resolveConfigValue(value.replaceAll("{token}", token));
+		if (resolved !== undefined) headers[name] = resolved;
+	}
+	return headers;
+}
+
+export function createCustomAdapter(id: string, custom: CustomProviderConfig, fallbackLabel: string): ProviderAdapter {
+	return {
+		id,
+		label: fallbackLabel,
+		async fetch({ token, signal, fetchImpl }: ProviderFetchArgs): Promise<AccountBalance> {
+			const response = await fetchImpl(custom.url, {
+				method: custom.method ?? "GET",
+				headers: { Accept: "application/json", ...buildHeaders(custom, token) },
+				signal,
+			});
+			if (!response.ok) {
+				throw new Error(`${id} returned HTTP ${response.status}`);
+			}
+			const body: unknown = await response.json();
+			let balance: MoneyBalance | undefined;
+			if (custom.balancePath) {
+				const amount = toNumber(dotPath(body, custom.balancePath));
+				if (amount !== undefined) balance = { amount, currency: custom.currency ?? "USD" };
+			}
+			const windows: UsageWindow[] = [];
+			if (custom.windowsPath) {
+				const rawWindows = dotPath(body, custom.windowsPath);
+				if (Array.isArray(rawWindows)) {
+					const fields = { label: "label", percent: "percent", resetsAt: "resetsAt", ...custom.windowFields };
+					rawWindows.forEach((entry, index) => {
+						const percent = toNumber(dotPath(entry, fields.percent ?? "percent"));
+						if (percent === undefined) return;
+						const label = dotPath(entry, fields.label ?? "label");
+						const resetsAt = toEpoch(dotPath(entry, fields.resetsAt ?? "resetsAt"));
+						windows.push({
+							label: typeof label === "string" && label ? label : `w${index + 1}`,
+							usedPercent: percent,
+							resetsAt,
+						});
+					});
+				}
+			}
+			if (!balance && windows.length === 0) {
+				throw new Error(`${id}: no balance or windows extracted (check balancePath/windowsPath)`);
+			}
+			return { providerId: id, label: fallbackLabel, windows, balance, notes: [], fetchedAt: Date.now() };
+		},
+	};
+}

package/src/providers/deepseek.ts

@@ -0,0 +1,68 @@
+/**
+ * DeepSeek adapter: prepaid account balance via the public balance endpoint.
+ */
+
+import type { AccountBalance, ProviderAdapter, ProviderFetchArgs } from "../types.ts";
+
+const ENDPOINT = "https://api.deepseek.com/user/balance";
+
+interface DeepseekBalanceInfo {
+	currency?: unknown;
+	total_balance?: unknown;
+	granted_balance?: unknown;
+	topped_up_balance?: unknown;
+}
+
+interface DeepseekBalanceResponse {
+	is_available?: unknown;
+	balance_infos?: unknown;
+}
+
+function parseAmount(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
+	return undefined;
+}
+
+export const deepseekAdapter: ProviderAdapter = {
+	id: "deepseek",
+	label: "DeepSeek",
+	async fetch({ token, signal, fetchImpl }: ProviderFetchArgs): Promise<AccountBalance> {
+		const response = await fetchImpl(ENDPOINT, {
+			headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+			signal,
+		});
+		if (!response.ok) {
+			throw new Error(`DeepSeek balance API returned HTTP ${response.status}`);
+		}
+		const body: unknown = await response.json();
+		if (typeof body !== "object" || body === null) {
+			throw new Error("DeepSeek balance API returned an unexpected response");
+		}
+		const parsed = body as DeepseekBalanceResponse;
+		if (!Array.isArray(parsed.balance_infos)) {
+			throw new Error("DeepSeek balance API returned no balance_infos");
+		}
+		const first = parsed.balance_infos.find((entry): entry is DeepseekBalanceInfo => typeof entry === "object" && entry !== null);
+		if (!first) {
+			throw new Error("DeepSeek balance API returned an empty balance_infos list");
+		}
+		const amount = parseAmount(first.total_balance);
+		if (amount === undefined) {
+			throw new Error("DeepSeek balance API returned no usable total_balance");
+		}
+		const currency = typeof first.currency === "string" && first.currency ? first.currency : "CNY";
+		const notes: string[] = [];
+		const granted = parseAmount(first.granted_balance);
+		if (granted !== undefined && granted > 0) notes.push(`granted ${currency} ${granted.toFixed(2)}`);
+		if (parsed.is_available === false) notes.push("account unavailable");
+		return {
+			providerId: "deepseek",
+			label: "DeepSeek",
+			balance: { amount, currency },
+			windows: [],
+			notes,
+			fetchedAt: Date.now(),
+		};
+	},
+};

package/src/providers/github-copilot.ts

@@ -0,0 +1,101 @@
+/**
+ * GitHub Copilot adapter.
+ *
+ * Query method borrowed from CodexBar: the GitHub OAuth token stored by pi
+ * (k Copilot's device-flow login) is accepted directly by the internal user
+ * endpoint, no Copilot token exchange needed.
+ */
+
+import { parseTimestamp, toNumber } from "../parse.ts";
+import type { AccountBalance, ProviderAdapter, ProviderFetchArgs, UsageWindow } from "../types.ts";
+
+const ENDPOINT = "https://github.com/copilot_internal/user";
+
+const REQUEST_HEADERS = {
+	Accept: "application/json",
+	"Editor-Version": "vscode/1.96.2",
+	"Editor-Plugin-Version": "copilot-chat/0.26.7",
+	"X-Github-Api-Version": "2025-04-01",
+} as const;
+
+interface CopilotSnapshot {
+	entitlement?: unknown;
+	remaining?: unknown;
+	percent_remaining?: unknown;
+	unlimited?: unknown;
+}
+
+interface CopilotUsageResponse {
+	quota_snapshots?: unknown;
+	copilot_plan?: unknown;
+	quota_reset_date?: unknown;
+}
+
+/** Short display labels for the known snapshot keys. */
+const SNAPSHOT_LABELS: Record<string, string> = {
+	premium_interactions: "premium",
+	chat: "chat",
+	embeddings: "embeddings",
+};
+
+function snapshotLabel(key: string): string {
+	return SNAPSHOT_LABELS[key] ?? key.replaceAll("_", " ");
+}
+
+function parseSnapshot(key: string, raw: unknown): UsageWindow | undefined {
+	if (typeof raw !== "object" || raw === null) return undefined;
+	const snapshot = raw as CopilotSnapshot;
+	const label = snapshotLabel(key);
+	if (snapshot.unlimited === true) {
+		return { label, usedPercent: 0, detail: "unlimited" };
+	}
+	const percentRemaining = toNumber(snapshot.percent_remaining);
+	if (percentRemaining === undefined) return undefined;
+	const entitlement = toNumber(snapshot.entitlement);
+	const remaining = toNumber(snapshot.remaining);
+	// Placeholder shape: GitHub reports all-zero rows for token-based billing
+	// and some business seats; they carry no usable quota signal.
+	if (entitlement === 0 && remaining === 0) return undefined;
+	return { label, usedPercent: Math.max(0, 100 - percentRemaining) };
+}
+
+export const githubCopilotAdapter: ProviderAdapter = {
+	id: "github-copilot",
+	label: "Copilot",
+	async fetch({ token, signal, fetchImpl }: ProviderFetchArgs): Promise<AccountBalance> {
+		const response = await fetchImpl(ENDPOINT, {
+			headers: { Authorization: `token ${token}`, ...REQUEST_HEADERS },
+			signal,
+		});
+		if (!response.ok) {
+			throw new Error(`Copilot usage API returned HTTP ${response.status}`);
+		}
+		const body: unknown = await response.json();
+		if (typeof body !== "object" || body === null) {
+			throw new Error("Copilot usage API returned an unexpected response");
+		}
+		const usage = body as CopilotUsageResponse;
+		if (typeof usage.quota_snapshots !== "object" || usage.quota_snapshots === null) {
+			throw new Error("Copilot usage API returned no quota snapshots");
+		}
+		const snapshots = usage.quota_snapshots as Record<string, unknown>;
+		const windows = Object.entries(snapshots)
+			.map(([key, value]) => parseSnapshot(key, value))
+			.filter((window): window is UsageWindow => window !== undefined);
+		if (windows.length === 0) {
+			throw new Error("Copilot usage API returned no usable quota snapshots");
+		}
+		const planRaw = typeof usage.copilot_plan === "string" ? usage.copilot_plan : undefined;
+		const plan = planRaw
+			? planRaw
+					.split("_")
+					.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+					.join(" ")
+			: undefined;
+		const quotaResetDate = parseTimestamp(usage.quota_reset_date);
+		for (const window of windows) {
+			window.resetsAt ??= quotaResetDate;
+		}
+		return { providerId: "github-copilot", label: "Copilot", plan, windows, notes: [], fetchedAt: Date.now() };
+	},
+};