paygate-mcp 9.7.0 → 9.8.0

package/README.md

@@ -11,7 +11,7 @@ Monetize any MCP server with one command. Add API key auth, per-tool pricing, ra
 - [Quick Start](#quick-start)
 - [What It Does](#what-it-does)
 - [Usage](#usage) — Local stdio, remote HTTP, multi-server, client SDK
-- [API Reference](#api-reference) — All 166+ endpoints
+- [API Reference](#api-reference) — All 172+ endpoints
 - [CLI Options](#cli-options)
 - [Deployment](#deployment) — Docker, docker-compose, systemd, PM2
 - [Load Testing](#load-testing) — k6 benchmarking for production
@@ -66,7 +66,7 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **SSE Streaming** — Full MCP Streamable HTTP transport (POST SSE, GET notifications, DELETE sessions)
 - **Audit Log** — Structured audit trail with retention policies, query API, CSV/JSON export
 - **Registry/Discovery** — Agent-discoverable pricing via `/.well-known/mcp-payment`, `/pricing`, and `/.well-known/mcp.json` identity card
-- **OpenAPI 3.1 + Interactive Docs** — Auto-generated spec at `/openapi.json`, Swagger UI at `/docs` — all 166+ endpoints documented
+- **OpenAPI 3.1 + Interactive Docs** — Auto-generated spec at `/openapi.json`, Swagger UI at `/docs` — all 172+ endpoints documented
 - **Public Endpoint Rate Limiting** — Configurable per-IP rate limit (default 300/min) on `/health`, `/info`, `/pricing`, `/docs`, `/openapi.json`, `/.well-known/*`, `/robots.txt`, `/` — 429 with Retry-After header
 - **Robots.txt + HEAD Support** — Standard `/robots.txt` (allow public, disallow admin/keys), HEAD method on all public endpoints for uptime monitoring
 - **Prometheus Metrics** — `/metrics` endpoint with counters, gauges, and uptime in standard text format
@@ -168,6 +168,9 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **Request/Response Transforms** — Declarative rewriting of tool call arguments and responses — inject defaults, strip fields, rename keys, and template `{{variables}}` from context, wildcard tool matching, priority ordering, deep clone on apply, import/export for backup, manage via `GET/POST/PUT/DELETE /admin/transforms`
 - **Backend Retry Policy** — Automatic retry with exponential backoff for transient failures — configurable max retries, base/max backoff, full jitter, retry budget (max % of traffic as retries with cold-start grace), per-tool stats, retryable error pattern matching, manage via `GET/POST /admin/retry-policy`
 - **Adaptive Rate Limiting** — Dynamic rate adjustment based on key behavior — auto-tighten for high error rates, auto-boost for good actors, cooldown periods, configurable thresholds, per-key behavior tracking, LRU eviction, batch evaluation, manage via `GET/POST /admin/adaptive-rates`
+- **Request Deduplication** — Idempotency layer preventing duplicate billing from agent retries — `X-Idempotency-Key` header with auto-generation fallback (SHA-256), in-flight request coalescing, configurable TTL window, LRU eviction, credits-saved tracking, manage via `GET/POST/DELETE /admin/dedup`
+- **Priority Queue** — Tiered request prioritization (critical/high/normal/low/background) with fair scheduling — per-key priority assignment, configurable max wait times per tier, starvation prevention via automatic promotion, max queue depth limiting, manage via `GET/POST /admin/priority-queue`
+- **Cost Allocation Tags** — Per-request cost attribution via `X-Cost-Tags` header (JSON) for enterprise chargeback — aggregated reports by any tag dimension, cross-tabulation, CSV export, required tag enforcement per key, cardinality limits, manage via `GET/POST/DELETE /admin/cost-tags`
 - **Anomaly Detection** — `GET /admin/anomalies` identifies unusual patterns: keys with high denial rates, rapid credit depletion, low remaining credits, with severity ratings and detailed descriptions
 - **Usage Forecasting** — `GET /admin/forecast` predicts future credit consumption with per-key depletion estimates, calls remaining, at-risk key identification, system-wide consumption aggregates, and per-tool cost breakdown
 - **Compliance Report** — `GET /admin/compliance` generates compliance-ready report with key governance (expiry coverage), access control (ACL/IP/spending limit coverage), audit trail completeness, weighted overall score, and actionable recommendations
@@ -481,7 +484,7 @@ 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) |
 | `/.well-known/mcp.json` | GET | None | MCP Server Identity card (discovery) |
 | `/pricing` | GET | None | Full per-tool pricing breakdown |
-| `/openapi.json` | GET | None | OpenAPI 3.1 spec (all 166+ endpoints) |
+| `/openapi.json` | GET | None | OpenAPI 3.1 spec (all 172+ endpoints) |
 | `/docs` | GET | None | Interactive API docs (Swagger UI) |
 | `/robots.txt` | GET | None | Crawler directives (allow public, disallow admin/keys) |
 | `/portal` | GET | None | Self-service API key portal (browser UI, auth via X-API-Key prompt) |

package/dist/cost-tags.d.ts

@@ -0,0 +1,138 @@
+/**
+ * CostAllocator — Per-request cost allocation tags with chargeback reporting.
+ *
+ * Allows clients to attach key-value tags to individual tool calls via
+ * an `X-Cost-Tags` header. Tags flow through the metering pipeline and
+ * enable aggregated chargeback reports by any dimension.
+ *
+ * Features:
+ *   - X-Cost-Tags header parsing with validation
+ *   - Tag cardinality limits to prevent memory exhaustion
+ *   - Aggregated chargeback reports by any tag dimension
+ *   - Cross-tabulation (group by two dimensions)
+ *   - CSV export support
+ *   - Per-key required tag enforcement
+ *
+ * Zero external dependencies.
+ */
+export interface CostTagConfig {
+    /** Enable cost tags. Default true. */
+    enabled: boolean;
+    /** Max tags per request. Default 10. */
+    maxTagsPerRequest: number;
+    /** Max key length. Default 64. */
+    maxKeyLength: number;
+    /** Max value length. Default 64. */
+    maxValueLength: number;
+    /** Max unique tag keys. Default 1_000. */
+    maxUniqueKeys: number;
+    /** Max unique values per key. Default 10_000. */
+    maxValuesPerKey: number;
+}
+export interface CostTagEntry {
+    tags: Record<string, string>;
+    apiKey: string;
+    toolName: string;
+    credits: number;
+    timestamp: number;
+}
+export interface ChargebackRow {
+    dimension: string;
+    value: string;
+    totalCredits: number;
+    totalCalls: number;
+    avgCreditsPerCall: number;
+}
+export interface CrossTabRow {
+    dim1Value: string;
+    dim2Value: string;
+    totalCredits: number;
+    totalCalls: number;
+}
+export interface ChargebackReport {
+    dimension: string;
+    rows: ChargebackRow[];
+    totalCredits: number;
+    totalCalls: number;
+    generatedAt: string;
+}
+export interface CrossTabReport {
+    dim1: string;
+    dim2: string;
+    rows: CrossTabRow[];
+    totalCredits: number;
+    totalCalls: number;
+    generatedAt: string;
+}
+export interface CostTagStats {
+    enabled: boolean;
+    config: CostTagConfig;
+    totalEntries: number;
+    uniqueKeys: number;
+    valuesPerKey: Record<string, number>;
+    totalCreditsTracked: number;
+    totalCallsTracked: number;
+    requiredTagKeys: number;
+}
+export declare class CostAllocator {
+    private config;
+    private entries;
+    private readonly maxEntries;
+    private knownKeys;
+    private knownValuesPerKey;
+    private requiredTags;
+    constructor(config?: Partial<CostTagConfig>);
+    /**
+     * Parse and validate tags from X-Cost-Tags header value.
+     * Header format: JSON-encoded object, e.g. {"project":"acme","dept":"eng"}
+     */
+    parseTags(headerValue: string): Record<string, string>;
+    /**
+     * Record a tagged usage event.
+     */
+    record(tags: Record<string, string>, apiKey: string, toolName: string, credits: number): void;
+    /**
+     * Check if a request has all required tags for the given API key.
+     */
+    validateRequired(apiKey: string, tags: Record<string, string>): string[];
+    /**
+     * Set required tags for an API key.
+     */
+    setRequiredTags(apiKey: string, tagKeys: string[]): void;
+    /**
+     * Get required tags for an API key.
+     */
+    getRequiredTags(apiKey: string): string[];
+    /**
+     * Generate a chargeback report grouped by a single dimension.
+     */
+    report(dimension: string, startMs?: number, endMs?: number): ChargebackReport;
+    /**
+     * Generate a cross-tabulation report (group by two dimensions).
+     */
+    crossTab(dim1: string, dim2: string, startMs?: number, endMs?: number): CrossTabReport;
+    /**
+     * Export report as CSV string.
+     */
+    reportToCsv(report: ChargebackReport): string;
+    /**
+     * Update configuration at runtime.
+     */
+    configure(updates: Partial<CostTagConfig>): CostTagConfig;
+    /**
+     * Clear all recorded entries.
+     */
+    clear(): void;
+    /**
+     * Get statistics.
+     */
+    stats(): CostTagStats;
+    /** Is cost allocation enabled? */
+    get enabled(): boolean;
+    /** Current config (copy). */
+    get currentConfig(): CostTagConfig;
+    /** Number of recorded entries. */
+    get size(): number;
+    private filterEntries;
+}
+//# sourceMappingURL=cost-tags.d.ts.map

package/dist/cost-tags.d.ts.map

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

package/dist/cost-tags.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * CostAllocator — Per-request cost allocation tags with chargeback reporting.
+ *
+ * Allows clients to attach key-value tags to individual tool calls via
+ * an `X-Cost-Tags` header. Tags flow through the metering pipeline and
+ * enable aggregated chargeback reports by any dimension.
+ *
+ * Features:
+ *   - X-Cost-Tags header parsing with validation
+ *   - Tag cardinality limits to prevent memory exhaustion
+ *   - Aggregated chargeback reports by any tag dimension
+ *   - Cross-tabulation (group by two dimensions)
+ *   - CSV export support
+ *   - Per-key required tag enforcement
+ *
+ * Zero external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostAllocator = void 0;
+// ─── Default config ─────────────────────────────────────────────────────────
+const DEFAULT_COST_TAG_CONFIG = {
+    enabled: true,
+    maxTagsPerRequest: 10,
+    maxKeyLength: 64,
+    maxValueLength: 64,
+    maxUniqueKeys: 1_000,
+    maxValuesPerKey: 10_000,
+};
+// Valid tag key/value pattern: alphanumeric, dash, underscore, colon, dot
+const TAG_PATTERN = /^[a-zA-Z0-9\-_:.]+$/;
+// ─── CostAllocator Class ────────────────────────────────────────────────────
+class CostAllocator {
+    config;
+    entries = [];
+    maxEntries = 100_000;
+    // Cardinality tracking
+    knownKeys = new Set();
+    knownValuesPerKey = new Map();
+    // Required tags per key
+    requiredTags = new Map();
+    constructor(config) {
+        this.config = { ...DEFAULT_COST_TAG_CONFIG, ...config };
+    }
+    /**
+     * Parse and validate tags from X-Cost-Tags header value.
+     * Header format: JSON-encoded object, e.g. {"project":"acme","dept":"eng"}
+     */
+    parseTags(headerValue) {
+        if (!headerValue || !headerValue.trim())
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(headerValue);
+        }
+        catch {
+            throw new Error('Invalid X-Cost-Tags header: must be valid JSON object');
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error('Invalid X-Cost-Tags header: must be a JSON object');
+        }
+        const tags = parsed;
+        const keys = Object.keys(tags);
+        if (keys.length > this.config.maxTagsPerRequest) {
+            throw new Error(`Too many cost tags: ${keys.length} (max ${this.config.maxTagsPerRequest})`);
+        }
+        const validated = {};
+        for (const key of keys) {
+            const value = String(tags[key]);
+            if (key.length > this.config.maxKeyLength) {
+                throw new Error(`Tag key "${key}" exceeds max length ${this.config.maxKeyLength}`);
+            }
+            if (value.length > this.config.maxValueLength) {
+                throw new Error(`Tag value for "${key}" exceeds max length ${this.config.maxValueLength}`);
+            }
+            if (!TAG_PATTERN.test(key)) {
+                throw new Error(`Invalid tag key "${key}": must match [a-zA-Z0-9\\-_:.]`);
+            }
+            if (!TAG_PATTERN.test(value)) {
+                throw new Error(`Invalid tag value for "${key}": must match [a-zA-Z0-9\\-_:.]`);
+            }
+            validated[key] = value;
+        }
+        return validated;
+    }
+    /**
+     * Record a tagged usage event.
+     */
+    record(tags, apiKey, toolName, credits) {
+        if (!this.config.enabled)
+            return;
+        if (Object.keys(tags).length === 0)
+            return;
+        // Check cardinality limits
+        for (const [key, value] of Object.entries(tags)) {
+            if (!this.knownKeys.has(key)) {
+                if (this.knownKeys.size >= this.config.maxUniqueKeys)
+                    continue; // Skip new keys over limit
+                this.knownKeys.add(key);
+            }
+            let valSet = this.knownValuesPerKey.get(key);
+            if (!valSet) {
+                valSet = new Set();
+                this.knownValuesPerKey.set(key, valSet);
+            }
+            if (!valSet.has(value)) {
+                if (valSet.size >= this.config.maxValuesPerKey)
+                    continue; // Skip new values over limit
+                valSet.add(value);
+            }
+        }
+        // Evict oldest entries if at capacity
+        if (this.entries.length >= this.maxEntries) {
+            this.entries.splice(0, Math.floor(this.maxEntries * 0.1));
+        }
+        this.entries.push({
+            tags,
+            apiKey,
+            toolName,
+            credits,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Check if a request has all required tags for the given API key.
+     */
+    validateRequired(apiKey, tags) {
+        const required = this.requiredTags.get(apiKey);
+        if (!required || required.length === 0)
+            return [];
+        const missing = [];
+        for (const key of required) {
+            if (!tags[key])
+                missing.push(key);
+        }
+        return missing;
+    }
+    /**
+     * Set required tags for an API key.
+     */
+    setRequiredTags(apiKey, tagKeys) {
+        if (tagKeys.length === 0) {
+            this.requiredTags.delete(apiKey);
+        }
+        else {
+            this.requiredTags.set(apiKey, tagKeys);
+        }
+    }
+    /**
+     * Get required tags for an API key.
+     */
+    getRequiredTags(apiKey) {
+        return this.requiredTags.get(apiKey) || [];
+    }
+    /**
+     * Generate a chargeback report grouped by a single dimension.
+     */
+    report(dimension, startMs, endMs) {
+        const filtered = this.filterEntries(startMs, endMs);
+        const groups = new Map();
+        for (const entry of filtered) {
+            const value = entry.tags[dimension];
+            if (value === undefined)
+                continue;
+            const group = groups.get(value) || { credits: 0, calls: 0 };
+            group.credits += entry.credits;
+            group.calls++;
+            groups.set(value, group);
+        }
+        const rows = Array.from(groups.entries())
+            .map(([value, g]) => ({
+            dimension,
+            value,
+            totalCredits: g.credits,
+            totalCalls: g.calls,
+            avgCreditsPerCall: g.calls > 0 ? Math.round((g.credits / g.calls) * 100) / 100 : 0,
+        }))
+            .sort((a, b) => b.totalCredits - a.totalCredits);
+        const totalCredits = rows.reduce((sum, r) => sum + r.totalCredits, 0);
+        const totalCalls = rows.reduce((sum, r) => sum + r.totalCalls, 0);
+        return {
+            dimension,
+            rows,
+            totalCredits,
+            totalCalls,
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Generate a cross-tabulation report (group by two dimensions).
+     */
+    crossTab(dim1, dim2, startMs, endMs) {
+        const filtered = this.filterEntries(startMs, endMs);
+        const groups = new Map();
+        for (const entry of filtered) {
+            const v1 = entry.tags[dim1];
+            const v2 = entry.tags[dim2];
+            if (v1 === undefined || v2 === undefined)
+                continue;
+            const key = `${v1}|||${v2}`;
+            const group = groups.get(key) || { credits: 0, calls: 0 };
+            group.credits += entry.credits;
+            group.calls++;
+            groups.set(key, group);
+        }
+        const rows = Array.from(groups.entries())
+            .map(([key, g]) => {
+            const [v1, v2] = key.split('|||');
+            return {
+                dim1Value: v1,
+                dim2Value: v2,
+                totalCredits: g.credits,
+                totalCalls: g.calls,
+            };
+        })
+            .sort((a, b) => b.totalCredits - a.totalCredits);
+        const totalCredits = rows.reduce((sum, r) => sum + r.totalCredits, 0);
+        const totalCalls = rows.reduce((sum, r) => sum + r.totalCalls, 0);
+        return {
+            dim1,
+            dim2,
+            rows,
+            totalCredits,
+            totalCalls,
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Export report as CSV string.
+     */
+    reportToCsv(report) {
+        const lines = ['dimension,value,totalCredits,totalCalls,avgCreditsPerCall'];
+        for (const row of report.rows) {
+            lines.push(`${row.dimension},${row.value},${row.totalCredits},${row.totalCalls},${row.avgCreditsPerCall}`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Update configuration at runtime.
+     */
+    configure(updates) {
+        if (updates.enabled !== undefined)
+            this.config.enabled = updates.enabled;
+        if (updates.maxTagsPerRequest !== undefined)
+            this.config.maxTagsPerRequest = Math.max(1, Math.min(50, updates.maxTagsPerRequest));
+        if (updates.maxKeyLength !== undefined)
+            this.config.maxKeyLength = Math.max(8, Math.min(256, updates.maxKeyLength));
+        if (updates.maxValueLength !== undefined)
+            this.config.maxValueLength = Math.max(8, Math.min(256, updates.maxValueLength));
+        if (updates.maxUniqueKeys !== undefined)
+            this.config.maxUniqueKeys = Math.max(10, Math.min(10_000, updates.maxUniqueKeys));
+        if (updates.maxValuesPerKey !== undefined)
+            this.config.maxValuesPerKey = Math.max(100, Math.min(100_000, updates.maxValuesPerKey));
+        return { ...this.config };
+    }
+    /**
+     * Clear all recorded entries.
+     */
+    clear() {
+        this.entries = [];
+    }
+    /**
+     * Get statistics.
+     */
+    stats() {
+        const valuesPerKey = {};
+        for (const [key, valSet] of this.knownValuesPerKey) {
+            valuesPerKey[key] = valSet.size;
+        }
+        return {
+            enabled: this.config.enabled,
+            config: { ...this.config },
+            totalEntries: this.entries.length,
+            uniqueKeys: this.knownKeys.size,
+            valuesPerKey,
+            totalCreditsTracked: this.entries.reduce((sum, e) => sum + e.credits, 0),
+            totalCallsTracked: this.entries.length,
+            requiredTagKeys: this.requiredTags.size,
+        };
+    }
+    /** Is cost allocation enabled? */
+    get enabled() {
+        return this.config.enabled;
+    }
+    /** Current config (copy). */
+    get currentConfig() {
+        return { ...this.config };
+    }
+    /** Number of recorded entries. */
+    get size() {
+        return this.entries.length;
+    }
+    // ─── Private ───────────────────────────────────────────────────────────────
+    filterEntries(startMs, endMs) {
+        if (!startMs && !endMs)
+            return this.entries;
+        return this.entries.filter(e => {
+            if (startMs && e.timestamp < startMs)
+                return false;
+            if (endMs && e.timestamp > endMs)
+                return false;
+            return true;
+        });
+    }
+}
+exports.CostAllocator = CostAllocator;
+//# sourceMappingURL=cost-tags.js.map

package/dist/cost-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tags.js","sourceRoot":"","sources":["../src/cost-tags.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAsEH,+EAA+E;AAE/E,MAAM,uBAAuB,GAAkB;IAC7C,OAAO,EAAE,IAAI;IACb,iBAAiB,EAAE,EAAE;IACrB,YAAY,EAAE,EAAE;IAChB,cAAc,EAAE,EAAE;IAClB,aAAa,EAAE,KAAK;IACpB,eAAe,EAAE,MAAM;CACxB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAE1C,+EAA+E;AAE/E,MAAa,aAAa;IAChB,MAAM,CAAgB;IACtB,OAAO,GAAmB,EAAE,CAAC;IACpB,UAAU,GAAG,OAAO,CAAC;IAEtC,uBAAuB;IACf,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,iBAAiB,GAAG,IAAI,GAAG,EAAuB,CAAC;IAE3D,wBAAwB;IAChB,YAAY,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEnD,YAAY,MAA+B;QACzC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,uBAAuB,EAAE,GAAG,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,WAAmB;QAC3B,IAAI,CAAC,WAAW,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;QAEnD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,IAAI,GAAG,MAAiC,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,uBAAuB,IAAI,CAAC,MAAM,SAAS,IAAI,CAAC,MAAM,CAAC,iBAAiB,GAAG,CAAC,CAAC;QAC/F,CAAC;QAED,MAAM,SAAS,GAA2B,EAAE,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAEhC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;gBAC1C,MAAM,IAAI,KAAK,CAAC,YAAY,GAAG,wBAAwB,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;YACrF,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;gBAC9C,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,wBAAwB,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC;YAC7F,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,iCAAiC,CAAC,CAAC;YAC5E,CAAC;YACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,iCAAiC,CAAC,CAAC;YAClF,CAAC;YAED,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACzB,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,IAA4B,EAAE,MAAc,EAAE,QAAgB,EAAE,OAAe;QACpF,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO;QACjC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAE3C,2BAA2B;QAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa;oBAAE,SAAS,CAAC,2BAA2B;gBAC3F,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;YAED,IAAI,MAAM,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;gBAC3B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC1C,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvB,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,eAAe;oBAAE,SAAS,CAAC,6BAA6B;gBACvF,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QAED,sCAAsC;QACtC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAC3C,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAChB,IAAI;YACJ,MAAM;YACN,QAAQ;YACR,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,MAAc,EAAE,IAA4B;QAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAElD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,MAAc,EAAE,OAAiB;QAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,MAAc;QAC5B,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAiB,EAAE,OAAgB,EAAE,KAAc;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8C,CAAC;QAErE,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACpC,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAElC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QAED,MAAM,IAAI,GAAoB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;aACvD,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACpB,SAAS;YACT,KAAK;YACL,YAAY,EAAE,CAAC,CAAC,OAAO;YACvB,UAAU,EAAE,CAAC,CAAC,KAAK;YACnB,iBAAiB,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;SACnF,CAAC,CAAC;aACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;QAEnD,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAElE,OAAO;YACL,SAAS;YACT,IAAI;YACJ,YAAY;YACZ,UAAU;YACV,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAY,EAAE,IAAY,EAAE,OAAgB,EAAE,KAAc;QACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA8C,CAAC;QAErE,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;gBAAE,SAAS;YAEnD,MAAM,GAAG,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;YAC1D,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;YAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QAED,MAAM,IAAI,GAAkB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;aACrD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;YAChB,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClC,OAAO;gBACL,SAAS,EAAE,EAAE;gBACb,SAAS,EAAE,EAAE;gBACb,YAAY,EAAE,CAAC,CAAC,OAAO;gBACvB,UAAU,EAAE,CAAC,CAAC,KAAK;aACpB,CAAC;QACJ,CAAC,CAAC;aACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;QAEnD,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;QACtE,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAElE,OAAO;YACL,IAAI;YACJ,IAAI;YACJ,IAAI;YACJ,YAAY;YACZ,UAAU;YACV,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,MAAwB;QAClC,MAAM,KAAK,GAAG,CAAC,2DAA2D,CAAC,CAAC;QAC5E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,YAAY,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC;QAC7G,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,OAA+B;QACvC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QACzE,IAAI,OAAO,CAAC,iBAAiB,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;QAClI,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;QACpH,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;QAC1H,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAC3H,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;QACnI,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,MAAM,YAAY,GAA2B,EAAE,CAAC;QAChD,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACnD,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;QAClC,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;YAC1B,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YACjC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI;YAC/B,YAAY;YACZ,mBAAmB,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACxE,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YACtC,eAAe,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI;SACxC,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,6BAA6B;IAC7B,IAAI,aAAa;QACf,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,8EAA8E;IAEtE,aAAa,CAAC,OAAgB,EAAE,KAAc;QACpD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;YAC7B,IAAI,OAAO,IAAI,CAAC,CAAC,SAAS,GAAG,OAAO;gBAAE,OAAO,KAAK,CAAC;YACnD,IAAI,KAAK,IAAI,CAAC,CAAC,SAAS,GAAG,KAAK;gBAAE,OAAO,KAAK,CAAC;YAC/C,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAvSD,sCAuSC"}

package/dist/dedup.d.ts

@@ -0,0 +1,97 @@
+/**
+ * RequestDeduplicator — Idempotency layer for MCP tool calls.
+ *
+ * Prevents duplicate billing when agents retry the same request due to
+ * timeouts, network flakiness, or client-side retry logic. Clients send
+ * an `X-Idempotency-Key` header or the proxy auto-generates one via
+ * SHA-256 of apiKey + tool + sorted args.
+ *
+ * Features:
+ *   - X-Idempotency-Key header support with auto-generation fallback
+ *   - In-flight request coalescing (concurrent duplicates share the first result)
+ *   - Configurable TTL window for completed request dedup
+ *   - Per-key dedup tracking with LRU eviction
+ *   - Stats: deduplicated requests, coalesced in-flight, credits saved
+ *
+ * Zero external dependencies.
+ */
+export interface DedupConfig {
+    /** Enable deduplication. Default true. */
+    enabled: boolean;
+    /** TTL in ms for completed request cache. Default 60_000 (60s). */
+    ttlMs: number;
+    /** Max cached entries. Default 10_000. */
+    maxEntries: number;
+    /** Auto-generate idempotency key from apiKey+tool+args when header missing. Default true. */
+    autoGenerate: boolean;
+}
+export interface DedupEntry {
+    key: string;
+    result: unknown;
+    completedAt: number;
+    toolName: string;
+    apiKey: string;
+}
+export interface InFlightEntry {
+    promise: Promise<unknown>;
+    toolName: string;
+    apiKey: string;
+    startedAt: number;
+}
+export interface DedupStats {
+    enabled: boolean;
+    config: DedupConfig;
+    cachedEntries: number;
+    inFlightEntries: number;
+    totalDeduped: number;
+    totalCoalesced: number;
+    creditsSaved: number;
+    hitRate: number;
+    totalChecks: number;
+}
+export interface DedupResult<T> {
+    result: T;
+    deduplicated: boolean;
+    idempotencyKey: string;
+}
+export declare class RequestDeduplicator {
+    private config;
+    private cache;
+    private inFlight;
+    private totalDeduped;
+    private totalCoalesced;
+    private creditsSaved;
+    private totalChecks;
+    private insertionOrder;
+    constructor(config?: Partial<DedupConfig>);
+    /**
+     * Generate an idempotency key from request parameters.
+     */
+    generateKey(apiKey: string, toolName: string, args: unknown): string;
+    /**
+     * Execute a function with deduplication.
+     * If an identical request is in-flight, coalesces onto it.
+     * If a completed result is cached, returns it immediately.
+     */
+    execute<T>(idempotencyKey: string, apiKey: string, toolName: string, creditCost: number, fn: () => Promise<T>): Promise<DedupResult<T>>;
+    /**
+     * Update dedup configuration at runtime.
+     */
+    configure(updates: Partial<DedupConfig>): DedupConfig;
+    /**
+     * Clear the dedup cache.
+     */
+    clear(): void;
+    /**
+     * Get statistics.
+     */
+    stats(): DedupStats;
+    /** Is dedup enabled? */
+    get enabled(): boolean;
+    /** Current config. */
+    get currentConfig(): DedupConfig;
+    private cacheResult;
+    private pruneExpired;
+    private sortKeys;
+}
+//# sourceMappingURL=dedup.d.ts.map

package/dist/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,WAAW,WAAW;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC;IACV,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAaD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAc;IAG5B,OAAO,CAAC,KAAK,CAAiC;IAE9C,OAAO,CAAC,QAAQ,CAAoC;IAGpD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IAGxB,OAAO,CAAC,cAAc,CAAgB;gBAE1B,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAIzC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM;IAUpE;;;;OAIG;IACG,OAAO,CAAC,CAAC,EACb,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA0D1B;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW;IAQrD;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,KAAK,IAAI,UAAU;IAenB,wBAAwB;IACxB,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,sBAAsB;IACtB,IAAI,aAAa,IAAI,WAAW,CAE/B;IAID,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,QAAQ;CAYjB"}