paygate-mcp 1.7.0 → 1.8.0

package/README.md

@@ -50,6 +50,8 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **Admin Lifecycle Events** — Webhook notifications for key.created, key.revoked, key.rotated, key.topup
 - **IP Allowlisting** — Restrict API keys to specific IPs or CIDR ranges (IPv4)
 - **Key Tags/Metadata** — Attach arbitrary key-value tags to API keys for external system integration
+- **Usage Analytics** — Time-series analytics API with tool breakdown, top consumers, and trend comparison
+- **Alert Webhooks** — Configurable alerts for spending thresholds, low credits, quota warnings, key expiry, rate limit spikes
 - **Refund on Failure** — Automatically refund credits when downstream tool calls fail
 - **Webhook Events** — POST batched usage events to any URL for external billing/alerting
 - **Config File Mode** — Load all settings from a JSON file (`--config`)
@@ -286,6 +288,9 @@ A real-time admin UI for managing keys, viewing usage, and monitoring tool calls
 | `/.well-known/mcp-payment` | GET | None | Server payment metadata (SEP-2007) |
 | `/pricing` | GET | None | Full per-tool pricing breakdown |
 | `/metrics` | GET | None | Prometheus metrics (counters, gauges, uptime) |
+| `/analytics` | GET | `X-Admin-Key` | Usage analytics (time-series, tool breakdown, trends) |
+| `/alerts` | GET | `X-Admin-Key` | Consume pending alerts |
+| `/alerts` | POST | `X-Admin-Key` | Configure alert rules |
 | `/audit` | GET | `X-Admin-Key` | Query audit log (filter by type, actor, time) |
 | `/audit/export` | GET | `X-Admin-Key` | Export full audit log (JSON or CSV) |
 | `/audit/stats` | GET | `X-Admin-Key` | Audit log statistics |
@@ -510,6 +515,8 @@ When webhooks are enabled, admin operations also fire webhook events:
 | `key.topup` | POST /topup | keyMasked, creditsAdded, newBalance |
 | `key.revoked` | POST /keys/revoke | keyMasked |
 | `key.rotated` | POST /keys/rotate | oldKeyMasked, newKeyMasked |
+| `key.expired` | Gate evaluation | keyMasked |
+| `alert.fired` | Gate evaluation | alertType, keyPrefix, message, value, threshold |
 
 Admin events appear in the `adminEvents` array of the webhook payload (separate from usage `events`). Both arrays can be present in the same batch.
 
@@ -649,7 +656,7 @@ curl http://localhost:3402/audit/stats \
   -H "X-Admin-Key: YOUR_ADMIN_KEY"
 ```
 
-**Tracked events:** `key.created`, `key.revoked`, `key.topup`, `key.acl_updated`, `key.expiry_updated`, `key.quota_updated`, `key.limit_updated`, `gate.allow`, `gate.deny`, `session.created`, `session.destroyed`, `oauth.client_registered`, `oauth.token_issued`, `oauth.token_revoked`, `admin.auth_failed`, `billing.refund`.
+**Tracked events:** `key.created`, `key.revoked`, `key.topup`, `key.acl_updated`, `key.expiry_updated`, `key.quota_updated`, `key.limit_updated`, `key.tags_updated`, `key.ip_updated`, `gate.allow`, `gate.deny`, `session.created`, `session.destroyed`, `oauth.client_registered`, `oauth.token_issued`, `oauth.token_revoked`, `admin.auth_failed`, `admin.alerts_configured`, `billing.refund`.
 
 **Retention:** Ring buffer (default 10,000 events), age-based cleanup (default 30 days), automatic periodic enforcement.
 
@@ -789,6 +796,65 @@ curl -X POST http://localhost:3402/keys \
 
 Limits: max 50 tags per key, max 100 chars per key/value. Tags appear in `/balance` responses and key listings.
 
+### Usage Analytics
+
+Query aggregated usage data for dashboards, reports, and trend analysis:
+
+```bash
+# Get analytics for the last 24 hours (hourly buckets)
+curl "http://localhost:3402/analytics?from=2026-02-25T00:00:00Z&to=2026-02-26T00:00:00Z&granularity=hourly" \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+
+# Daily granularity with top 5 consumers
+curl "http://localhost:3402/analytics?granularity=daily&topN=5" \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+```
+
+Returns:
+- **timeSeries** — Bucketed call counts, credits charged, and denials per time window
+- **toolBreakdown** — Per-tool stats (calls, credits, average cost) sorted by usage
+- **topConsumers** — Top N API keys by credits spent, with each key's most-used tool
+- **trend** — Current vs previous period comparison with percentage changes (calls, credits, denials)
+- **summary** — Total calls, credits, unique keys, and unique tools
+
+Query parameters: `from` (ISO date), `to` (ISO date), `granularity` (`hourly` or `daily`, default: `hourly`), `topN` (number, default: `10`).
+
+### Alert Webhooks
+
+Configure rules to fire alerts when usage thresholds are crossed. Alerts are delivered via webhooks as `alert.fired` admin events:
+
+```bash
+# Configure alert rules
+curl -X POST http://localhost:3402/alerts \
+  -H "Content-Type: application/json" \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"rules": [
+    {"type": "spending_threshold", "threshold": 80},
+    {"type": "credits_low", "threshold": 50},
+    {"type": "quota_warning", "threshold": 90},
+    {"type": "key_expiry_soon", "threshold": 86400},
+    {"type": "rate_limit_spike", "threshold": 10}
+  ]}'
+
+# Consume pending alerts (returns and clears queue)
+curl http://localhost:3402/alerts \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+```
+
+**Alert types:**
+
+| Type | Threshold Meaning | Fires When |
+|------|-------------------|------------|
+| `spending_threshold` | Percentage (0–100) | Key has spent ≥ threshold% of its initial credits |
+| `credits_low` | Absolute credits | Key's remaining credits drop below threshold |
+| `quota_warning` | Percentage (0–100) | Key's daily call usage exceeds threshold% of quota |
+| `key_expiry_soon` | Seconds | Key expires within threshold seconds |
+| `rate_limit_spike` | Count | Key has ≥ threshold rate-limit denials in 5 minutes |
+
+Each rule has an optional `cooldownSeconds` (default: 300) to prevent alert storms. Alerts are automatically checked on every gate evaluation (tool call).
+
+When webhooks are enabled (`--webhook-url`), alerts fire as `alert.fired` events in the `adminEvents` webhook payload with full context (key, rule type, current value, threshold).
+
 ### Rate Limit Response Headers
 
 Every `/mcp` response includes rate limit and credits headers when an API key is provided:
@@ -941,6 +1007,8 @@ const result = await client.callTool('search', { query: 'hello' });
 - [x] Admin lifecycle events — Webhook notifications for key management operations
 - [x] IP allowlisting — Restrict API keys to specific IPs or CIDR ranges
 - [x] Key tags/metadata — Attach key-value tags for external system integration
+- [x] Usage analytics — Time-series analytics API with tool breakdown, trends, and top consumers
+- [x] Alert webhooks — Configurable threshold alerts (spending, credits, quota, expiry, rate limits)
 - [ ] Horizontal scaling — Redis-backed state for multi-process deployments
 
 ## Requirements

package/dist/alerts.d.ts

@@ -0,0 +1,85 @@
+/**
+ * AlertEngine — Configurable alerts for proactive monitoring.
+ *
+ * Alert types:
+ *   - spending_threshold: Fires when a key's totalSpent crosses X% of its credits
+ *   - credits_low: Fires when remaining credits fall below threshold
+ *   - quota_warning: Fires when daily/monthly quota usage exceeds X%
+ *   - key_expiry_soon: Fires when a key will expire within N seconds
+ *   - rate_limit_spike: Fires when rate limit denials exceed N in a window
+ *
+ * Each alert fires at most once per key per cooldown period (default 1 hour).
+ */
+import { ApiKeyRecord } from './types';
+export type AlertType = 'spending_threshold' | 'credits_low' | 'quota_warning' | 'key_expiry_soon' | 'rate_limit_spike';
+export interface AlertRule {
+    type: AlertType;
+    /** Threshold value — meaning depends on type:
+     *   - spending_threshold: percentage (0-100) of initial credits spent
+     *   - credits_low: absolute credits remaining
+     *   - quota_warning: percentage (0-100) of quota used
+     *   - key_expiry_soon: seconds before expiry to alert
+     *   - rate_limit_spike: number of denials in a 5-min window
+     */
+    threshold: number;
+    /** Cooldown in seconds between repeated alerts for same key (default: 3600) */
+    cooldownSeconds?: number;
+}
+export interface Alert {
+    type: AlertType;
+    timestamp: string;
+    keyPrefix: string;
+    keyName: string;
+    message: string;
+    threshold: number;
+    currentValue: number;
+    metadata: Record<string, unknown>;
+}
+export interface AlertEngineConfig {
+    rules: AlertRule[];
+    /** If true, alerts are only logged but not emitted */
+    dryRun?: boolean;
+}
+export declare class AlertEngine {
+    private readonly rules;
+    private readonly dryRun;
+    /** Map of "alertType:keyPrefix" → last alert timestamp */
+    private readonly cooldowns;
+    /** Rate limit denial counter: "keyPrefix" → timestamps of recent denials */
+    private readonly rateLimitDenials;
+    /** Pending alerts waiting to be consumed */
+    private pendingAlerts;
+    constructor(config?: AlertEngineConfig);
+    /**
+     * Check a key record against all alert rules.
+     * Call this after every gate evaluation.
+     */
+    check(key: string, record: ApiKeyRecord, context?: {
+        rateLimitDenied?: boolean;
+    }): Alert[];
+    /**
+     * Record a rate limit denial for spike detection.
+     */
+    recordRateLimitDenial(key: string): void;
+    /**
+     * Consume pending alerts (returns and clears the queue).
+     */
+    consumeAlerts(): Alert[];
+    /**
+     * Get pending alert count.
+     */
+    get pendingCount(): number;
+    /**
+     * Get configured rules.
+     */
+    get configuredRules(): AlertRule[];
+    /**
+     * Evaluate a single rule against a key record.
+     */
+    private evaluateRule;
+    /**
+     * Clear cooldowns (for testing).
+     */
+    clearCooldowns(): void;
+}
+//# sourceMappingURL=alerts.d.ts.map

package/dist/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../src/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvC,MAAM,MAAM,SAAS,GACjB,oBAAoB,GACpB,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAID,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+B;IAChE,4CAA4C;IAC5C,OAAO,CAAC,aAAa,CAAe;gBAExB,MAAM,CAAC,EAAE,iBAAiB;IAKtC;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,KAAK,EAAE;IAyB1F;;OAEG;IACH,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAcxC;;OAEG;IACH,aAAa,IAAI,KAAK,EAAE;IAMxB;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,SAAS,EAAE,CAEjC;IAED;;OAEG;IACH,OAAO,CAAC,YAAY;IAuHpB;;OAEG;IACH,cAAc,IAAI,IAAI;CAKvB"}

package/dist/alerts.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * AlertEngine — Configurable alerts for proactive monitoring.
+ *
+ * Alert types:
+ *   - spending_threshold: Fires when a key's totalSpent crosses X% of its credits
+ *   - credits_low: Fires when remaining credits fall below threshold
+ *   - quota_warning: Fires when daily/monthly quota usage exceeds X%
+ *   - key_expiry_soon: Fires when a key will expire within N seconds
+ *   - rate_limit_spike: Fires when rate limit denials exceed N in a window
+ *
+ * Each alert fires at most once per key per cooldown period (default 1 hour).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlertEngine = void 0;
+// ─── Engine ───────────────────────────────────────────────────────────────────
+class AlertEngine {
+    rules;
+    dryRun;
+    /** Map of "alertType:keyPrefix" → last alert timestamp */
+    cooldowns = new Map();
+    /** Rate limit denial counter: "keyPrefix" → timestamps of recent denials */
+    rateLimitDenials = new Map();
+    /** Pending alerts waiting to be consumed */
+    pendingAlerts = [];
+    constructor(config) {
+        this.rules = config?.rules || [];
+        this.dryRun = config?.dryRun || false;
+    }
+    /**
+     * Check a key record against all alert rules.
+     * Call this after every gate evaluation.
+     */
+    check(key, record, context) {
+        const fired = [];
+        const keyPrefix = key.slice(0, 10) + '...';
+        for (const rule of this.rules) {
+            const cooldownKey = `${rule.type}:${keyPrefix}`;
+            const cooldownMs = (rule.cooldownSeconds || 3600) * 1000;
+            const lastFired = this.cooldowns.get(cooldownKey) || 0;
+            const now = Date.now();
+            if (now - lastFired < cooldownMs)
+                continue;
+            const alert = this.evaluateRule(rule, key, record, keyPrefix, context);
+            if (alert) {
+                this.cooldowns.set(cooldownKey, now);
+                fired.push(alert);
+                if (!this.dryRun) {
+                    this.pendingAlerts.push(alert);
+                }
+            }
+        }
+        return fired;
+    }
+    /**
+     * Record a rate limit denial for spike detection.
+     */
+    recordRateLimitDenial(key) {
+        const keyPrefix = key.slice(0, 10) + '...';
+        let denials = this.rateLimitDenials.get(keyPrefix);
+        if (!denials) {
+            denials = [];
+            this.rateLimitDenials.set(keyPrefix, denials);
+        }
+        denials.push(Date.now());
+        // Keep only last 5 minutes
+        const cutoff = Date.now() - 5 * 60 * 1000;
+        this.rateLimitDenials.set(keyPrefix, denials.filter(t => t > cutoff));
+    }
+    /**
+     * Consume pending alerts (returns and clears the queue).
+     */
+    consumeAlerts() {
+        const alerts = [...this.pendingAlerts];
+        this.pendingAlerts = [];
+        return alerts;
+    }
+    /**
+     * Get pending alert count.
+     */
+    get pendingCount() {
+        return this.pendingAlerts.length;
+    }
+    /**
+     * Get configured rules.
+     */
+    get configuredRules() {
+        return [...this.rules];
+    }
+    /**
+     * Evaluate a single rule against a key record.
+     */
+    evaluateRule(rule, key, record, keyPrefix, context) {
+        const now = new Date().toISOString();
+        const base = {
+            type: rule.type,
+            timestamp: now,
+            keyPrefix,
+            keyName: record.name,
+            threshold: rule.threshold,
+        };
+        switch (rule.type) {
+            case 'spending_threshold': {
+                // Alert when totalSpent exceeds threshold% of (totalSpent + remaining credits)
+                const totalBudget = record.credits + record.totalSpent;
+                if (totalBudget <= 0)
+                    return null;
+                const spentPct = (record.totalSpent / totalBudget) * 100;
+                if (spentPct >= rule.threshold) {
+                    return {
+                        ...base,
+                        currentValue: Math.round(spentPct * 10) / 10,
+                        message: `Key "${record.name}" has spent ${Math.round(spentPct)}% of total budget (${record.totalSpent}/${totalBudget} credits)`,
+                        metadata: { credits: record.credits, totalSpent: record.totalSpent, totalBudget },
+                    };
+                }
+                return null;
+            }
+            case 'credits_low': {
+                if (record.credits <= rule.threshold) {
+                    return {
+                        ...base,
+                        currentValue: record.credits,
+                        message: `Key "${record.name}" has only ${record.credits} credits remaining (threshold: ${rule.threshold})`,
+                        metadata: { credits: record.credits },
+                    };
+                }
+                return null;
+            }
+            case 'quota_warning': {
+                if (!record.quota)
+                    return null;
+                // Check daily call quota
+                if (record.quota.dailyCallLimit > 0) {
+                    const pct = (record.quotaDailyCalls / record.quota.dailyCallLimit) * 100;
+                    if (pct >= rule.threshold) {
+                        return {
+                            ...base,
+                            currentValue: Math.round(pct * 10) / 10,
+                            message: `Key "${record.name}" daily call quota at ${Math.round(pct)}% (${record.quotaDailyCalls}/${record.quota.dailyCallLimit})`,
+                            metadata: {
+                                quotaType: 'dailyCalls',
+                                used: record.quotaDailyCalls,
+                                limit: record.quota.dailyCallLimit,
+                            },
+                        };
+                    }
+                }
+                // Check monthly call quota
+                if (record.quota.monthlyCallLimit > 0) {
+                    const pct = (record.quotaMonthlyCalls / record.quota.monthlyCallLimit) * 100;
+                    if (pct >= rule.threshold) {
+                        return {
+                            ...base,
+                            currentValue: Math.round(pct * 10) / 10,
+                            message: `Key "${record.name}" monthly call quota at ${Math.round(pct)}% (${record.quotaMonthlyCalls}/${record.quota.monthlyCallLimit})`,
+                            metadata: {
+                                quotaType: 'monthlyCalls',
+                                used: record.quotaMonthlyCalls,
+                                limit: record.quota.monthlyCallLimit,
+                            },
+                        };
+                    }
+                }
+                return null;
+            }
+            case 'key_expiry_soon': {
+                if (!record.expiresAt)
+                    return null;
+                const expiresMs = new Date(record.expiresAt).getTime();
+                const remainingMs = expiresMs - Date.now();
+                const thresholdMs = rule.threshold * 1000;
+                if (remainingMs > 0 && remainingMs <= thresholdMs) {
+                    const remainingHours = Math.round(remainingMs / 3600_000 * 10) / 10;
+                    return {
+                        ...base,
+                        currentValue: Math.round(remainingMs / 1000),
+                        message: `Key "${record.name}" expires in ${remainingHours} hours (${record.expiresAt})`,
+                        metadata: { expiresAt: record.expiresAt, remainingSeconds: Math.round(remainingMs / 1000) },
+                    };
+                }
+                return null;
+            }
+            case 'rate_limit_spike': {
+                if (!context?.rateLimitDenied)
+                    return null;
+                const denials = this.rateLimitDenials.get(keyPrefix) || [];
+                const recentCount = denials.length;
+                if (recentCount >= rule.threshold) {
+                    return {
+                        ...base,
+                        currentValue: recentCount,
+                        message: `Key "${record.name}" hit ${recentCount} rate limit denials in 5 min (threshold: ${rule.threshold})`,
+                        metadata: { denialCount: recentCount, windowMinutes: 5 },
+                    };
+                }
+                return null;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Clear cooldowns (for testing).
+     */
+    clearCooldowns() {
+        this.cooldowns.clear();
+        this.rateLimitDenials.clear();
+        this.pendingAlerts = [];
+    }
+}
+exports.AlertEngine = AlertEngine;
+//# sourceMappingURL=alerts.js.map

package/dist/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.js","sourceRoot":"","sources":["../src/alerts.ts"],"names":[],"mappings":"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"}

package/dist/analytics.d.ts

@@ -0,0 +1,117 @@
+/**
+ * AnalyticsEngine — Time-series analytics over UsageEvents.
+ *
+ * Provides:
+ *   - Time-bucketed aggregation (hourly, daily)
+ *   - Per-tool breakdown with success/failure rates
+ *   - Top consumers by credits or call count
+ *   - Trend comparison (current vs previous period)
+ *   - Revenue (credits) over time
+ */
+import { UsageEvent } from './types';
+export type BucketGranularity = 'hourly' | 'daily';
+export interface TimeBucket {
+    /** Bucket start time (ISO 8601) */
+    start: string;
+    /** Bucket end time (ISO 8601) */
+    end: string;
+    /** Total calls in this bucket */
+    calls: number;
+    /** Allowed calls */
+    allowed: number;
+    /** Denied calls */
+    denied: number;
+    /** Credits charged */
+    credits: number;
+}
+export interface ToolBreakdown {
+    tool: string;
+    calls: number;
+    allowed: number;
+    denied: number;
+    credits: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Average credits per allowed call */
+    avgCreditsPerCall: number;
+}
+export interface TopConsumer {
+    /** Key name (or masked prefix) */
+    keyName: string;
+    calls: number;
+    credits: number;
+    denied: number;
+    /** Most-used tool */
+    topTool: string;
+}
+export interface TrendComparison {
+    /** Current period stats */
+    current: {
+        calls: number;
+        credits: number;
+        denied: number;
+    };
+    /** Previous period stats (same duration) */
+    previous: {
+        calls: number;
+        credits: number;
+        denied: number;
+    };
+    /** Percentage change (-100 to +Infinity) */
+    change: {
+        calls: number | null;
+        credits: number | null;
+        denied: number | null;
+    };
+}
+export interface AnalyticsReport {
+    /** Query time range */
+    from: string;
+    to: string;
+    granularity: BucketGranularity;
+    /** Time-series data */
+    timeSeries: TimeBucket[];
+    /** Per-tool breakdown (sorted by calls desc) */
+    tools: ToolBreakdown[];
+    /** Top consumers (sorted by credits desc) */
+    topConsumers: TopConsumer[];
+    /** Trend vs previous equivalent period */
+    trend: TrendComparison;
+    /** Summary stats */
+    summary: {
+        totalCalls: number;
+        totalCredits: number;
+        totalDenied: number;
+        uniqueKeys: number;
+        uniqueTools: number;
+        successRate: number;
+    };
+}
+export declare class AnalyticsEngine {
+    /**
+     * Generate a full analytics report from usage events.
+     */
+    report(events: UsageEvent[], options?: {
+        from?: string;
+        to?: string;
+        granularity?: BucketGranularity;
+        topN?: number;
+    }): AnalyticsReport;
+    /**
+     * Bucket events into time intervals.
+     */
+    private buildTimeSeries;
+    /**
+     * Breakdown per tool, sorted by calls descending.
+     */
+    private buildToolBreakdown;
+    /**
+     * Top consumers by credits spent, with their most-used tool.
+     */
+    private buildTopConsumers;
+    /**
+     * Compare current period vs previous period of same length.
+     */
+    private buildTrend;
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAIrC,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5D,4CAA4C;IAC5C,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,4CAA4C;IAC5C,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,iBAAiB,CAAC;IAC/B,uBAAuB;IACvB,UAAU,EAAE,UAAU,EAAE,CAAC;IACzB,gDAAgD;IAChD,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,6CAA6C;IAC7C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,0CAA0C;IAC1C,KAAK,EAAE,eAAe,CAAC;IACvB,oBAAoB;IACpB,OAAO,EAAE;QACP,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAID,qBAAa,eAAe;IAC1B;;OAEG;IACH,MAAM,CACJ,MAAM,EAAE,UAAU,EAAE,EACpB,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,iBAAiB,CAAC;QAChC,IAAI,CAAC,EAAE,MAAM,CAAC;KACV,GACL,eAAe;IAoDlB;;OAEG;IACH,OAAO,CAAC,eAAe;IA4CvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsDzB;;OAEG;IACH,OAAO,CAAC,UAAU;CA2BnB"}