paygate-mcp 9.5.0 → 9.7.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 154+ endpoints
+- [API Reference](#api-reference) — All 166+ 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 154+ endpoints documented
+- **OpenAPI 3.1 + Interactive Docs** — Auto-generated spec at `/openapi.json`, Swagger UI at `/docs` — all 166+ 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
@@ -162,6 +162,12 @@ Agent → PayGate (auth + billing) → Your MCP Server (stdio or HTTP)
 - **Concurrency Limiter** — Per-key and per-tool inflight request caps — distinct from rate limiting, limits simultaneous active requests to protect backends from burst parallelism, error code `-32005` with `Retry-After` header, runtime-adjustable via `GET/POST /admin/concurrency`
 - **Traffic Mirroring** — Fire-and-forget request duplication to a shadow backend for A/B testing MCP server versions — percentage-based sampling, configurable timeout, zero impact on primary response path, stats/management via `GET/POST/DELETE /admin/mirror`
 - **Tool Aliasing + Deprecation** — Tool renaming with RFC 8594 compliance — map old tool names to new ones with `Deprecation`, `Sunset`, and `Link` headers, chain prevention, per-alias call counts, CRUD via `GET/POST/DELETE /admin/tool-aliases`
+- **Usage Plans** — Tiered key policies (free/pro/enterprise) — bundle rate limits, quotas, credit multipliers, and tool ACL into reusable templates, assign keys to plans via `POST /admin/keys/plan`, denied tools rejected with error code `-32403`, CRUD via `GET/POST/DELETE /admin/plans`
+- **Tool Input Schema Validation** — Per-tool JSON Schema validation at the gateway — register schemas to reject invalid payloads before they reach downstream, zero-dependency JSON Schema subset (type, required, enum, minLength, pattern, items), error code `-32602` with detailed errors, manage via `GET/POST/DELETE /admin/tools/schema`
+- **Canary Routing** — Weighted traffic splitting between primary and canary MCP servers — enable zero-downtime upgrades with percentage-based routing (0-100%), unbiased `crypto.randomInt` decisions, per-backend call/error tracking, weight updates without restart, manage via `GET/POST/DELETE /admin/canary`
+- **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`
 - **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
@@ -475,7 +481,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 154+ endpoints) |
+| `/openapi.json` | GET | None | OpenAPI 3.1 spec (all 166+ 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/adaptive-rate-limiter.d.ts

@@ -0,0 +1,126 @@
+/**
+ * AdaptiveRateLimiter — Dynamic rate limit adjustment based on traffic behavior.
+ *
+ * Automatically tightens limits for misbehaving keys (high error rates,
+ * excessive credit velocity) and loosens limits for well-behaved keys
+ * (zero denials, steady usage). Wraps the existing static RateLimiter
+ * with a per-key multiplier.
+ *
+ * Inspired by Apigee adaptive rate limiting and Tyk request throttling.
+ * Zero external dependencies.
+ */
+export interface AdaptiveRateConfig {
+    /** Enable adaptive rate limiting. */
+    enabled: boolean;
+    /** Sliding window size in seconds for evaluation. Default 300 (5 min). */
+    evaluationWindowSeconds: number;
+    /** Error rate threshold (0-1) above which rate is tightened. Default 0.3. */
+    errorRateThreshold: number;
+    /** If credit spend rate exceeds this × average, tighten. Default 1.5. */
+    creditVelocityMultiplier: number;
+    /** Never reduce below this % of configured limit. Default 25. */
+    minRatePercent: number;
+    /** Allow burst up to this % for good behavior. Default 200. */
+    maxRatePercent: number;
+    /** Hold adjusted rate for at least this many seconds. Default 60. */
+    cooldownSeconds: number;
+}
+export interface KeyBehavior {
+    totalCalls: number;
+    errorCalls: number;
+    deniedCalls: number;
+    creditsSpent: number;
+    /** Current effective multiplier (1.0 = nominal). */
+    multiplier: number;
+    /** Last time the multiplier was adjusted. */
+    lastAdjusted: number;
+    /** Sliding window of call timestamps. */
+    callTimestamps: number[];
+    /** Sliding window of error timestamps. */
+    errorTimestamps: number[];
+}
+export interface AdaptiveRateStats {
+    enabled: boolean;
+    config: AdaptiveRateConfig;
+    totalKeys: number;
+    tightenedKeys: number;
+    boostedKeys: number;
+    normalKeys: number;
+    keyDetails: Array<{
+        key: string;
+        multiplier: number;
+        effectiveRate: string;
+        recentCalls: number;
+        recentErrors: number;
+        errorRate: number;
+    }>;
+}
+export interface AdaptiveRateAdjustment {
+    key: string;
+    previousMultiplier: number;
+    newMultiplier: number;
+    reason: string;
+    effectiveRate: number;
+    baseRate: number;
+}
+export declare class AdaptiveRateLimiter {
+    private config;
+    private readonly keyBehaviors;
+    private readonly maxTrackedKeys;
+    constructor(config?: Partial<AdaptiveRateConfig>);
+    /**
+     * Update configuration at runtime.
+     */
+    configure(updates: Partial<AdaptiveRateConfig>): AdaptiveRateConfig;
+    /**
+     * Record a call for a key.
+     */
+    recordCall(apiKey: string): void;
+    /**
+     * Record an error for a key.
+     */
+    recordError(apiKey: string): void;
+    /**
+     * Record a denied request for a key.
+     */
+    recordDenied(apiKey: string): void;
+    /**
+     * Record credits spent by a key.
+     */
+    recordCredits(apiKey: string, amount: number): void;
+    /**
+     * Get the effective rate multiplier for a key.
+     * Returns 1.0 if adaptive limiting is disabled.
+     */
+    getMultiplier(apiKey: string): number;
+    /**
+     * Get the effective rate limit for a key.
+     */
+    getEffectiveRate(apiKey: string, baseRate: number): number;
+    /**
+     * Evaluate and adjust the rate multiplier for a key.
+     * Call this periodically (e.g., every minute) or on every Nth request.
+     */
+    evaluate(apiKey: string): AdaptiveRateAdjustment | null;
+    /**
+     * Evaluate all tracked keys.
+     */
+    evaluateAll(): AdaptiveRateAdjustment[];
+    private pruneTimestamps;
+    private getOrCreate;
+    /**
+     * Get adaptive rate statistics.
+     */
+    stats(): AdaptiveRateStats;
+    /**
+     * Reset tracking for a specific key.
+     */
+    resetKey(apiKey: string): boolean;
+    /**
+     * Clear all tracking data.
+     */
+    clear(): void;
+    /** Number of tracked keys. */
+    get size(): number;
+}
+//# sourceMappingURL=adaptive-rate-limiter.d.ts.map

package/dist/adaptive-rate-limiter.d.ts.map

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

package/dist/adaptive-rate-limiter.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * AdaptiveRateLimiter — Dynamic rate limit adjustment based on traffic behavior.
+ *
+ * Automatically tightens limits for misbehaving keys (high error rates,
+ * excessive credit velocity) and loosens limits for well-behaved keys
+ * (zero denials, steady usage). Wraps the existing static RateLimiter
+ * with a per-key multiplier.
+ *
+ * Inspired by Apigee adaptive rate limiting and Tyk request throttling.
+ * Zero external dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveRateLimiter = void 0;
+// ─── Default config ─────────────────────────────────────────────────────────
+const DEFAULT_ADAPTIVE_CONFIG = {
+    enabled: false,
+    evaluationWindowSeconds: 300,
+    errorRateThreshold: 0.3,
+    creditVelocityMultiplier: 1.5,
+    minRatePercent: 25,
+    maxRatePercent: 200,
+    cooldownSeconds: 60,
+};
+// ─── AdaptiveRateLimiter Class ──────────────────────────────────────────────
+class AdaptiveRateLimiter {
+    config;
+    keyBehaviors = new Map();
+    maxTrackedKeys = 5000;
+    constructor(config) {
+        this.config = { ...DEFAULT_ADAPTIVE_CONFIG, ...config };
+    }
+    /**
+     * Update configuration at runtime.
+     */
+    configure(updates) {
+        if (updates.enabled !== undefined)
+            this.config.enabled = updates.enabled;
+        if (updates.evaluationWindowSeconds !== undefined)
+            this.config.evaluationWindowSeconds = Math.max(30, updates.evaluationWindowSeconds);
+        if (updates.errorRateThreshold !== undefined)
+            this.config.errorRateThreshold = Math.min(1, Math.max(0, updates.errorRateThreshold));
+        if (updates.creditVelocityMultiplier !== undefined)
+            this.config.creditVelocityMultiplier = Math.max(1, updates.creditVelocityMultiplier);
+        if (updates.minRatePercent !== undefined)
+            this.config.minRatePercent = Math.min(100, Math.max(1, updates.minRatePercent));
+        if (updates.maxRatePercent !== undefined)
+            this.config.maxRatePercent = Math.max(100, updates.maxRatePercent);
+        if (updates.cooldownSeconds !== undefined)
+            this.config.cooldownSeconds = Math.max(0, updates.cooldownSeconds);
+        return { ...this.config };
+    }
+    /**
+     * Record a call for a key.
+     */
+    recordCall(apiKey) {
+        if (!this.config.enabled)
+            return;
+        const behavior = this.getOrCreate(apiKey);
+        behavior.totalCalls++;
+        behavior.callTimestamps.push(Date.now());
+    }
+    /**
+     * Record an error for a key.
+     */
+    recordError(apiKey) {
+        if (!this.config.enabled)
+            return;
+        const behavior = this.getOrCreate(apiKey);
+        behavior.errorCalls++;
+        behavior.errorTimestamps.push(Date.now());
+    }
+    /**
+     * Record a denied request for a key.
+     */
+    recordDenied(apiKey) {
+        if (!this.config.enabled)
+            return;
+        const behavior = this.getOrCreate(apiKey);
+        behavior.deniedCalls++;
+    }
+    /**
+     * Record credits spent by a key.
+     */
+    recordCredits(apiKey, amount) {
+        if (!this.config.enabled)
+            return;
+        const behavior = this.getOrCreate(apiKey);
+        behavior.creditsSpent += amount;
+    }
+    /**
+     * Get the effective rate multiplier for a key.
+     * Returns 1.0 if adaptive limiting is disabled.
+     */
+    getMultiplier(apiKey) {
+        if (!this.config.enabled)
+            return 1.0;
+        const behavior = this.keyBehaviors.get(apiKey);
+        if (!behavior)
+            return 1.0;
+        return behavior.multiplier;
+    }
+    /**
+     * Get the effective rate limit for a key.
+     */
+    getEffectiveRate(apiKey, baseRate) {
+        return Math.round(baseRate * this.getMultiplier(apiKey));
+    }
+    /**
+     * Evaluate and adjust the rate multiplier for a key.
+     * Call this periodically (e.g., every minute) or on every Nth request.
+     */
+    evaluate(apiKey) {
+        if (!this.config.enabled)
+            return null;
+        const behavior = this.keyBehaviors.get(apiKey);
+        if (!behavior)
+            return null;
+        // Check cooldown
+        const now = Date.now();
+        const cooldownMs = this.config.cooldownSeconds * 1000;
+        if (now - behavior.lastAdjusted < cooldownMs)
+            return null;
+        // Prune old timestamps
+        this.pruneTimestamps(behavior);
+        const recentCalls = behavior.callTimestamps.length;
+        const recentErrors = behavior.errorTimestamps.length;
+        // Need minimum traffic to evaluate
+        if (recentCalls < 5)
+            return null;
+        const previousMultiplier = behavior.multiplier;
+        let newMultiplier = 1.0;
+        let reason = 'normal behavior';
+        // Check error rate
+        const errorRate = recentErrors / recentCalls;
+        if (errorRate > this.config.errorRateThreshold) {
+            // Tighten: reduce to proportional amount
+            const tightenFactor = 1 - (errorRate * 0.5); // 30% errors → 0.85x, 60% → 0.7x
+            newMultiplier = Math.max(this.config.minRatePercent / 100, tightenFactor);
+            reason = `high error rate: ${(errorRate * 100).toFixed(1)}%`;
+        }
+        else if (errorRate < 0.05 && behavior.deniedCalls === 0) {
+            // Boost: reward good behavior
+            const boostFactor = 1 + ((1 - errorRate) * 0.3); // up to 1.3x for perfect keys
+            newMultiplier = Math.min(this.config.maxRatePercent / 100, boostFactor);
+            reason = `good behavior: ${(errorRate * 100).toFixed(1)}% error rate`;
+        }
+        // Clamp
+        newMultiplier = Math.max(this.config.minRatePercent / 100, Math.min(this.config.maxRatePercent / 100, newMultiplier));
+        // Only update if significantly different (>5% change)
+        if (Math.abs(newMultiplier - previousMultiplier) < 0.05)
+            return null;
+        behavior.multiplier = newMultiplier;
+        behavior.lastAdjusted = now;
+        return {
+            key: apiKey.slice(0, 8) + '...',
+            previousMultiplier,
+            newMultiplier,
+            reason,
+            effectiveRate: 0, // caller fills in with base rate
+            baseRate: 0,
+        };
+    }
+    /**
+     * Evaluate all tracked keys.
+     */
+    evaluateAll() {
+        const adjustments = [];
+        for (const key of this.keyBehaviors.keys()) {
+            const adj = this.evaluate(key);
+            if (adj)
+                adjustments.push(adj);
+        }
+        return adjustments;
+    }
+    pruneTimestamps(behavior) {
+        const cutoff = Date.now() - (this.config.evaluationWindowSeconds * 1000);
+        behavior.callTimestamps = behavior.callTimestamps.filter(t => t > cutoff);
+        behavior.errorTimestamps = behavior.errorTimestamps.filter(t => t > cutoff);
+    }
+    getOrCreate(apiKey) {
+        let behavior = this.keyBehaviors.get(apiKey);
+        if (!behavior) {
+            // Evict oldest if at capacity
+            if (this.keyBehaviors.size >= this.maxTrackedKeys) {
+                const firstKey = this.keyBehaviors.keys().next().value;
+                if (firstKey)
+                    this.keyBehaviors.delete(firstKey);
+            }
+            behavior = {
+                totalCalls: 0,
+                errorCalls: 0,
+                deniedCalls: 0,
+                creditsSpent: 0,
+                multiplier: 1.0,
+                lastAdjusted: 0,
+                callTimestamps: [],
+                errorTimestamps: [],
+            };
+            this.keyBehaviors.set(apiKey, behavior);
+        }
+        return behavior;
+    }
+    /**
+     * Get adaptive rate statistics.
+     */
+    stats() {
+        const keyDetails = [];
+        let tightened = 0;
+        let boosted = 0;
+        let normal = 0;
+        for (const [key, behavior] of this.keyBehaviors) {
+            this.pruneTimestamps(behavior);
+            const recentCalls = behavior.callTimestamps.length;
+            const recentErrors = behavior.errorTimestamps.length;
+            const errorRate = recentCalls > 0 ? recentErrors / recentCalls : 0;
+            if (behavior.multiplier < 0.95)
+                tightened++;
+            else if (behavior.multiplier > 1.05)
+                boosted++;
+            else
+                normal++;
+            keyDetails.push({
+                key: key.slice(0, 8) + '...',
+                multiplier: Math.round(behavior.multiplier * 100) / 100,
+                effectiveRate: `${Math.round(behavior.multiplier * 100)}%`,
+                recentCalls,
+                recentErrors,
+                errorRate: Math.round(errorRate * 100) / 100,
+            });
+        }
+        return {
+            enabled: this.config.enabled,
+            config: { ...this.config },
+            totalKeys: this.keyBehaviors.size,
+            tightenedKeys: tightened,
+            boostedKeys: boosted,
+            normalKeys: normal,
+            keyDetails,
+        };
+    }
+    /**
+     * Reset tracking for a specific key.
+     */
+    resetKey(apiKey) {
+        return this.keyBehaviors.delete(apiKey);
+    }
+    /**
+     * Clear all tracking data.
+     */
+    clear() {
+        this.keyBehaviors.clear();
+    }
+    /** Number of tracked keys. */
+    get size() {
+        return this.keyBehaviors.size;
+    }
+}
+exports.AdaptiveRateLimiter = AdaptiveRateLimiter;
+//# sourceMappingURL=adaptive-rate-limiter.js.map

package/dist/adaptive-rate-limiter.js.map

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

package/dist/canary-router.d.ts

@@ -0,0 +1,85 @@
+/**
+ * CanaryRouter — Weighted traffic splitting between primary and canary backends.
+ *
+ * Enables zero-downtime MCP server upgrades by splitting tool-call traffic
+ * between a primary and canary MCP server process. The canary weight (0-100%)
+ * determines the percentage of requests routed to the canary.
+ *
+ * Uses crypto.randomInt for unbiased routing decisions.
+ * Tracks per-backend call counts and error rates.
+ *
+ * Zero external dependencies.
+ */
+import { EventEmitter } from 'events';
+export interface CanaryConfig {
+    /** Command to spawn the canary MCP server. */
+    serverCommand: string;
+    /** Args for the canary server command. */
+    serverArgs: string[];
+    /** Percentage of traffic to route to canary (0-100). */
+    weight: number;
+}
+export interface CanaryStats {
+    enabled: boolean;
+    weight: number;
+    canaryCommand: string | null;
+    primaryCalls: number;
+    canaryCalls: number;
+    primaryErrors: number;
+    canaryErrors: number;
+    createdAt: string | null;
+}
+export type CanaryBackend = 'primary' | 'canary';
+export interface CanaryDecision {
+    backend: CanaryBackend;
+    weight: number;
+}
+export declare class CanaryRouter extends EventEmitter {
+    private config;
+    private primaryCalls;
+    private canaryCalls;
+    private primaryErrors;
+    private canaryErrors;
+    private createdAt;
+    constructor();
+    /**
+     * Enable canary routing with the given config.
+     * The actual canary process spawning is handled by the server — this class
+     * only manages the routing decision and stats.
+     */
+    enable(config: CanaryConfig): void;
+    /**
+     * Disable canary routing.
+     */
+    disable(): void;
+    /**
+     * Update canary weight without restart.
+     */
+    setWeight(weight: number): void;
+    /**
+     * Route a request to primary or canary based on weight.
+     * Uses crypto.randomInt for unbiased routing.
+     */
+    route(): CanaryDecision;
+    /**
+     * Record an error for a backend.
+     */
+    recordError(backend: CanaryBackend): void;
+    /**
+     * Get canary statistics.
+     */
+    stats(): CanaryStats;
+    /**
+     * Check if canary routing is enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Get current weight.
+     */
+    get weight(): number;
+    /**
+     * Get canary config (if enabled).
+     */
+    get canaryConfig(): CanaryConfig | null;
+}
+//# sourceMappingURL=canary-router.d.ts.map

package/dist/canary-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canary-router.d.ts","sourceRoot":"","sources":["../src/canary-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAItC,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,qBAAa,YAAa,SAAQ,YAAY;IAC5C,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,SAAS,CAAuB;;IAMxC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAiBlC;;OAEG;IACH,OAAO,IAAI,IAAI;IAKf;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM/B;;;OAGG;IACH,KAAK,IAAI,cAAc;IAsBvB;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAQzC;;OAEG;IACH,KAAK,IAAI,WAAW;IAepB;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,YAAY,GAAG,IAAI,CAEtC;CACF"}