/**
 * Usage Metering & Tier Cost Reporting (GTM-001)
 *
 * Tracks per-request tier usage and cost signals for analytics and billing.
 * Provides aggregation by domain, tier, and time period.
 */
import { RenderTier } from '../core/tiered-fetcher.js';
/**
 * Cost units per tier (relative cost, not actual pricing).
 * These represent computational/resource cost, not billing amounts.
 *
 * Intelligence: Fastest, minimal resources (static parsing)
 * Lightweight: Medium, uses linkedom + Node VM
 * Playwright: Slowest, full Chromium browser
 */
export declare const TIER_COST_UNITS: Record<RenderTier, number>;
/**
 * Estimated latency ranges in milliseconds for each tier
 */
export declare const TIER_LATENCY_ESTIMATES: Record<RenderTier, {
    min: number;
    max: number;
    typical: number;
}>;
/**
 * A single usage event
 */
export interface UsageEvent {
    /** Unique event ID */
    id: string;
    /** Timestamp of the event */
    timestamp: number;
    /** Domain of the request */
    domain: string;
    /** Full URL requested */
    url: string;
    /** Tier used for the request */
    tier: RenderTier;
    /** Whether the request succeeded */
    success: boolean;
    /** Actual duration in milliseconds */
    durationMs: number;
    /** Cost units for this request */
    costUnits: number;
    /** Tiers that were attempted (for fallback tracking) */
    tiersAttempted: RenderTier[];
    /** Whether fallback occurred */
    fellBack: boolean;
    /** Optional tenant ID for multi-tenant deployments */
    tenantId?: string;
}
/**
 * Aggregated usage for a period
 */
export interface UsageAggregate {
    /** Start of the period */
    periodStart: number;
    /** End of the period */
    periodEnd: number;
    /** Total requests in period */
    requestCount: number;
    /** Successful requests */
    successCount: number;
    /** Failed requests */
    failureCount: number;
    /** Total cost units consumed */
    totalCostUnits: number;
    /** Breakdown by tier */
    byTier: Record<RenderTier, TierUsage>;
    /** Top domains by cost */
    topDomainsByCost: DomainUsage[];
    /** Top domains by request count */
    topDomainsByRequests: DomainUsage[];
    /** Average duration in ms */
    avgDurationMs: number;
    /** Fallback rate (0-1) */
    fallbackRate: number;
}
export interface TierUsage {
    requestCount: number;
    successCount: number;
    failureCount: number;
    costUnits: number;
    avgDurationMs: number;
    successRate: number;
}
export interface DomainUsage {
    domain: string;
    requestCount: number;
    costUnits: number;
    successRate: number;
    preferredTier: RenderTier;
}
/**
 * Time period for aggregation
 */
export type TimePeriod = 'hour' | 'day' | 'week' | 'month' | 'all';
/**
 * Usage summary for reporting
 */
export interface UsageSummary {
    /** Total requests since tracking started */
    totalRequests: number;
    /** Total cost units consumed */
    totalCostUnits: number;
    /** Overall success rate (0-1) */
    successRate: number;
    /** Average cost per request */
    avgCostPerRequest: number;
    /** Current period stats */
    currentPeriod: UsageAggregate;
    /** Previous period stats (for comparison) */
    previousPeriod?: UsageAggregate;
    /** Cost trend: positive means increasing cost, negative means decreasing */
    costTrend?: number;
    /** Request trend: positive means increasing requests */
    requestTrend?: number;
    /** Timestamp of first event */
    trackingSince: number;
    /** Timestamp of last event */
    lastActivity: number;
}
/**
 * Options for querying usage
 */
export interface UsageQueryOptions {
    /** Filter by domain */
    domain?: string;
    /** Filter by tier */
    tier?: RenderTier;
    /** Filter by tenant ID */
    tenantId?: string;
    /** Time period for aggregation */
    period?: TimePeriod;
    /** Custom start time (overrides period) */
    startTime?: number;
    /** Custom end time (overrides period) */
    endTime?: number;
    /** Limit for top domains */
    topDomainsLimit?: number;
}
export declare class UsageMeter {
    private events;
    private persistentStore;
    private maxEvents;
    private initialized;
    constructor(options?: {
        persistPath?: string;
        maxEvents?: number;
    });
    /**
     * Initialize the usage meter (load persisted events)
     */
    initialize(): Promise<void>;
    /**
     * Record a usage event
     */
    record(event: Omit<UsageEvent, 'id' | 'costUnits'>): Promise<UsageEvent>;
    /**
     * Calculate cost units for a request
     */
    private calculateCost;
    /**
     * Generate a unique event ID
     */
    private generateId;
    /**
     * Get period boundaries based on time period
     */
    private getPeriodBoundaries;
    /**
     * Get previous period boundaries for comparison
     */
    private getPreviousPeriodBoundaries;
    /**
     * Filter events based on query options
     */
    private filterEvents;
    /**
     * Aggregate events into usage stats
     */
    private aggregateEvents;
    /**
     * Get usage summary with trends
     */
    getSummary(options?: UsageQueryOptions): Promise<UsageSummary>;
    /**
     * Get usage aggregated by time periods
     */
    getUsageByPeriod(period: 'hour' | 'day', options?: UsageQueryOptions & {
        periods?: number;
    }): Promise<UsageAggregate[]>;
    /**
     * Get cost breakdown by tier
     */
    getCostBreakdown(options?: UsageQueryOptions): Promise<{
        total: number;
        byTier: Record<RenderTier, {
            cost: number;
            percentage: number;
            requests: number;
        }>;
        avgCostPerRequest: number;
        estimatedMonthlyCost: number;
    }>;
    /**
     * Get event count
     */
    getEventCount(): number;
    /**
     * Reset usage data (for testing or admin purposes)
     */
    reset(): Promise<void>;
    /**
     * Flush any pending data to persistent storage
     */
    flush(): Promise<void>;
}
/**
 * Get or create the global usage meter instance
 */
export declare function getUsageMeter(): UsageMeter;
/**
 * Reset the global usage meter instance (for testing)
 */
export declare function resetUsageMeterInstance(): void;
//# sourceMappingURL=usage-meter.d.ts.map