paygate-mcp 1.6.0 → 1.8.0

package/README.md

@@ -48,6 +48,10 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **Rate Limit Headers** — `X-RateLimit-*` and `X-Credits-Remaining` on every `/mcp` response
 - **Webhook Signatures** — HMAC-SHA256 signed webhook payloads (`X-PayGate-Signature`) for tamper-proof delivery
 - **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`)
@@ -267,6 +271,9 @@ A real-time admin UI for managing keys, viewing usage, and monitoring tool calls
 | `/keys/acl` | POST | `X-Admin-Key` | Set tool ACL (whitelist/blacklist) on a key |
 | `/keys/expiry` | POST | `X-Admin-Key` | Set or remove key expiry (TTL) |
 | `/keys/quota` | POST | `X-Admin-Key` | Set usage quota (daily/monthly limits) |
+| `/keys/tags` | POST | `X-Admin-Key` | Set key tags/metadata (merge semantics) |
+| `/keys/ip` | POST | `X-Admin-Key` | Set IP allowlist (CIDR + exact match) |
+| `/keys/search` | POST | `X-Admin-Key` | Search keys by tag values |
 | `/limits` | POST | `X-Admin-Key` | Set spending limit on a key |
 | `/usage` | GET | `X-Admin-Key` | Export usage data (JSON or CSV) |
 | `/status` | GET | `X-Admin-Key` | Full dashboard with usage stats |
@@ -281,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 |
@@ -505,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.
 
@@ -644,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.
 
@@ -726,6 +738,123 @@ curl -X POST http://localhost:3402/keys/rotate \
 
 The old key is immediately invalidated. All state (credits, totalSpent, totalCalls, ACL, quota, expiry, spending limit) transfers to the new key. Use this for periodic key rotation policies, compromised key response, or key migration.
 
+### IP Allowlisting
+
+Restrict API keys to specific IP addresses or CIDR ranges:
+
+```bash
+# Set IP allowlist on a key (replaces existing list)
+curl -X POST http://localhost:3402/keys/ip \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"key": "pg_...", "ips": ["192.168.1.0/24", "10.0.0.5"]}'
+
+# Clear allowlist (allow all IPs)
+curl -X POST http://localhost:3402/keys/ip \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"key": "pg_...", "ips": []}'
+```
+
+You can also set the allowlist at key creation time:
+
+```bash
+curl -X POST http://localhost:3402/keys \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"name": "prod-agent", "credits": 1000, "ipAllowlist": ["10.0.0.0/8"]}'
+```
+
+Supports exact IPv4 matching and CIDR notation (`/8`, `/16`, `/24`, `/32`, etc.). When the allowlist is empty, all IPs are allowed. Client IP is extracted from `X-Forwarded-For` header (first value) or socket remote address.
+
+### Key Tags / Metadata
+
+Attach arbitrary key-value tags to API keys for external system integration:
+
+```bash
+# Set tags (merge semantics — existing tags preserved, new ones added/updated)
+curl -X POST http://localhost:3402/keys/tags \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"key": "pg_...", "tags": {"team": "backend", "env": "production", "customer_id": "cus_123"}}'
+
+# Remove a tag (set value to null)
+curl -X POST http://localhost:3402/keys/tags \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"key": "pg_...", "tags": {"env": null}}'
+
+# Search keys by tags
+curl -X POST http://localhost:3402/keys/search \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"tags": {"team": "backend"}}'
+# → { "keys": [...], "count": 3 }
+```
+
+Tags can also be set at key creation:
+
+```bash
+curl -X POST http://localhost:3402/keys \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
+  -d '{"name": "backend-prod", "credits": 5000, "tags": {"team": "backend", "env": "production"}}'
+```
+
+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:
@@ -876,6 +1005,10 @@ const result = await client.callTool('search', { query: 'hello' });
 - [x] Rate limit headers — X-RateLimit-* and X-Credits-Remaining on /mcp responses
 - [x] Webhook signatures — HMAC-SHA256 signed payloads with timing-safe verification
 - [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":"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"}