when-does-my-quota-refresh 1.0.0

package/dist/sdk/index.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Core types for when-does-my-quota-refresh SDK
+ */
+interface QuotaSnapshot {
+    timestamp: string;
+    email?: string;
+    method: DataSource;
+    planType?: string;
+    groups: QuotaGroup[];
+    promptCredits?: PromptCreditsInfo;
+}
+interface QuotaGroup {
+    displayName: string;
+    buckets: QuotaBucket[];
+}
+interface QuotaBucket {
+    bucketId: string;
+    displayName: string;
+    description: string;
+    remainingFraction: number;
+    resetTime?: string;
+    timeUntilResetMs?: number;
+}
+interface PromptCreditsInfo {
+    available: number;
+    monthly: number;
+    usedPercentage: number;
+    remainingPercentage: number;
+}
+type DataSource = 'local' | 'cli' | 'cloud' | 'oauth';
+interface ModelQuotaInfo {
+    label: string;
+    modelId: string;
+    remainingPercentage?: number;
+    isExhausted: boolean;
+    resetTime?: string;
+    timeUntilResetMs?: number;
+    isAutocompleteOnly?: boolean;
+}
+interface AccountInfo {
+    email: string;
+    displayName?: string;
+    isActive: boolean;
+    tokenExpiresAt?: number;
+}
+interface StoredTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    email?: string;
+    projectId?: string;
+}
+interface DataSourceAdapter {
+    readonly name: DataSource;
+    readonly priority: number;
+    isAvailable(): Promise<boolean>;
+    fetchQuota(): Promise<QuotaSnapshot>;
+}
+interface Plugin {
+    name: string;
+    version: string;
+    onQuotaUpdate?: (snapshot: QuotaSnapshot) => Promise<void>;
+    onQuotaLow?: (group: string, bucket: string, remaining: number) => Promise<void>;
+    onReset?: (group: string, nextReset: Date) => Promise<void>;
+    onInit?: () => Promise<void>;
+    onDestroy?: () => Promise<void>;
+}
+interface UsageRecord {
+    timestamp: string;
+    email: string;
+    geminiWeeklyRemaining: number | null;
+    geminiSessionRemaining: number | null;
+    claudeWeeklyRemaining: number | null;
+    claudeSessionRemaining: number | null;
+}
+interface AppConfig {
+    defaultMode: DataSource;
+    cacheTtlMs: number;
+    refreshIntervalMs: number;
+    wakeupModels: string[];
+    wakeupAccounts: string[];
+    notifications: boolean;
+    plugins: string[];
+    daemon: {
+        pollIntervalMs: number;
+        enabled: boolean;
+    };
+}
+interface ClientOptions {
+    mode?: DataSource;
+    cacheTtlMs?: number;
+    verbose?: boolean;
+}
+
+/**
+ * Source registry — manages data source adapters and implements the fallback chain
+ *
+ * Priority order:
+ * 1. Local (Antigravity app language server) — fastest, offline
+ * 2. CLI (agy CLI HTTPS server) — no app needed, requires signed-in agy
+ * 3. OAuth (Google Cloud Code API) — works anywhere, requires login
+ */
+
+declare class SourceRegistry {
+    private sources;
+    private health;
+    constructor();
+    /**
+     * Register an additional data source (e.g., OAuth)
+     */
+    addSource(source: DataSourceAdapter): void;
+    /**
+     * Remove a source by name
+     */
+    removeSource(name: DataSource): void;
+    /**
+     * Fetch quota using the best available source
+     *
+     * @param preferredSource Force a specific source
+     */
+    fetchQuota(preferredSource?: DataSource): Promise<QuotaSnapshot>;
+    /**
+     * Get health status of all sources
+     */
+    getHealth(): Map<DataSource, {
+        available: boolean;
+        lastCheck: number;
+    }>;
+    /**
+     * Get registered source names
+     */
+    getSourceNames(): DataSource[];
+}
+
+/**
+ * SQLite storage for usage history and analytics
+ */
+
+/**
+ * Store a quota snapshot for history tracking
+ */
+declare function storeSnapshot(snapshot: QuotaSnapshot): void;
+/**
+ * Retrieve usage history for an account
+ */
+declare function getHistory(email: string, options?: {
+    days?: number;
+    limit?: number;
+}): UsageRecord[];
+/**
+ * Get the most recent snapshot for an account
+ */
+declare function getLatestSnapshot(email: string): UsageRecord | null;
+/**
+ * Get daily usage summary (average remaining per day)
+ */
+declare function getDailySummary(email: string, days?: number): Array<{
+    date: string;
+    geminiWeeklyAvg: number | null;
+    geminiSessionAvg: number | null;
+    claudeWeeklyAvg: number | null;
+    claudeSessionAvg: number | null;
+    count: number;
+}>;
+/**
+ * Clean up old snapshots (older than N days)
+ */
+declare function cleanupHistory(keepDays?: number): number;
+/**
+ * Close the database connection
+ */
+declare function closeStore(): void;
+
+/**
+ * Quota fetching orchestration
+ *
+ * Coordinates between the source registry, cache, storage, and plugins
+ * to provide a unified quota fetching experience.
+ */
+
+declare class QuotaClient {
+    private registry;
+    private cache;
+    private verbose;
+    constructor(options?: ClientOptions);
+    /**
+     * Fetch quota for the active account (or all accounts)
+     */
+    fetchQuota(options?: {
+        source?: DataSource;
+        refresh?: boolean;
+        allAccounts?: boolean;
+    }): Promise<QuotaSnapshot | QuotaSnapshot[]>;
+    /**
+     * Fetch quota for all stored accounts
+     */
+    private fetchAllAccounts;
+    /**
+     * Get the full dashboard data for all accounts
+     */
+    getFullDashboard(): Promise<{
+        snapshots: QuotaSnapshot[];
+        history: Record<string, UsageRecord[]>;
+        dailySummary: Record<string, ReturnType<typeof getDailySummary>>;
+    }>;
+    /**
+     * Get usage history for an account
+     */
+    getHistory(email: string, days?: number): UsageRecord[];
+    /**
+     * Get daily summary for an account
+     */
+    getDailySummary(email: string, days?: number): {
+        date: string;
+        geminiWeeklyAvg: number | null;
+        geminiSessionAvg: number | null;
+        claudeWeeklyAvg: number | null;
+        claudeSessionAvg: number | null;
+        count: number;
+    }[];
+    /**
+     * Register OAuth sources for all stored accounts
+     */
+    private registerOAuthSources;
+    /**
+     * Get the source registry (for doctor/status checks)
+     */
+    getRegistry(): SourceRegistry;
+}
+
+/**
+ * Smart caching layer for quota data
+ *
+ * Caches quota snapshots to avoid hitting API rate limits.
+ * Cache is keyed by email + source combination.
+ */
+
+declare class QuotaCache {
+    private cache;
+    private ttlMs;
+    constructor(ttlMs?: number);
+    /**
+     * Get cached quota if available and not expired
+     */
+    get(email: string, source: string): QuotaSnapshot | null;
+    /**
+     * Store a quota snapshot in cache
+     */
+    set(email: string, source: string, snapshot: QuotaSnapshot): void;
+    /**
+     * Check if a cached entry is still fresh
+     */
+    isFresh(email: string, source: string): boolean;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Get cache age in seconds for a key
+     */
+    getAgeMs(email: string, source: string): number | null;
+}
+
+/**
+ * Token storage for account credentials
+ *
+ * Stores OAuth tokens locally in the config directory.
+ * Tokens are stored as plain JSON (local machine only).
+ */
+
+/**
+ * Get tokens for a specific account
+ */
+declare function getAccountTokens(email: string): StoredTokens | null;
+/**
+ * Get the active account's tokens
+ */
+declare function getActiveAccountTokens(): StoredTokens | null;
+/**
+ * Set the active account
+ */
+declare function setActiveAccount(email: string): boolean;
+/**
+ * Remove an account
+ */
+declare function removeAccount(email: string): boolean;
+/**
+ * List all stored accounts
+ */
+declare function listAccounts(): Array<{
+    email: string;
+    isActive: boolean;
+    addedAt: string;
+}>;
+
+/**
+ * OAuth authentication flow for Google accounts
+ */
+/**
+ * Start an interactive OAuth login flow
+ *
+ * Opens the browser for Google login, then captures the redirect
+ * to exchange the authorization code for tokens.
+ */
+declare function loginAccount(): Promise<string>;
+
+/**
+ * Config file management — reads/writes app configuration
+ */
+
+declare function loadConfig(): AppConfig;
+declare function saveConfig(config: AppConfig): void;
+declare function getConfigDirPath(): string;
+declare function getDataDirPath(): string;
+
+/**
+ * Custom error types for when-does-my-quota-refresh
+ */
+declare class SourceUnavailableError extends Error {
+    constructor(source: string, reason?: string);
+}
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+declare class QuotaFetchError extends Error {
+    constructor(source: string, reason?: string);
+}
+
+/**
+ * when-does-my-quota-refresh SDK
+ *
+ * Core library for fetching and managing Antigravity AI model quotas.
+ * Import this for programmatic use in your own tools and extensions.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'when-does-my-quota-refresh'
+ *
+ * const client = createClient()
+ * const snapshot = await client.fetchQuota()
+ * console.log(snapshot.groups)
+ * ```
+ */
+
+/**
+ * Create a new when-does-my-quota-refresh client
+ */
+declare function createClient(options?: ClientOptions): QuotaClient;
+
+export { type AccountInfo, AuthError, type ClientOptions, type DataSource, type ModelQuotaInfo, type Plugin, type PromptCreditsInfo, type QuotaBucket, QuotaCache, QuotaClient, QuotaFetchError, type QuotaGroup, type QuotaSnapshot, SourceRegistry, SourceUnavailableError, type UsageRecord, cleanupHistory, closeStore, createClient, getAccountTokens, getActiveAccountTokens, getConfigDirPath, getDailySummary, getDataDirPath, getHistory, getLatestSnapshot, listAccounts, loadConfig, loginAccount, removeAccount, saveConfig, setActiveAccount, storeSnapshot };