@astrosheep/pi-quota 0.12.0 → 0.12.2

package/dist/query/sub2api.js

@@ -0,0 +1,132 @@
+import { bearer } from "./http.js";
+import { numeric, object, percent, timestamp } from "./parse.js";
+import { QuotaError } from "./types.js";
+import { safeBaseUrl } from "./url.js";
+export function sub2ApiUsageUrl(baseUrl) {
+    const url = safeBaseUrl(baseUrl);
+    // Anthropic clients use the host root; OpenAI clients include /v1.
+    const prefix = url.pathname.replace(/\/+$/, '') || '/v1';
+    url.pathname = `${prefix}/usage`;
+    return url.toString();
+}
+function currency(value) {
+    if (typeof value !== 'string' || !/^[A-Z]{3}$/.test(value))
+        throw new QuotaError('schema');
+    return value;
+}
+function amount(value) {
+    const result = numeric(value);
+    if (result === null || result < 0)
+        throw new QuotaError('schema');
+    return result;
+}
+function allowance(data, unit) {
+    const limit = amount(data.limit);
+    if (limit === 0)
+        throw new QuotaError('schema');
+    const used = amount(data.used);
+    const remaining = amount(data.remaining);
+    return { currency: unit, limit, used, remaining };
+}
+function spend(data, unit) {
+    const today = object(data.today);
+    const total = object(data.total);
+    const todayCost = numeric(today.actual_cost);
+    const lifetimeCost = numeric(total.actual_cost);
+    if (todayCost === null && lifetimeCost === null)
+        return undefined;
+    if ((todayCost !== null && todayCost < 0) || (lifetimeCost !== null && lifetimeCost < 0))
+        throw new QuotaError('schema');
+    return { currency: unit, ...(todayCost !== null ? { today: todayCost } : {}),
+        ...(lifetimeCost !== null ? { lifetime: lifetimeCost } : {}) };
+}
+function percentFromAmounts(remaining, limit) {
+    return percent(remaining / limit * 100);
+}
+const RATE_WINDOWS = { '5h': 18000, '1d': 86400, '7d': 604800 };
+function rateWindow(data, unit) {
+    const label = data.window;
+    if (typeof label !== 'string' || !Object.hasOwn(RATE_WINDOWS, label))
+        throw new QuotaError('schema');
+    const limits = allowance(data, unit);
+    return { id: `rate-${label}`, label, durationSeconds: RATE_WINDOWS[label],
+        remainingPercent: percentFromAmounts(limits.remaining, limits.limit),
+        resetAt: timestamp(data.reset_at), amounts: limits };
+}
+function subscriptionWindows(data, unit) {
+    const specs = [
+        ['daily', '1d', 'daily_usage_usd', 'daily_limit_usd', 86400],
+        ['weekly', '1w', 'weekly_usage_usd', 'weekly_limit_usd', 604800],
+        ['monthly', '30d', 'monthly_usage_usd', 'monthly_limit_usd', 2592000],
+    ];
+    return specs.flatMap(([id, label, usedKey, limitKey, durationSeconds]) => {
+        if (data[limitKey] == null)
+            return []; // Upstream sends null for an unconfigured cap.
+        const limit = numeric(data[limitKey]);
+        if (limit === null || limit < 0)
+            throw new QuotaError('schema');
+        if (limit === 0)
+            return []; // No cap for this period; no percentage can be computed.
+        const used = numeric(data[usedKey]);
+        if (used === null || used < 0)
+            throw new QuotaError('schema');
+        const amounts = { currency: unit, limit, used, remaining: Math.max(0, limit - used) };
+        const start = id === 'weekly' ? timestamp(data.weekly_window_start) : null;
+        return [{ id, label, durationSeconds, remainingPercent: percentFromAmounts(amounts.remaining, limit),
+                resetAt: start === null ? null : start + durationSeconds * 1000, amounts }];
+    });
+}
+export function parseSub2ApiUsage(payload) {
+    const body = object(payload);
+    if (body.isValid !== true || (body.mode !== 'quota_limited' && body.mode !== 'unrestricted')) {
+        throw new QuotaError('schema');
+    }
+    // Upstream omits `unit` when a key has rate limits but no total quota.
+    // Sub2API rate limits are always USD; a fixed quota carries its own unit.
+    const unit = currency(body.unit ?? (body.mode === 'quota_limited'
+        ? object(body.quota).unit ?? 'USD' : undefined));
+    const windows = [];
+    let balance;
+    let finiteQuota;
+    if (body.mode === 'quota_limited') {
+        const quota = body.quota === undefined ? undefined : allowance(object(body.quota), unit);
+        finiteQuota = quota;
+        const rates = body.rate_limits;
+        if (rates !== undefined) {
+            if (!Array.isArray(rates))
+                throw new QuotaError('schema');
+            rates.forEach(entry => windows.push(rateWindow(object(entry), unit)));
+        }
+    }
+    else if (body.subscription !== undefined) {
+        windows.push(...subscriptionWindows(object(body.subscription), unit));
+    }
+    else {
+        const remaining = amount(body.remaining ?? body.balance);
+        balance = { currency: unit, remaining };
+    }
+    const usage = spend(object(body.usage), unit);
+    if (windows.length === 0 && !balance && !finiteQuota)
+        throw new QuotaError('schema');
+    return { windows, ...(balance ? { balance } : {}), ...(finiteQuota ? { allowance: finiteQuota } : {}),
+        ...(usage ? { spend: usage } : {}) };
+}
+export function createSub2ApiAdapter(provider) {
+    return {
+        provider, label: provider,
+        async query(context) {
+            let auth;
+            try {
+                auth = await context.getAuth(context.provider);
+            }
+            catch {
+                throw new QuotaError('auth');
+            }
+            context.signal.throwIfAborted();
+            if (!auth)
+                throw new QuotaError('auth');
+            const payload = await context.getJson(sub2ApiUsageUrl(auth.baseUrl), { Authorization: `Bearer ${bearer(auth)}` }, context.signal);
+            return { ...parseSub2ApiUsage(payload), fetchedAt: context.now() };
+        },
+    };
+}

package/dist/query/types.d.ts

@@ -0,0 +1,77 @@
+export interface QuotaWindow {
+    id: string;
+    label: string;
+    remainingPercent: number | null;
+    resetAt: number | null;
+    durationSeconds: number;
+    scope?: string;
+    amounts?: QuotaAllowance;
+}
+export interface AccountBalance {
+    currency: string;
+    remaining: number;
+    unlimited?: boolean;
+}
+export interface QuotaAllowance {
+    currency: string;
+    limit: number;
+    used: number;
+    remaining: number;
+}
+export interface SpendSummary {
+    currency: string;
+    today?: number;
+    lifetime?: number;
+}
+export interface QuotaSnapshot {
+    windows: readonly QuotaWindow[];
+    balance?: AccountBalance;
+    allowance?: QuotaAllowance;
+    spend?: SpendSummary;
+    fetchedAt: number;
+}
+export interface ProviderAuth {
+    apiKey?: string;
+    headers?: Record<string, string | undefined>;
+    baseUrl?: string;
+}
+export interface PostJsonResult {
+    body: unknown;
+    setCookie: string[];
+}
+export interface QueryContext {
+    provider: string;
+    signal: AbortSignal;
+    now(): number;
+    getAuth(provider: string): Promise<ProviderAuth | undefined>;
+    getJson(url: string, headers: Record<string, string>, signal: AbortSignal): Promise<unknown>;
+    postJson(url: string, body: unknown, headers: Record<string, string>, signal: AbortSignal): Promise<PostJsonResult>;
+}
+export interface QuotaAdapter {
+    provider: string;
+    label: string;
+    query(context: QueryContext): Promise<QuotaSnapshot>;
+}
+export type QuotaErrorCode = 'auth' | 'unsupported-auth' | 'account-access' | 'network' | 'timeout' | 'rate-limit' | 'http' | 'schema';
+export declare class QuotaError extends Error {
+    readonly code: QuotaErrorCode;
+    readonly retryAfterMs?: number;
+    constructor(code: QuotaErrorCode, retryAfterMs?: number);
+}
+export type QuotaState = {
+    kind: 'hidden';
+} | {
+    kind: 'loading';
+    provider: string;
+    label: string;
+} | {
+    kind: 'ready';
+    provider: string;
+    label: string;
+    snapshot: QuotaSnapshot;
+} | {
+    kind: 'error';
+    provider: string;
+    label: string;
+    code: QuotaErrorCode;
+};

package/dist/query/types.js

@@ -0,0 +1,9 @@
+export class QuotaError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, retryAfterMs) {
+        super(code); // Never include response bodies, request headers, or raw exceptions.
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}

package/dist/query/url.d.ts

@@ -0,0 +1 @@
+export declare function safeBaseUrl(baseUrl: string | undefined): URL;

package/dist/query/url.js

@@ -0,0 +1,19 @@
+import { QuotaError } from "./types.js";
+// Validate a model endpoint before deriving any authenticated quota URL.
+// Never accept redirects (see http.ts) or move credentials to another origin.
+export function safeBaseUrl(baseUrl) {
+    if (!baseUrl)
+        throw new QuotaError('unsupported-auth');
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new QuotaError('unsupported-auth');
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+        || url.username || url.password || url.search || url.hash)
+        throw new QuotaError('unsupported-auth');
+    return url;
+}

package/dist/query/yescode.d.ts

@@ -0,0 +1,15 @@
+import type { PostJsonResult, QuotaAdapter, QuotaSnapshot } from './types.js';
+export declare const YESCODE_ORIGIN = "https://co.yes.vg";
+export interface YesCodeOptions {
+    username: string;
+    password: string;
+}
+interface YesCodeSession {
+    headers: Record<string, string>;
+    expiresAt: number;
+}
+export declare function validateYesCodeOptions(options: YesCodeOptions): YesCodeOptions;
+export declare function parseYesCodeLogin(result: PostJsonResult, now: number): YesCodeSession;
+export declare function parseYesCodeAccount(balancePayload: unknown, profilePayload: unknown): Omit<QuotaSnapshot, 'fetchedAt'>;
+export declare function createYesCodeAdapter(provider: string, options: YesCodeOptions): QuotaAdapter;
+export {};

package/dist/query/yescode.js

@@ -0,0 +1,155 @@
+import { officialAuth } from "./http.js";
+import { numeric, object, percent, timestamp, windowLabel } from "./parse.js";
+import { QuotaError } from "./types.js";
+export const YESCODE_ORIGIN = 'https://co.yes.vg';
+const SESSION_TTL_MS = 23 * 3600 * 1000; // observed cookie Max-Age is 24h
+export function validateYesCodeOptions(options) {
+    const { username, password } = options;
+    if (typeof username !== 'string' || username.trim() === '') {
+        throw new Error('username must be a non-empty string');
+    }
+    if (typeof password !== 'string' || password === '')
+        throw new Error('password must be a non-empty string');
+    return { username, password };
+}
+function cookieValue(setCookie, name) {
+    for (const entry of setCookie) {
+        if (!entry.startsWith(`${name}=`))
+            continue;
+        const value = entry.slice(name.length + 1).split(';', 1)[0];
+        if (value !== '' && !/[\s;]/.test(value))
+            return value;
+    }
+    return undefined;
+}
+// POST /api/v1/auth/login returns {token} and sets yescode_auth/yescode_csrf.
+// The cookie pair is what the web app itself uses; the bare JWT is the
+// documented UserToken fallback (Authorization: Bearer).
+export function parseYesCodeLogin(result, now) {
+    const auth = cookieValue(result.setCookie, 'yescode_auth');
+    if (auth) {
+        const csrf = cookieValue(result.setCookie, 'yescode_csrf');
+        return { headers: { Cookie: csrf ? `yescode_auth=${auth}; yescode_csrf=${csrf}` : `yescode_auth=${auth}` },
+            expiresAt: now + SESSION_TTL_MS };
+    }
+    const token = object(result.body).token;
+    if (typeof token !== 'string' || token.trim() === '' || /[\s;]/.test(token))
+        throw new QuotaError('schema');
+    return { headers: { Authorization: `Bearer ${token}` }, expiresAt: now + SESSION_TTL_MS };
+}
+// Balances may legitimately be negative (debt); limits/spends may not.
+function optionalAmount(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const result = numeric(value);
+    if (result === null)
+        throw new QuotaError('schema');
+    return result;
+}
+function nonNegative(value) {
+    const result = optionalAmount(value);
+    if (result !== undefined && result < 0)
+        throw new QuotaError('schema');
+    return result;
+}
+function limitWindow(id, label, durationSeconds, limitRaw, usedRaw, resetAt) {
+    const used = nonNegative(usedRaw); // validate present-but-corrupt spends even without a cap
+    const limit = nonNegative(limitRaw);
+    if (limit === undefined || limit === 0)
+        return []; // no configured cap: nothing to draw
+    if (used === undefined) {
+        return [{ id, label, durationSeconds, remainingPercent: null, resetAt }];
+    }
+    const remaining = Math.max(0, limit - used);
+    return [{ id, label, durationSeconds, remainingPercent: percent(remaining / limit * 100), resetAt,
+            amounts: { currency: 'USD', limit, used, remaining } }];
+}
+// GET /api/v1/user/balance (optional; some accounts may lack it) merged with
+// GET /api/v1/auth/profile (required). The live response carries a generic
+// spending_limits array (scope/spent/limit/remaining/resets_at/window_seconds)
+// plus top-level weekly_* and monthly_* fields; profile is the last fallback.
+function spendingLimitWindows(balanceData) {
+    if (balanceData.spending_limits === undefined)
+        return null;
+    if (!Array.isArray(balanceData.spending_limits))
+        throw new QuotaError('schema');
+    const windows = balanceData.spending_limits.flatMap((entry) => {
+        const item = object(entry);
+        const limit = nonNegative(item.limit);
+        const spent = nonNegative(item.spent);
+        const remaining = nonNegative(item.remaining);
+        const windowSeconds = numeric(item.window_seconds);
+        const resetAt = timestamp(item.resets_at);
+        if (typeof item.key !== 'string' || item.key === ''
+            || windowSeconds === null || !Number.isSafeInteger(windowSeconds) || windowSeconds <= 0) {
+            throw new QuotaError('schema');
+        }
+        if (limit === undefined || limit === 0)
+            return []; // uncapped: nothing to draw
+        if (spent === undefined) {
+            return [{ id: `spending:${item.key}`, label: windowLabel(windowSeconds), durationSeconds: windowSeconds,
+                    remainingPercent: null, resetAt }];
+        }
+        const left = remaining ?? Math.max(0, limit - spent);
+        return [{ id: `spending:${item.key}`, label: windowLabel(windowSeconds), durationSeconds: windowSeconds,
+                remainingPercent: percent(left / limit * 100), resetAt,
+                amounts: { currency: 'USD', limit, used: spent, remaining: left } }];
+    });
+    // Footer/detail convention is ascending duration (5h → 1w → 30d).
+    return windows.sort((a, b) => a.durationSeconds - b.durationSeconds);
+}
+export function parseYesCodeAccount(balancePayload, profilePayload) {
+    const balanceData = object(balancePayload);
+    const profile = object(profilePayload);
+    const plan = object(profile.subscription_plan);
+    const subscription = optionalAmount(balanceData.subscription_balance ?? profile.subscription_balance);
+    const paygo = optionalAmount(balanceData.pay_as_you_go_balance ?? profile.pay_as_you_go_balance);
+    if (subscription === undefined && paygo === undefined)
+        throw new QuotaError('schema');
+    const weekStart = timestamp(profile.last_week_reset);
+    const monthStart = timestamp(profile.last_month_reset);
+    const windows = spendingLimitWindows(balanceData) ?? [
+        ...limitWindow('daily', '1d', 86400, balanceData.daily_limit, balanceData.daily_spent, timestamp(balanceData.daily_resets_at ?? balanceData.daily_reset_at)),
+        ...limitWindow('weekly', '1w', 604800, balanceData.weekly_limit ?? plan.weekly_limit, balanceData.weekly_spent_balance ?? balanceData.weekly_spent ?? profile.current_week_spend, timestamp(balanceData.weekly_resets_at ?? balanceData.weekly_reset_at)
+            ?? (weekStart === null ? null : weekStart + 604800000)),
+        ...limitWindow('monthly', '30d', 2592000, balanceData.monthly_spend_limit ?? plan.monthly_spend_limit, balanceData.monthly_spent_balance ?? balanceData.monthly_spent ?? profile.current_month_spend, timestamp(balanceData.monthly_resets_at ?? balanceData.monthly_reset_at)
+            ?? (monthStart === null ? null : monthStart + 2592000000)),
+    ];
+    return { windows, balance: { currency: 'USD', remaining: (subscription ?? 0) + (paygo ?? 0) } };
+}
+export function createYesCodeAdapter(provider, options) {
+    const credentials = validateYesCodeOptions(options);
+    let session;
+    return {
+        provider, label: provider,
+        async query(context) {
+            await officialAuth(context, YESCODE_ORIGIN);
+            const login = async () => parseYesCodeLogin(await context.postJson(`${YESCODE_ORIGIN}/api/v1/auth/login`, { username: credentials.username, password: credentials.password }, { Origin: YESCODE_ORIGIN, Referer: `${YESCODE_ORIGIN}/login` }, context.signal), context.now());
+            const fetchAccount = async (current) => {
+                const [profile, balance] = await Promise.all([
+                    context.getJson(`${YESCODE_ORIGIN}/api/v1/auth/profile`, current.headers, context.signal),
+                    // Optional endpoint: a plain 404 must not fail the whole query.
+                    context.getJson(`${YESCODE_ORIGIN}/api/v1/user/balance`, current.headers, context.signal)
+                        .catch((error) => {
+                        if (error instanceof QuotaError && error.code === 'http')
+                            return undefined;
+                        throw error;
+                    }),
+                ]);
+                return parseYesCodeAccount(balance, profile);
+            };
+            if (!session || context.now() >= session.expiresAt)
+                session = await login();
+            try {
+                return { ...await fetchAccount(session), fetchedAt: context.now() };
+            }
+            catch (error) {
+                // Session died early (24h cookie or revocation): re-login once, then give up.
+                if (!(error instanceof QuotaError) || error.code !== 'auth')
+                    throw error;
+                session = await login();
+                return { ...await fetchAccount(session), fetchedAt: context.now() };
+            }
+        },
+    };
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@astrosheep/pi-quota",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./query": "./src/query/index.ts",
+    "./query": {
+      "types": "./dist/query/index.d.ts",
+      "default": "./dist/query/index.js"
+    },
     "./package.json": "./package.json"
   },
   "description": "Composable quota bar with Codex, Kimi, OpenCode Go, new-api, DeepSeek, Sub2API and YesCode adapters",
@@ -16,6 +19,7 @@
   ],
   "files": [
     "src",
+    "dist",
     "examples",
     "README.md"
   ],
@@ -26,6 +30,8 @@
   },
   "scripts": {
     "test": "node --test test/*.test.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/fix-dist-types.mjs",
+    "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
     "demo": "node examples/preview.ts"
   },
@@ -37,8 +43,12 @@
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "@earendil-works/pi-tui": { "optional": true }
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/query/sub2api.ts

@@ -6,7 +6,9 @@ import type { AccountBalance, QuotaAdapter, QuotaAllowance, QuotaSnapshot, Quota
 
 export function sub2ApiUsageUrl(baseUrl: string | undefined): string {
   const url = safeBaseUrl(baseUrl);
-  url.pathname = `${url.pathname.replace(/\/+$/, '')}/usage`;
+  // Anthropic clients use the host root; OpenAI clients include /v1.
+  const prefix = url.pathname.replace(/\/+$/, '') || '/v1';
+  url.pathname = `${prefix}/usage`;
   return url.toString();
 }