@teneo-protocol/sdk 1.0.0

package/dist/types/validation.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Validation schemas for user inputs
+ * Provides strict validation with length limits, character restrictions, and format requirements
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchQuerySchema = exports.AgentCommandContentSchema = exports.MessageContentSchema = exports.AgentIdSchema = exports.RoomIdSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Validates room IDs with strict constraints.
+ * - Must not be empty
+ * - Maximum 100 characters
+ * - Only alphanumeric characters, spaces, dashes, and underscores allowed
+ * - Automatically trims whitespace
+ *
+ * @example
+ * ```typescript
+ * const roomId = RoomIdSchema.parse('general-chat'); // OK
+ * const roomId = RoomIdSchema.parse('room_123'); // OK
+ * const roomId = RoomIdSchema.parse('Crawler Room'); // OK
+ * const roomId = RoomIdSchema.parse('invalid room!'); // Error: invalid characters
+ * ```
+ */
+exports.RoomIdSchema = zod_1.z
+    .string()
+    .min(1, "Room ID cannot be empty")
+    .max(100, "Room ID must be 100 characters or less")
+    .regex(/^[a-zA-Z0-9_\- ]+$/, "Room ID can only contain letters, numbers, spaces, dashes, and underscores")
+    .trim();
+/**
+ * Validates agent IDs with strict constraints.
+ * - Must not be empty
+ * - Maximum 100 characters
+ * - Only alphanumeric characters, dashes, and underscores allowed
+ * - Automatically trims whitespace
+ *
+ * @example
+ * ```typescript
+ * const agentId = AgentIdSchema.parse('agent-123'); // OK
+ * const agentId = AgentIdSchema.parse('my_agent'); // OK
+ * const agentId = AgentIdSchema.parse('invalid agent!'); // Error: invalid characters
+ * ```
+ */
+exports.AgentIdSchema = zod_1.z
+    .string()
+    .min(1, "Agent ID cannot be empty")
+    .max(100, "Agent ID must be 100 characters or less")
+    .regex(/^[a-zA-Z0-9_-]+$/, "Agent ID can only contain letters, numbers, dashes, and underscores")
+    .trim();
+/**
+ * Validates message content with strict constraints.
+ * - Must not be empty
+ * - Maximum 10,000 characters to prevent abuse
+ * - No control characters (except newline, tab, carriage return)
+ * - Automatically trims whitespace
+ *
+ * @example
+ * ```typescript
+ * const content = MessageContentSchema.parse('Hello, world!'); // OK
+ * const content = MessageContentSchema.parse('Multi\nline\nmessage'); // OK
+ * const content = MessageContentSchema.parse('\x00Bad content'); // Error: control characters
+ * ```
+ */
+exports.MessageContentSchema = zod_1.z
+    .string()
+    .trim()
+    .min(1, "Message content cannot be empty")
+    .max(10000, "Message content must be 10,000 characters or less")
+    .refine(
+// eslint-disable-next-line no-control-regex -- Intentionally checking for control characters to prevent injection
+(str) => !/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(str), "Message content cannot contain control characters");
+/**
+ * Validates agent command content (string) with strict constraints.
+ * - Must not be empty
+ * - Maximum 5,000 characters
+ * - No control characters (except newline, tab, carriage return)
+ * - Automatically trims whitespace
+ *
+ * @example
+ * ```typescript
+ * const command = AgentCommandContentSchema.parse('execute task'); // OK
+ * const command = AgentCommandContentSchema.parse('multi\nline\ncommand'); // OK
+ * const command = AgentCommandContentSchema.parse('\x00Bad'); // Error: control characters
+ * ```
+ */
+exports.AgentCommandContentSchema = zod_1.z
+    .string()
+    .trim()
+    .min(1, "Agent command cannot be empty")
+    .max(5000, "Agent command must be 5,000 characters or less")
+    .refine(
+// eslint-disable-next-line no-control-regex -- Intentionally checking for control characters to prevent injection
+(str) => !/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(str), "Agent command cannot contain control characters");
+/**
+ * Validates search queries with strict constraints.
+ * - Must not be empty
+ * - Maximum 200 characters (reasonable for search)
+ * - No control characters
+ * - Automatically trims whitespace
+ *
+ * @example
+ * ```typescript
+ * const query = SearchQuerySchema.parse('find agents'); // OK
+ * const query = SearchQuerySchema.parse('\x00Bad query'); // Error: control characters
+ * ```
+ */
+exports.SearchQuerySchema = zod_1.z
+    .string()
+    .trim()
+    .min(1, "Search query cannot be empty")
+    .max(200, "Search query must be 200 characters or less")
+    .refine(
+// eslint-disable-next-line no-control-regex -- Intentionally checking for control characters to prevent injection
+(str) => !/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/.test(str), "Search query cannot contain control characters");
+//# sourceMappingURL=validation.js.map

package/dist/types/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,6BAAwB;AAExB;;;;;;;;;;;;;;GAcG;AACU,QAAA,YAAY,GAAG,OAAC;KAC1B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,yBAAyB,CAAC;KACjC,GAAG,CAAC,GAAG,EAAE,wCAAwC,CAAC;KAClD,KAAK,CAAC,oBAAoB,EAAE,4EAA4E,CAAC;KACzG,IAAI,EAAE,CAAC;AAEV;;;;;;;;;;;;;GAaG;AACU,QAAA,aAAa,GAAG,OAAC;KAC3B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,0BAA0B,CAAC;KAClC,GAAG,CAAC,GAAG,EAAE,yCAAyC,CAAC;KACnD,KAAK,CAAC,kBAAkB,EAAE,qEAAqE,CAAC;KAChG,IAAI,EAAE,CAAC;AAEV;;;;;;;;;;;;;GAaG;AACU,QAAA,oBAAoB,GAAG,OAAC;KAClC,MAAM,EAAE;KACR,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,EAAE,iCAAiC,CAAC;KACzC,GAAG,CAAC,KAAK,EAAE,mDAAmD,CAAC;KAC/D,MAAM;AACL,kHAAkH;AAClH,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,kCAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,EACtD,mDAAmD,CACpD,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACU,QAAA,yBAAyB,GAAG,OAAC;KACvC,MAAM,EAAE;KACR,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,EAAE,+BAA+B,CAAC;KACvC,GAAG,CAAC,IAAI,EAAE,gDAAgD,CAAC;KAC3D,MAAM;AACL,kHAAkH;AAClH,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,kCAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,EACtD,iDAAiD,CAClD,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACU,QAAA,iBAAiB,GAAG,OAAC;KAC/B,MAAM,EAAE;KACR,IAAI,EAAE;KACN,GAAG,CAAC,CAAC,EAAE,8BAA8B,CAAC;KACtC,GAAG,CAAC,GAAG,EAAE,6CAA6C,CAAC;KACvD,MAAM;AACL,kHAAkH;AAClH,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,kCAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,EACtD,gDAAgD,CACjD,CAAC"}

package/dist/utils/bounded-queue.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Bounded Queue with Overflow Strategies
+ * Prevents unbounded memory growth by enforcing a maximum size
+ *
+ * This queue prevents the OOM (Out of Memory) issues that can occur
+ * with unbounded queues when producers outpace consumers (e.g., webhook
+ * delivery failures causing queue buildup).
+ */
+/**
+ * Strategy for handling queue overflow when at max capacity
+ */
+export type OverflowStrategy = 'drop-oldest' | 'drop-newest' | 'reject';
+/**
+ * A queue with a maximum size limit and configurable overflow behavior
+ *
+ * @template T The type of items stored in the queue
+ *
+ * @example
+ * ```typescript
+ * // Create queue that drops oldest items when full
+ * const queue = new BoundedQueue<Message>(1000, 'drop-oldest');
+ *
+ * queue.push(message1); // returns true
+ * queue.push(message2); // returns true
+ *
+ * const msg = queue.shift(); // Remove from front
+ * const peek = queue.peek(); // Look at front without removing
+ *
+ * if (queue.isFull()) {
+ *   console.log('Queue at capacity');
+ * }
+ * ```
+ */
+export declare class BoundedQueue<T> {
+    private readonly maxSize;
+    private readonly strategy;
+    private queue;
+    /**
+     * Creates a new bounded queue
+     *
+     * @param maxSize Maximum number of items the queue can hold
+     * @param strategy How to handle overflow when queue is full
+     * @throws {Error} If maxSize is less than 1
+     */
+    constructor(maxSize: number, strategy?: OverflowStrategy);
+    /**
+     * Add an item to the end of the queue
+     *
+     * Behavior when queue is full depends on strategy:
+     * - 'drop-oldest': Removes oldest item, adds new item, returns true
+     * - 'drop-newest': Rejects new item, returns false
+     * - 'reject': Throws QueueOverflowError
+     *
+     * @param item Item to add to the queue
+     * @returns true if item was added, false if rejected (drop-newest strategy only)
+     * @throws {QueueOverflowError} If strategy is 'reject' and queue is full
+     */
+    push(item: T): boolean;
+    /**
+     * Remove and return the item at the front of the queue
+     *
+     * @returns The item at the front, or undefined if queue is empty
+     */
+    shift(): T | undefined;
+    /**
+     * Look at the item at the front of the queue without removing it
+     *
+     * @returns The item at the front, or undefined if queue is empty
+     */
+    peek(): T | undefined;
+    /**
+     * Remove all items from the queue
+     */
+    clear(): void;
+    /**
+     * Get the current number of items in the queue
+     *
+     * @returns Number of items currently in the queue
+     */
+    size(): number;
+    /**
+     * Check if the queue is at maximum capacity
+     *
+     * @returns true if queue is full, false otherwise
+     */
+    isFull(): boolean;
+    /**
+     * Check if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the maximum capacity of the queue
+     *
+     * @returns The maximum number of items the queue can hold
+     */
+    getMaxSize(): number;
+    /**
+     * Get the current overflow strategy
+     *
+     * @returns The configured overflow strategy
+     */
+    getStrategy(): OverflowStrategy;
+    /**
+     * Get all items in the queue (for inspection/debugging)
+     * Returns a copy to prevent external modification
+     *
+     * @returns Array of all items in the queue (oldest to newest)
+     */
+    toArray(): T[];
+    /**
+     * Handle queue overflow based on configured strategy
+     *
+     * @param item The item attempting to be added
+     * @returns true if item was added, false if rejected
+     * @throws {QueueOverflowError} If strategy is 'reject'
+     */
+    private handleOverflow;
+}
+/**
+ * Error thrown when attempting to add to a full queue with 'reject' strategy
+ */
+export declare class QueueOverflowError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=bounded-queue.d.ts.map

package/dist/utils/bounded-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-queue.d.ts","sourceRoot":"","sources":["../../src/utils/bounded-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,aAAa,GACb,aAAa,GACb,QAAQ,CAAC;AAEb;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY,CAAC,CAAC;IAWvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAX3B,OAAO,CAAC,KAAK,CAAW;IAExB;;;;;;OAMG;gBAEgB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,gBAAgC;IAO7D;;;;;;;;;;;OAWG;IACI,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAS7B;;;;OAIG;IACI,KAAK,IAAI,CAAC,GAAG,SAAS;IAI7B;;;;OAIG;IACI,IAAI,IAAI,CAAC,GAAG,SAAS;IAI5B;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;;;OAIG;IACI,IAAI,IAAI,MAAM;IAIrB;;;;OAIG;IACI,MAAM,IAAI,OAAO;IAIxB;;;;OAIG;IACI,OAAO,IAAI,OAAO;IAIzB;;;;OAIG;IACI,UAAU,IAAI,MAAM;IAI3B;;;;OAIG;IACI,WAAW,IAAI,gBAAgB;IAItC;;;;;OAKG;IACI,OAAO,IAAI,CAAC,EAAE;IAIrB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CAwBvB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAS5B"}

package/dist/utils/bounded-queue.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Bounded Queue with Overflow Strategies
+ * Prevents unbounded memory growth by enforcing a maximum size
+ *
+ * This queue prevents the OOM (Out of Memory) issues that can occur
+ * with unbounded queues when producers outpace consumers (e.g., webhook
+ * delivery failures causing queue buildup).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueueOverflowError = exports.BoundedQueue = void 0;
+/**
+ * A queue with a maximum size limit and configurable overflow behavior
+ *
+ * @template T The type of items stored in the queue
+ *
+ * @example
+ * ```typescript
+ * // Create queue that drops oldest items when full
+ * const queue = new BoundedQueue<Message>(1000, 'drop-oldest');
+ *
+ * queue.push(message1); // returns true
+ * queue.push(message2); // returns true
+ *
+ * const msg = queue.shift(); // Remove from front
+ * const peek = queue.peek(); // Look at front without removing
+ *
+ * if (queue.isFull()) {
+ *   console.log('Queue at capacity');
+ * }
+ * ```
+ */
+class BoundedQueue {
+    /**
+     * Creates a new bounded queue
+     *
+     * @param maxSize Maximum number of items the queue can hold
+     * @param strategy How to handle overflow when queue is full
+     * @throws {Error} If maxSize is less than 1
+     */
+    constructor(maxSize, strategy = 'drop-oldest') {
+        this.maxSize = maxSize;
+        this.strategy = strategy;
+        this.queue = [];
+        if (maxSize < 1) {
+            throw new Error('BoundedQueue maxSize must be at least 1');
+        }
+    }
+    /**
+     * Add an item to the end of the queue
+     *
+     * Behavior when queue is full depends on strategy:
+     * - 'drop-oldest': Removes oldest item, adds new item, returns true
+     * - 'drop-newest': Rejects new item, returns false
+     * - 'reject': Throws QueueOverflowError
+     *
+     * @param item Item to add to the queue
+     * @returns true if item was added, false if rejected (drop-newest strategy only)
+     * @throws {QueueOverflowError} If strategy is 'reject' and queue is full
+     */
+    push(item) {
+        if (this.queue.length >= this.maxSize) {
+            return this.handleOverflow(item);
+        }
+        this.queue.push(item);
+        return true;
+    }
+    /**
+     * Remove and return the item at the front of the queue
+     *
+     * @returns The item at the front, or undefined if queue is empty
+     */
+    shift() {
+        return this.queue.shift();
+    }
+    /**
+     * Look at the item at the front of the queue without removing it
+     *
+     * @returns The item at the front, or undefined if queue is empty
+     */
+    peek() {
+        return this.queue[0];
+    }
+    /**
+     * Remove all items from the queue
+     */
+    clear() {
+        this.queue = [];
+    }
+    /**
+     * Get the current number of items in the queue
+     *
+     * @returns Number of items currently in the queue
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Check if the queue is at maximum capacity
+     *
+     * @returns true if queue is full, false otherwise
+     */
+    isFull() {
+        return this.queue.length >= this.maxSize;
+    }
+    /**
+     * Check if the queue is empty
+     *
+     * @returns true if queue has no items, false otherwise
+     */
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+    /**
+     * Get the maximum capacity of the queue
+     *
+     * @returns The maximum number of items the queue can hold
+     */
+    getMaxSize() {
+        return this.maxSize;
+    }
+    /**
+     * Get the current overflow strategy
+     *
+     * @returns The configured overflow strategy
+     */
+    getStrategy() {
+        return this.strategy;
+    }
+    /**
+     * Get all items in the queue (for inspection/debugging)
+     * Returns a copy to prevent external modification
+     *
+     * @returns Array of all items in the queue (oldest to newest)
+     */
+    toArray() {
+        return [...this.queue];
+    }
+    /**
+     * Handle queue overflow based on configured strategy
+     *
+     * @param item The item attempting to be added
+     * @returns true if item was added, false if rejected
+     * @throws {QueueOverflowError} If strategy is 'reject'
+     */
+    handleOverflow(item) {
+        switch (this.strategy) {
+            case 'drop-oldest':
+                // Remove oldest item and add new one
+                this.queue.shift();
+                this.queue.push(item);
+                return true;
+            case 'drop-newest':
+                // Reject the new item
+                return false;
+            case 'reject':
+                // Throw error - let caller handle
+                throw new QueueOverflowError(`Queue is full (max size: ${this.maxSize}). Cannot add more items.`);
+            default:
+                // TypeScript exhaustiveness check
+                const _exhaustive = this.strategy;
+                throw new Error(`Unknown overflow strategy: ${_exhaustive}`);
+        }
+    }
+}
+exports.BoundedQueue = BoundedQueue;
+/**
+ * Error thrown when attempting to add to a full queue with 'reject' strategy
+ */
+class QueueOverflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QueueOverflowError';
+        // Maintains proper stack trace for where error was thrown (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, QueueOverflowError);
+        }
+    }
+}
+exports.QueueOverflowError = QueueOverflowError;
+//# sourceMappingURL=bounded-queue.js.map

package/dist/utils/bounded-queue.js.map

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

package/dist/utils/circuit-breaker.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ * Provides fault tolerance by preventing cascading failures
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failure threshold exceeded, requests fail fast
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ */
+/**
+ * Circuit breaker states
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Circuit breaker configuration options
+ */
+export interface CircuitBreakerOptions {
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Success count needed to close from half-open (default: 2) */
+    successThreshold?: number;
+    /** Time in ms to wait before trying half-open (default: 60000) */
+    timeout?: number;
+    /** Window size in ms for tracking failures (default: 60000) */
+    windowSize?: number;
+}
+/**
+ * Error thrown when circuit is open
+ */
+export declare class CircuitBreakerError extends Error {
+    readonly state: CircuitState;
+    constructor(message: string, state: CircuitState);
+}
+/**
+ * Circuit breaker for fault tolerance
+ * Prevents cascading failures by failing fast when errors are detected
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 5,
+ *   timeout: 60000
+ * });
+ *
+ * try {
+ *   await breaker.execute(async () => {
+ *     return await fetch('https://api.example.com/data');
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerError) {
+ *     console.log('Circuit is open, failing fast');
+ *   }
+ * }
+ * ```
+ */
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime?;
+    private nextAttemptTime?;
+    private readonly failures;
+    private readonly failureThreshold;
+    private readonly successThreshold;
+    private readonly timeout;
+    private readonly windowSize;
+    /**
+     * Creates a new circuit breaker
+     *
+     * @param options - Configuration options
+     * @throws {Error} If thresholds are less than 1
+     *
+     * @example
+     * ```typescript
+     * const breaker = new CircuitBreaker({
+     *   failureThreshold: 5,  // Open after 5 failures
+     *   successThreshold: 2,  // Close after 2 successes
+     *   timeout: 60000,       // Wait 60s before trying again
+     *   windowSize: 60000     // Track failures in 60s window
+     * });
+     * ```
+     */
+    constructor(options?: CircuitBreakerOptions);
+    /**
+     * Execute an operation through the circuit breaker
+     *
+     * @template T - Return type of the operation
+     * @param operation - Async operation to execute
+     * @returns Promise resolving to operation result
+     * @throws {CircuitBreakerError} If circuit is open
+     * @throws Operation error if operation fails
+     *
+     * @example
+     * ```typescript
+     * const result = await breaker.execute(async () => {
+     *   const response = await fetch(url);
+     *   return await response.json();
+     * });
+     * ```
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit breaker state and metrics
+     *
+     * @returns State object with status and counters
+     */
+    getState(): {
+        state: CircuitState;
+        failureCount: number;
+        successCount: number;
+        lastFailureTime?: number;
+        nextAttemptTime?: number;
+    };
+    /**
+     * Get circuit breaker configuration
+     */
+    getConfig(): {
+        failureThreshold: number;
+        successThreshold: number;
+        timeout: number;
+        windowSize: number;
+    };
+    /**
+     * Manually reset the circuit breaker to CLOSED state
+     * Useful for recovery scenarios or testing
+     */
+    reset(): void;
+    /**
+     * Try to transition from OPEN to HALF_OPEN if timeout has passed
+     */
+    private tryTransitionToHalfOpen;
+    /**
+     * Handle successful operation
+     */
+    private onSuccess;
+    /**
+     * Handle failed operation
+     */
+    private onFailure;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/utils/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/utils/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aACC,KAAK,EAAE,YAAY;gBAApD,OAAO,EAAE,MAAM,EAAkB,KAAK,EAAE,YAAY;CAQjE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;;;;;;;;;;;;OAeG;gBACS,OAAO,GAAE,qBAA0B;IAc/C;;;;;;;;;;;;;;;;OAgBG;IACU,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBhE;;;;OAIG;IACI,QAAQ,IAAI;QACjB,KAAK,EAAE,YAAY,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B;IAUD;;OAEG;IACI,SAAS,IAAI;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB;IASD;;;OAGG;IACI,KAAK,IAAI,IAAI;IASpB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAS/B;;OAEG;IACH,OAAO,CAAC,SAAS;IAkBjB;;OAEG;IACH,OAAO,CAAC,SAAS;CA8BlB"}