npm - paygate-mcp - Versions diffs - 7.9.0 → 8.1.0 - Mend

paygate-mcp 7.9.0 → 8.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -106,6 +106,8 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **Tool Call Dry Run** — `POST /requests/dry-run` simulates a tool call without executing — checks key validity, ACL, rate limits, credits, and spending limits, returns predicted outcome with credits-after calculation and rate limit status
 - **Batch Dry Run** — `POST /requests/dry-run/batch` simulates multiple tool calls at once — aggregate credit check, per-tool ACL validation, spending limit, returns per-tool results with total credits required and credits-after
 - **Tool Availability** — `GET /tools/available?key=...` returns per-key tool availability with pricing, affordability (canAfford), ACL enforcement (accessible/denyReason), and per-tool + global rate limit status
+- **Key Dashboard** — `GET /keys/dashboard?key=...` consolidated single-endpoint view with metadata, balance, health score, spending velocity, rate limits, quotas, usage summary, and recent activity timeline
+- **Admin Notifications** — `GET /admin/notifications` scans all keys for actionable issues: expired/expiring keys, zero credits, credit depletion velocity, suspended keys, high error rates, and rate limit pressure — with severity filtering and priority sorting
 - **Config Hot Reload** — `POST /config/reload` reloads pricing, rate limits, webhooks, quotas, and behavior flags from config file without server restart
 - **Webhook Events** — POST batched usage events to any URL for external billing/alerting
 - **Config File Mode** — Load all settings from a JSON file (`--config`)
@@ -2330,6 +2332,103 @@ curl "http://localhost:3402/tools/available?key=pg_..." \
 Returns every discovered tool with: `accessible` (ACL check), `denyReason` (if blocked), `creditsPerCall`, `canAfford` (credits vs price), and per-tool `rateLimit` when configured. Includes global rate limit info. Supports alias keys. Works on suspended keys (informational). Read-only — does not deduct credits or increment rate counters.
+### Key Dashboard
+Get a consolidated overview of any API key in a single request:
+```bash
+curl "http://localhost:3402/keys/dashboard?key=pg_..." \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+```
+**Response:**
+```json
+{
+  "key": "pg_c815...09a6",
+  "name": "production-agent",
+  "status": "active",
+  "namespace": "prod",
+  "balance": { "credits": 850, "totalSpent": 150, "totalAllocated": 1000, "spendingLimit": 500 },
+  "health": { "score": 92, "status": "good" },
+  "velocity": { "creditsPerHour": 6.2, "creditsPerDay": 149, "estimatedDepletionDate": "2025-02-03T..." },
+  "rateLimits": { "global": { "limit": 60, "used": 12, "remaining": 48, "resetInMs": 35000 } },
+  "quotas": { "source": "global", "daily": { "callsUsed": 24, "callsLimit": 100 }, "monthly": { "callsUsed": 340, "callsLimit": 5000 } },
+  "usage": { "totalCalls": 340, "totalAllowed": 330, "totalDenied": 10, "totalCredits": 150 },
+  "recentActivity": [{ "timestamp": "...", "event": "gate.allowed", "tool": "search", "credits": 5 }]
+}
+```
+Combines metadata (status/namespace/group/tags), balance (credits/spent/allocated/spendingLimit), health score (0-100 composite), spending velocity with depletion forecast, rate limit and quota status, usage summary, and last 10 audit events. Supports alias keys. Works on suspended/revoked/expired keys. Read-only.
+### Admin Notifications
+Get actionable notifications about keys that need attention:
+```bash
+# Get all notifications
+curl http://localhost:3402/admin/notifications \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+# Filter by severity
+curl "http://localhost:3402/admin/notifications?severity=critical" \
+  -H "X-Admin-Key: YOUR_ADMIN_KEY"
+```
+**Response:**
+```json
+{
+  "total": 4,
+  "critical": 2,
+  "warning": 1,
+  "info": 1,
+  "notifications": [
+    {
+      "severity": "critical",
+      "category": "zero_credits",
+      "message": "Key has zero credits remaining",
+      "key": "pg_c815...09a6",
+      "keyName": "production-agent"
+    },
+    {
+      "severity": "critical",
+      "category": "key_expiring_soon",
+      "message": "Key expires within 8 hours",
+      "key": "pg_a3f1...b2e4",
+      "keyName": "staging-agent",
+      "details": { "expiresAt": "2026-02-27T08:00:00.000Z", "hoursRemaining": 7.5 }
+    },
+    {
+      "severity": "warning",
+      "category": "credits_depleting",
+      "message": "Credits will deplete in ~18 hours at current rate",
+      "key": "pg_d7e2...f1a3",
+      "keyName": "batch-worker",
+      "details": { "credits": 90, "creditsPerHour": 5.1, "estimatedHoursRemaining": 17.6 }
+    },
+    {
+      "severity": "info",
+      "category": "key_suspended",
+      "message": "Key is suspended",
+      "key": "pg_b4c9...e8d5",
+      "keyName": "deprecated-agent"
+    }
+  ]
+}
+```
+**Notification categories:**
+- `key_expired` (critical) — Key has passed its expiry date
+- `key_expiring_soon` (critical <24h, warning <7d) — Key approaching expiry
+- `zero_credits` (critical) — Key has no credits remaining
+- `credits_depleting` (critical <6h, warning <24h) — Spending velocity predicts depletion
+- `key_suspended` (info) — Key is suspended
+- `high_error_rate` (critical ≥50%, warning ≥25%) — High denial rate (min 10 calls)
+- `rate_limit_pressure` (warning ≥90%) — Rate limit nearly exhausted
+Notifications are sorted by severity (critical first). Revoked keys are excluded. A single key can appear in multiple notifications (e.g., zero credits AND expiring soon). Filter with `?severity=critical|warning|info`. Read-only.
 ### IP Allowlisting
 Restrict API keys to specific IP addresses or CIDR ranges:

package/dist/server.d.ts CHANGED Viewed

@@ -211,6 +211,7 @@ export declare class PayGateServer {
     private handleSpendingVelocity;
     private handleKeyComparison;
     private handleKeyHealth;
+    private handleKeyDashboard;
     private handleSetAutoTopup;
     private handleBalance;
     private handleLimits;
@@ -241,6 +242,7 @@ export declare class PayGateServer {
     private handleGetMaintenance;
     private handleSetMaintenance;
     private handleAdminEventStream;
+    private handleAdminNotifications;
     private handleGetNotes;
     private handleAddNote;
     private handleDeleteNote;

package/dist/server.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,eAAe,EAA0B,MAAM,MAAM,CAAC;AAI7E,OAAO,EAAE,aAAa,EAAkB,mBAAmB,EAAkB,MAAM,SAAS,CAAC;AAU7F,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,cAAc,EAAqD,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAmB,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAS,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,eAAe,EAA6B,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAqB,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKrD,0EAA0E;AAC1E,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAsBvF;AAyCD,yCAAyC;AACzC,KAAK,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;AAa5C,qBAAa,aAAa;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,aAAa,CAAqC;IAC1D,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAQ;IAC5C,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAQ;IAC5C,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAS;IACzB,wEAAwE;IACxE,OAAO,CAAC,eAAe,CAAS;IAChC,mDAAmD;IACnD,OAAO,CAAC,kBAAkB,CAAiC;IAC3D,kDAAkD;IAClD,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,gDAAgD;IAChD,OAAO,CAAC,iBAAiB,CAAqF;IAC9G,8CAA8C;IAC9C,OAAO,CAAC,wBAAwB,CAA+C;IAC/E,8BAA8B;IAC9B,OAAO,CAAC,gBAAgB,CAOhB;IACR,2CAA2C;IAC3C,OAAO,CAAC,aAAa,CAA+C;IACpE,4CAA4C;IAC5C,OAAO,CAAC,cAAc,CAAK;IAC3B,kCAAkC;IAClC,OAAO,CAAC,kBAAkB,CAOX;IACf,+CAA+C;IAC/C,OAAO,CAAC,iBAAiB,CAAK;IAC9B,qDAAqD;IACrD,OAAO,CAAC,UAAU,CAUV;IACR,gCAAgC;IAChC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAC7C,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAK;IACrB,sEAAsE;IACtE,OAAO,CAAC,UAAU,CAAuB;IAEzC,0DAA0D;IAC1D,OAAO,KAAK,OAAO,GAElB;gBAGC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,EAC1D,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,mBAAmB,EAAE,EAC/B,QAAQ,CAAC,EAAE,MAAM;IAsMnB;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAK1B,KAAK,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;YA0C5C,aAAa;~~YA8Ub~~,SAAS;IAmQvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IA+C1B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAyB9B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAyCrB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAuC7B,OAAO,CAAC,UAAU;~~IAgHlB~~,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,YAAY;IAyCpB,OAAO,CAAC,UAAU;IAuElB,OAAO,CAAC,kBAAkB;IA0D1B,kEAAkE;IAClE,OAAO,CAAC,OAAO;YAWD,eAAe;IAqH7B,OAAO,CAAC,cAAc;YA0CR,WAAW;YAuEX,oBAAoB;YAwHpB,oBAAoB;IA4IlC,OAAO,CAAC,eAAe;YAoDT,eAAe;YAsEf,eAAe;YAsDf,gBAAgB;YAkEhB,eAAe;YAgEf,cAAc;YAuFd,cAAc;YAoEd,eAAe;YA0Df,YAAY;YAkDZ,eAAe;YAwDf,cAAc;YA+Dd,aAAa;YAsDb,oBAAoB;YAsDpB,qBAAqB;IAgCnC,OAAO,CAAC,cAAc;IA2CtB,OAAO,CAAC,kBAAkB;IAiC1B,OAAO,CAAC,cAAc;IAyEtB,OAAO,CAAC,qBAAqB;IAsD7B,OAAO,CAAC,iBAAiB;IAuEzB,OAAO,CAAC,mBAAmB;IA8C3B,OAAO,CAAC,sBAAsB;IAwD9B,OAAO,CAAC,mBAAmB;IAoG3B,OAAO,CAAC,eAAe;~~YAiJT~~,kBAAkB;IAoFhC,OAAO,CAAC,aAAa;YAuDP,YAAY;IAkD1B,OAAO,CAAC,WAAW;YA+CL,mBAAmB;IAmCjC,OAAO,CAAC,eAAe;IAYvB,+EAA+E;IAC/E,OAAO,CAAC,mBAAmB;IAU3B,oEAAoE;YACtD,mBAAmB;IA4DjC,yDAAyD;YAC3C,oBAAoB;IAuFlC,yCAAyC;YAC3B,gBAAgB;IA8E9B,uDAAuD;YACzC,iBAAiB;IAiC/B,sEAAsE;IACtE,OAAO,CAAC,kBAAkB;IAqB1B,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,eAAe;YAYT,qBAAqB;IAmDnC,OAAO,CAAC,oBAAoB;IAiB5B,OAAO,CAAC,sBAAsB;YAwBhB,mBAAmB;IAoDjC,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,oBAAoB;IA0D5B,OAAO,CAAC,sBAAsB;IA2D9B,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,aAAa;IAiErB,OAAO,CAAC,gBAAgB;IAkDxB,OAAO,CAAC,kBAAkB;IA6B1B,OAAO,CAAC,oBAAoB;IAiG5B,OAAO,CAAC,oBAAoB;IAmC5B,gFAAgF;IAChF,OAAO,CAAC,uBAAuB;IAiD/B,OAAO,CAAC,iBAAiB;IAmGzB,OAAO,CAAC,sBAAsB;IAgC9B,OAAO,CAAC,uBAAuB;IAqG/B,OAAO,CAAC,uBAAuB;IAqE/B,OAAO,CAAC,wBAAwB;IA+ChC,uEAAuE;IACvE,OAAO,CAAC,cAAc;IAQtB,mCAAmC;IACnC,OAAO,CAAC,0BAA0B;YAWpB,kBAAkB;IA4IhC,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,gBAAgB;IA6CxB,OAAO,CAAC,kBAAkB;IAgC1B,OAAO,CAAC,mBAAmB;YAiCb,iBAAiB;IA6H/B,OAAO,CAAC,wBAAwB;YAclB,yBAAyB;YAsCzB,yBAAyB;YAiDzB,yBAAyB;IA4CvC,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,UAAU;IAiClB,OAAO,CAAC,eAAe;YAiBT,gBAAgB;YA4ChB,gBAAgB;YA6ChB,gBAAgB;YAsChB,mBAAmB;YAsDnB,mBAAmB;IA8CjC,OAAO,CAAC,eAAe;IA8BvB,OAAO,CAAC,oBAAoB;YAgBd,iBAAiB;YAyDjB,iBAAiB;IAiE/B,OAAO,CAAC,uBAAuB;IAyB/B,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,gBAAgB;YAOV,iBAAiB;YA2CjB,iBAAiB;YAuDjB,iBAAiB;YAyCjB,sBAAsB;YAsDtB,wBAAwB;IAiDtC,OAAO,CAAC,mBAAmB;YAsBb,oBAAoB;YAwDpB,oBAAoB;IAwDlC,OAAO,CAAC,mBAAmB;YAQb,oBAAoB;YAsCpB,oBAAoB;IAuClC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,eAAe;IAUvB,iFAAiF;IACjF,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,QAAQ;IAkBV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC3B;;;;;;;OAOG;IACG,YAAY,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAgDrD,OAAO,CAAC,gBAAgB;IAuExB,OAAO,CAAC,eAAe;YA+GT,mBAAmB;YAgJnB,wBAAwB;IAoJtC,OAAO,CAAC,sBAAsB;IA0F9B,OAAO,CAAC,sBAAsB;IA6E9B,qDAAqD;IACrD,OAAO,CAAC,UAAU;CAMnB"}
1	+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js CHANGED Viewed

@@ -638,6 +638,12 @@ class PayGateServer {
                 return this.handleKeyComparison(req, res);
             case '/keys/health':
                 return this.handleKeyHealth(req, res);
+            case '/keys/dashboard':
+                if (req.method === 'GET')
+                    return this.handleKeyDashboard(req, res);
+                res.writeHead(405, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Method not allowed. Use GET.' }));
+                return;
             case '/keys/templates':
                 if (req.method === 'GET')
                     return this.handleListTemplates(req, res);
@@ -792,6 +798,12 @@ class PayGateServer {
                 return this.handleRevokeAdminKey(req, res);
             case '/admin/events':
                 return this.handleAdminEventStream(req, res);
+            case '/admin/notifications':
+                if (req.method === 'GET')
+                    return this.handleAdminNotifications(req, res);
+                res.writeHead(405, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Method not allowed. Use GET.' }));
+                return;
             // ─── Plugin endpoints ──────────────────────────────────────────────
             case '/plugins':
                 return this.handleListPlugins(req, res);
@@ -1331,6 +1343,8 @@ class PayGateServer {
                 requestDryRunBatch: 'POST /requests/dry-run/batch — Simulate multiple tool calls without executing (requires X-Admin-Key)',
                 toolStats: 'GET /tools/stats — Per-tool call counts, success rates, latency, credits, and top consumers (requires X-Admin-Key)',
                 toolAvailability: 'GET /tools/available?key=... — Per-key tool availability with pricing, affordability, and rate limit status (requires X-Admin-Key)',
+                keyDashboard: 'GET /keys/dashboard?key=... — Consolidated key overview with metadata, balance, health, velocity, rate limits, quotas, and recent activity (requires X-Admin-Key)',
+                adminNotifications: 'GET /admin/notifications — Actionable notifications for expiring keys, low credits, high error rates, and rate limit pressure (requires X-Admin-Key)',
                 ...(this.oauth ? {
                     oauthMetadata: 'GET /.well-known/oauth-authorization-server — OAuth 2.1 server metadata',
                     oauthRegister: 'POST /oauth/register — Register OAuth client',
@@ -3289,6 +3303,188 @@ class PayGateServer {
             },
         }));
     }
+    // ─── /keys/dashboard — Consolidated key overview ──────────────────────────────
+    handleKeyDashboard(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        const urlParts = req.url?.split('?') || [];
+        const params = new URLSearchParams(urlParts[1] || '');
+        const keyParam = params.get('key');
+        if (!keyParam) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing required parameter: key' }));
+            return;
+        }
+        const record = this.gate.store.resolveKeyRaw(keyParam);
+        if (!record) {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Key not found' }));
+            return;
+        }
+        const actualKey = record.key;
+        const maskedKey = actualKey.slice(0, 7) + '...' + actualKey.slice(-4);
+        // ── Metadata ──
+        const isExpired = record.expiresAt ? new Date(record.expiresAt).getTime() < Date.now() : false;
+        let status = 'active';
+        if (!record.active)
+            status = 'revoked';
+        else if (record.suspended)
+            status = 'suspended';
+        else if (isExpired)
+            status = 'expired';
+        const metadata = {
+            key: maskedKey,
+            name: record.name || null,
+            status,
+            namespace: record.namespace || null,
+            group: record.group || null,
+            createdAt: record.createdAt || null,
+            ...(record.expiresAt ? { expiresAt: record.expiresAt } : {}),
+            tags: record.tags && Object.keys(record.tags).length > 0 ? record.tags : undefined,
+        };
+        // ── Balance ──
+        const balance = {
+            credits: record.credits,
+            totalSpent: record.totalSpent || 0,
+            totalAllocated: record.credits + (record.totalSpent || 0),
+            ...(record.spendingLimit ? { spendingLimit: record.spendingLimit } : {}),
+        };
+        // ── Health score (simplified from handleKeyHealth) ──
+        const velocity = this.creditLedger.getSpendingVelocity(actualKey, record.credits, 24);
+        let balanceScore = 100;
+        if (velocity.creditsPerHour > 0) {
+            const hoursLeft = velocity.estimatedHoursRemaining ?? Infinity;
+            if (hoursLeft <= 1)
+                balanceScore = 0;
+            else if (hoursLeft <= 6)
+                balanceScore = 20;
+            else if (hoursLeft <= 24)
+                balanceScore = 40;
+            else if (hoursLeft <= 72)
+                balanceScore = 60;
+            else if (hoursLeft <= 168)
+                balanceScore = 80;
+        }
+        else if (record.credits <= 0) {
+            balanceScore = 0;
+        }
+        // Quota component
+        let quotaScore = 100;
+        const quotaConfig = record.quota || this.config.globalQuota;
+        if (quotaConfig) {
+            this.gate.quotaTracker.resetIfNeeded(record);
+            let maxUtil = 0;
+            if (quotaConfig.dailyCallLimit && quotaConfig.dailyCallLimit > 0)
+                maxUtil = Math.max(maxUtil, record.quotaDailyCalls / quotaConfig.dailyCallLimit);
+            if (quotaConfig.monthlyCallLimit && quotaConfig.monthlyCallLimit > 0)
+                maxUtil = Math.max(maxUtil, record.quotaMonthlyCalls / quotaConfig.monthlyCallLimit);
+            if (quotaConfig.dailyCreditLimit && quotaConfig.dailyCreditLimit > 0)
+                maxUtil = Math.max(maxUtil, record.quotaDailyCredits / quotaConfig.dailyCreditLimit);
+            if (quotaConfig.monthlyCreditLimit && quotaConfig.monthlyCreditLimit > 0)
+                maxUtil = Math.max(maxUtil, record.quotaMonthlyCredits / quotaConfig.monthlyCreditLimit);
+            quotaScore = Math.max(0, Math.round((1 - maxUtil) * 100));
+        }
+        // Rate limit component
+        const rateStatus = this.gate.rateLimiter.getStatus(actualKey);
+        let rateLimitScore = 100;
+        if (rateStatus.limit > 0) {
+            const utilization = rateStatus.used / rateStatus.limit;
+            rateLimitScore = Math.max(0, Math.round((1 - utilization) * 100));
+        }
+        // Error rate component
+        const keyUsage = this.gate.meter.getKeyUsage(actualKey);
+        let errorScore = 100;
+        if (keyUsage.totalCalls > 0) {
+            const errorRate = keyUsage.totalDenied / keyUsage.totalCalls;
+            errorScore = Math.max(0, Math.round((1 - errorRate) * 100));
+        }
+        const healthScore = Math.round(balanceScore * 0.30 + quotaScore * 0.25 + rateLimitScore * 0.20 + errorScore * 0.25);
+        let healthStatus = 'healthy';
+        if (healthScore < 25)
+            healthStatus = 'critical';
+        else if (healthScore < 50)
+            healthStatus = 'warning';
+        else if (healthScore < 75)
+            healthStatus = 'caution';
+        else if (healthScore < 90)
+            healthStatus = 'good';
+        // ── Velocity ──
+        const velocitySummary = {
+            creditsPerHour: velocity.creditsPerHour,
+            creditsPerDay: velocity.creditsPerDay,
+            callsPerHour: velocity.callsPerHour,
+            callsPerDay: velocity.callsPerDay,
+            estimatedDepletionDate: velocity.estimatedDepletionDate || null,
+        };
+        // ── Rate limits ──
+        const rateLimits = {
+            global: {
+                limit: rateStatus.limit,
+                used: rateStatus.used,
+                remaining: rateStatus.remaining,
+                resetInMs: rateStatus.resetInMs,
+            },
+        };
+        // ── Quotas ──
+        let quotas;
+        if (quotaConfig) {
+            this.gate.quotaTracker.resetIfNeeded(record);
+            quotas = {
+                source: record.quota ? 'per-key' : 'global',
+                daily: {
+                    callsUsed: record.quotaDailyCalls,
+                    callsLimit: quotaConfig.dailyCallLimit || 0,
+                    creditsUsed: record.quotaDailyCredits,
+                    creditsLimit: quotaConfig.dailyCreditLimit || 0,
+                },
+                monthly: {
+                    callsUsed: record.quotaMonthlyCalls,
+                    callsLimit: quotaConfig.monthlyCallLimit || 0,
+                    creditsUsed: record.quotaMonthlyCredits,
+                    creditsLimit: quotaConfig.monthlyCreditLimit || 0,
+                },
+            };
+        }
+        // ── Usage summary ──
+        const usage = {
+            totalCalls: keyUsage.totalCalls || 0,
+            totalAllowed: keyUsage.totalAllowed || 0,
+            totalDenied: keyUsage.totalDenied || 0,
+            totalCredits: keyUsage.totalCreditsSpent || 0,
+        };
+        // ── Recent activity (last 10 events) ──
+        const maskedForAudit = (0, audit_1.maskKeyForAudit)(actualKey);
+        const auditResult = this.audit.query({ limit: 100 });
+        const recentActivity = auditResult.events
+            .filter(e => {
+            for (const field of ['key', 'keyMasked', 'sourceKey', 'destKey']) {
+                const val = e.metadata?.[field];
+                if (val && typeof val === 'string' && val === maskedForAudit)
+                    return true;
+            }
+            if (e.actor === maskedForAudit)
+                return true;
+            return false;
+        })
+            .slice(0, 10)
+            .map(e => ({
+            timestamp: e.timestamp,
+            event: e.type,
+            ...(e.metadata?.tool ? { tool: e.metadata.tool } : {}),
+            ...(e.metadata?.credits ? { credits: e.metadata.credits } : {}),
+        }));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            ...metadata,
+            balance,
+            health: { score: healthScore, status: healthStatus },
+            velocity: velocitySummary,
+            rateLimits,
+            ...(quotas ? { quotas } : {}),
+            usage,
+            recentActivity: recentActivity.length > 0 ? recentActivity : [],
+        }));
+    }
     // ─── /keys/auto-topup — Configure auto-topup ────────────────────────────────
     async handleSetAutoTopup(req, res) {
         if (req.method !== 'POST') {
@@ -4107,6 +4303,142 @@ class PayGateServer {
             }
         });
     }
+    // ─── /admin/notifications — Actionable notifications ──────────────────────
+    handleAdminNotifications(req, res) {
+        if (!this.checkAdmin(req, res))
+            return;
+        const urlParts = req.url?.split('?') || [];
+        const params = new URLSearchParams(urlParts[1] || '');
+        const severityFilter = params.get('severity'); // critical, warning, info, or null for all
+        const notifications = [];
+        // Scan all keys for issues
+        const allRecords = this.gate.store.getAllRecords();
+        for (const record of allRecords) {
+            const maskedKey = record.key.slice(0, 7) + '...' + record.key.slice(-4);
+            const keyName = record.name || undefined;
+            // Skip revoked keys
+            if (!record.active)
+                continue;
+            // ── Expiry checks ──
+            if (record.expiresAt) {
+                const msToExpiry = new Date(record.expiresAt).getTime() - Date.now();
+                const hoursToExpiry = msToExpiry / 3_600_000;
+                if (msToExpiry <= 0) {
+                    notifications.push({
+                        severity: 'critical', category: 'key_expired',
+                        message: `Key has expired`,
+                        key: maskedKey, keyName,
+                        details: { expiresAt: record.expiresAt },
+                    });
+                }
+                else if (hoursToExpiry <= 24) {
+                    notifications.push({
+                        severity: 'critical', category: 'key_expiring_soon',
+                        message: `Key expires within ${Math.ceil(hoursToExpiry)} hours`,
+                        key: maskedKey, keyName,
+                        details: { expiresAt: record.expiresAt, hoursRemaining: Math.round(hoursToExpiry * 10) / 10 },
+                    });
+                }
+                else if (hoursToExpiry <= 168) {
+                    notifications.push({
+                        severity: 'warning', category: 'key_expiring_soon',
+                        message: `Key expires within ${Math.ceil(hoursToExpiry / 24)} days`,
+                        key: maskedKey, keyName,
+                        details: { expiresAt: record.expiresAt, daysRemaining: Math.round(hoursToExpiry / 24 * 10) / 10 },
+                    });
+                }
+            }
+            // ── Credit checks ──
+            if (record.credits <= 0) {
+                notifications.push({
+                    severity: 'critical', category: 'zero_credits',
+                    message: `Key has zero credits remaining`,
+                    key: maskedKey, keyName,
+                });
+            }
+            else {
+                // Check spending velocity for depletion
+                const velocity = this.creditLedger.getSpendingVelocity(record.key, record.credits, 24);
+                if (velocity.creditsPerHour > 0) {
+                    const hoursLeft = velocity.estimatedHoursRemaining ?? Infinity;
+                    if (hoursLeft <= 6) {
+                        notifications.push({
+                            severity: 'critical', category: 'credits_depleting',
+                            message: `Credits will deplete in ~${Math.ceil(hoursLeft)} hours at current rate`,
+                            key: maskedKey, keyName,
+                            details: { credits: record.credits, creditsPerHour: velocity.creditsPerHour, estimatedHoursRemaining: Math.round(hoursLeft * 10) / 10 },
+                        });
+                    }
+                    else if (hoursLeft <= 24) {
+                        notifications.push({
+                            severity: 'warning', category: 'credits_depleting',
+                            message: `Credits will deplete in ~${Math.ceil(hoursLeft)} hours at current rate`,
+                            key: maskedKey, keyName,
+                            details: { credits: record.credits, creditsPerHour: velocity.creditsPerHour, estimatedHoursRemaining: Math.round(hoursLeft * 10) / 10 },
+                        });
+                    }
+                }
+            }
+            // ── Suspended key ──
+            if (record.suspended) {
+                notifications.push({
+                    severity: 'info', category: 'key_suspended',
+                    message: `Key is suspended`,
+                    key: maskedKey, keyName,
+                });
+            }
+            // ── Error rate check ──
+            const keyUsage = this.gate.meter.getKeyUsage(record.key);
+            if (keyUsage.totalCalls >= 10) {
+                const errorRate = keyUsage.totalDenied / keyUsage.totalCalls;
+                if (errorRate >= 0.5) {
+                    notifications.push({
+                        severity: 'critical', category: 'high_error_rate',
+                        message: `${Math.round(errorRate * 100)}% error rate (${keyUsage.totalDenied}/${keyUsage.totalCalls} denied)`,
+                        key: maskedKey, keyName,
+                        details: { errorRate: Math.round(errorRate * 1000) / 1000, totalCalls: keyUsage.totalCalls, totalDenied: keyUsage.totalDenied },
+                    });
+                }
+                else if (errorRate >= 0.25) {
+                    notifications.push({
+                        severity: 'warning', category: 'high_error_rate',
+                        message: `${Math.round(errorRate * 100)}% error rate (${keyUsage.totalDenied}/${keyUsage.totalCalls} denied)`,
+                        key: maskedKey, keyName,
+                        details: { errorRate: Math.round(errorRate * 1000) / 1000, totalCalls: keyUsage.totalCalls, totalDenied: keyUsage.totalDenied },
+                    });
+                }
+            }
+            // ── Rate limit pressure ──
+            const rateStatus = this.gate.rateLimiter.getStatus(record.key);
+            if (rateStatus.limit > 0) {
+                const utilization = rateStatus.used / rateStatus.limit;
+                if (utilization >= 0.9) {
+                    notifications.push({
+                        severity: 'warning', category: 'rate_limit_pressure',
+                        message: `${Math.round(utilization * 100)}% rate limit utilization (${rateStatus.used}/${rateStatus.limit})`,
+                        key: maskedKey, keyName,
+                        details: { used: rateStatus.used, limit: rateStatus.limit, remaining: rateStatus.remaining },
+                    });
+                }
+            }
+        }
+        // Apply severity filter
+        let filtered = notifications;
+        if (severityFilter) {
+            filtered = notifications.filter(n => n.severity === severityFilter);
+        }
+        // Sort: critical first, then warning, then info
+        const severityOrder = { critical: 0, warning: 1, info: 2 };
+        filtered.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            total: filtered.length,
+            critical: filtered.filter(n => n.severity === 'critical').length,
+            warning: filtered.filter(n => n.severity === 'warning').length,
+            info: filtered.filter(n => n.severity === 'info').length,
+            notifications: filtered,
+        }));
+    }
     // ─── /keys/notes — Timestamped notes on API keys ─────────────────────────
     handleGetNotes(req, res) {
         if (!this.checkAdmin(req, res))