@agentuity/core 1.0.33 → 1.0.34

package/dist/services/queue/validation.js

@@ -0,0 +1,498 @@
+/**
+ * @module validation
+ * Queue validation utilities with constants matching the Catalyst backend.
+ *
+ * These validation functions perform client-side validation before API calls,
+ * providing immediate feedback and reducing unnecessary network requests.
+ */
+// ============================================================================
+// Validation Constants
+// ============================================================================
+/** Maximum allowed length for queue names. */
+export const MAX_QUEUE_NAME_LENGTH = 256;
+/** Minimum allowed length for queue names. */
+export const MIN_QUEUE_NAME_LENGTH = 1;
+/** Maximum payload size in bytes (1MB). */
+export const MAX_PAYLOAD_SIZE = 1048576;
+/** Maximum description length in characters. */
+export const MAX_DESCRIPTION_LENGTH = 1024;
+/** Maximum number of messages in a single batch operation. */
+export const MAX_BATCH_SIZE = 1000;
+/** Maximum metadata size in bytes (64KB). */
+export const MAX_METADATA_SIZE = 65536;
+/** Maximum partition key length in characters. */
+export const MAX_PARTITION_KEY_LENGTH = 256;
+/** Maximum idempotency key length in characters. */
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+/** Maximum visibility timeout in seconds (12 hours). */
+export const MAX_VISIBILITY_TIMEOUT = 43200;
+/** Maximum number of retry attempts allowed. */
+export const MAX_RETRIES = 100;
+/** Maximum number of in-flight messages per client. */
+export const MAX_IN_FLIGHT = 1000;
+/** Queue name pattern: starts with letter/underscore, contains lowercase alphanumerics, underscores, hyphens. */
+const VALID_QUEUE_NAME_REGEX = /^[a-z_][a-z0-9_-]*$/;
+/** Message ID pattern: must start with qmsg_ prefix. */
+const VALID_MESSAGE_ID_REGEX = /^qmsg_[a-zA-Z0-9]+$/;
+/** Destination ID pattern: must start with qdest_ prefix. */
+const VALID_DESTINATION_ID_REGEX = /^qdest_[a-zA-Z0-9]+$/;
+/** Source ID pattern: must start with qsrc_ prefix. */
+const VALID_SOURCE_ID_REGEX = /^qsrc_[a-zA-Z0-9]+$/;
+/** Maximum source name length. */
+export const MAX_SOURCE_NAME_LENGTH = 256;
+// ============================================================================
+// Validation Error
+// ============================================================================
+// QueueValidationError is the single definition from service.ts — imported for local use and re-exported
+import { QueueValidationError } from "./service.js";
+export { QueueValidationError };
+// ============================================================================
+// Validation Functions
+// ============================================================================
+/**
+ * Validates a queue name against naming rules.
+ *
+ * Queue names must:
+ * - Be 1-256 characters long
+ * - Start with a lowercase letter or underscore
+ * - Contain only lowercase letters, digits, underscores, and hyphens
+ *
+ * @param name - The queue name to validate
+ * @throws {QueueValidationError} If the name is invalid
+ *
+ * @example
+ * ```typescript
+ * validateQueueName('my_queue');      // OK
+ * validateQueueName('order-queue');   // OK
+ * validateQueueName('Invalid Name!'); // Throws
+ * ```
+ */
+export function validateQueueName(name) {
+    if (!name || name.length < MIN_QUEUE_NAME_LENGTH) {
+        throw new QueueValidationError({
+            message: 'Queue name cannot be empty',
+            field: 'name',
+            value: name,
+        });
+    }
+    if (name.length > MAX_QUEUE_NAME_LENGTH) {
+        throw new QueueValidationError({
+            message: `Queue name must not exceed ${MAX_QUEUE_NAME_LENGTH} characters`,
+            field: 'name',
+            value: name,
+        });
+    }
+    if (!VALID_QUEUE_NAME_REGEX.test(name)) {
+        throw new QueueValidationError({
+            message: 'Queue name must start with a letter or underscore and contain only lowercase letters, digits, underscores, and hyphens',
+            field: 'name',
+            value: name,
+        });
+    }
+}
+/**
+ * Validates a queue type.
+ *
+ * @param type - The queue type to validate
+ * @throws {QueueValidationError} If the type is not 'worker' or 'pubsub'
+ */
+export function validateQueueType(type) {
+    if (type !== 'worker' && type !== 'pubsub') {
+        throw new QueueValidationError({
+            message: "Queue type must be 'worker' or 'pubsub'",
+            field: 'queue_type',
+            value: type,
+        });
+    }
+}
+/**
+ * Validates a message payload.
+ *
+ * Payloads must be non-empty JSON and not exceed 1MB when serialized.
+ *
+ * @param payload - The payload to validate (must be JSON-serializable)
+ * @throws {QueueValidationError} If the payload is empty or too large
+ */
+export function validatePayload(payload) {
+    if (payload === undefined || payload === null) {
+        throw new QueueValidationError({
+            message: 'Payload cannot be empty',
+            field: 'payload',
+        });
+    }
+    const serialized = JSON.stringify(payload);
+    const payloadBytes = new TextEncoder().encode(serialized).length;
+    if (payloadBytes > MAX_PAYLOAD_SIZE) {
+        throw new QueueValidationError({
+            message: `Payload size exceeds ${MAX_PAYLOAD_SIZE} byte limit (${payloadBytes} bytes)`,
+            field: 'payload',
+            value: payloadBytes,
+        });
+    }
+}
+/**
+ * Validates a message ID format.
+ *
+ * Message IDs must start with the `qmsg_` prefix.
+ *
+ * @param id - The message ID to validate
+ * @throws {QueueValidationError} If the ID format is invalid
+ */
+export function validateMessageId(id) {
+    if (!id || !VALID_MESSAGE_ID_REGEX.test(id)) {
+        throw new QueueValidationError({
+            message: 'Invalid message ID format (must start with qmsg_ prefix)',
+            field: 'message_id',
+            value: id,
+        });
+    }
+}
+/**
+ * Validates a destination ID format.
+ *
+ * Destination IDs must start with the `qdest_` prefix.
+ *
+ * @param id - The destination ID to validate
+ * @throws {QueueValidationError} If the ID format is invalid
+ */
+export function validateDestinationId(id) {
+    if (!id || !VALID_DESTINATION_ID_REGEX.test(id)) {
+        throw new QueueValidationError({
+            message: 'Invalid destination ID format (must start with qdest_ prefix)',
+            field: 'destination_id',
+            value: id,
+        });
+    }
+}
+/**
+ * Validates a queue or message description.
+ *
+ * @param description - The description to validate (optional)
+ * @throws {QueueValidationError} If the description exceeds the maximum length
+ */
+export function validateDescription(description) {
+    if (description && description.length > MAX_DESCRIPTION_LENGTH) {
+        throw new QueueValidationError({
+            message: `Description must not exceed ${MAX_DESCRIPTION_LENGTH} characters`,
+            field: 'description',
+            value: description.length,
+        });
+    }
+}
+/**
+ * Validates a partition key length.
+ *
+ * Partition keys are used for message ordering within a queue.
+ *
+ * @param key - The partition key to validate (optional)
+ * @throws {QueueValidationError} If the key exceeds the maximum length
+ */
+export function validatePartitionKey(key) {
+    if (key && key.length > MAX_PARTITION_KEY_LENGTH) {
+        throw new QueueValidationError({
+            message: `Partition key must not exceed ${MAX_PARTITION_KEY_LENGTH} characters`,
+            field: 'partition_key',
+            value: key.length,
+        });
+    }
+}
+/**
+ * Validates an idempotency key length.
+ *
+ * Idempotency keys are used to prevent duplicate message processing.
+ *
+ * @param key - The idempotency key to validate (optional)
+ * @throws {QueueValidationError} If the key exceeds the maximum length
+ */
+export function validateIdempotencyKey(key) {
+    if (key && key.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+        throw new QueueValidationError({
+            message: `Idempotency key must not exceed ${MAX_IDEMPOTENCY_KEY_LENGTH} characters`,
+            field: 'idempotency_key',
+            value: key.length,
+        });
+    }
+}
+/**
+ * Validates a time-to-live value.
+ *
+ * TTL specifies how long a message should be kept before expiring.
+ *
+ * @param ttl - The TTL in seconds to validate (optional)
+ * @throws {QueueValidationError} If the TTL is negative
+ */
+export function validateTTL(ttl) {
+    if (ttl !== undefined && ttl < 0) {
+        throw new QueueValidationError({
+            message: 'TTL cannot be negative',
+            field: 'ttl',
+            value: ttl,
+        });
+    }
+}
+/**
+ * Validates a visibility timeout.
+ *
+ * Visibility timeout is how long a message is hidden after being received,
+ * giving the consumer time to process it before it becomes visible again.
+ *
+ * @param timeout - The timeout in seconds to validate (optional)
+ * @throws {QueueValidationError} If the timeout is out of valid range (1-43200 seconds)
+ */
+export function validateVisibilityTimeout(timeout) {
+    if (timeout !== undefined) {
+        if (timeout < 1) {
+            throw new QueueValidationError({
+                message: 'Visibility timeout must be at least 1 second',
+                field: 'visibility_timeout',
+                value: timeout,
+            });
+        }
+        if (timeout > MAX_VISIBILITY_TIMEOUT) {
+            throw new QueueValidationError({
+                message: `Visibility timeout must not exceed ${MAX_VISIBILITY_TIMEOUT} seconds (12 hours)`,
+                field: 'visibility_timeout',
+                value: timeout,
+            });
+        }
+    }
+}
+/**
+ * Validates the maximum retry count.
+ *
+ * @param retries - The max retries value to validate (optional)
+ * @throws {QueueValidationError} If retries is negative or exceeds maximum
+ */
+export function validateMaxRetries(retries) {
+    if (retries !== undefined) {
+        if (retries < 0) {
+            throw new QueueValidationError({
+                message: 'Max retries cannot be negative',
+                field: 'max_retries',
+                value: retries,
+            });
+        }
+        if (retries > MAX_RETRIES) {
+            throw new QueueValidationError({
+                message: `Max retries must not exceed ${MAX_RETRIES}`,
+                field: 'max_retries',
+                value: retries,
+            });
+        }
+    }
+}
+/**
+ * Validates the maximum in-flight messages per client.
+ *
+ * This controls how many messages a single consumer can process concurrently.
+ *
+ * @param maxInFlight - The max in-flight value to validate (optional)
+ * @throws {QueueValidationError} If the value is out of valid range (1-1000)
+ */
+export function validateMaxInFlight(maxInFlight) {
+    if (maxInFlight !== undefined) {
+        if (maxInFlight < 1) {
+            throw new QueueValidationError({
+                message: 'Max in-flight per client must be at least 1',
+                field: 'max_in_flight',
+                value: maxInFlight,
+            });
+        }
+        if (maxInFlight > MAX_IN_FLIGHT) {
+            throw new QueueValidationError({
+                message: `Max in-flight per client must not exceed ${MAX_IN_FLIGHT}`,
+                field: 'max_in_flight',
+                value: maxInFlight,
+            });
+        }
+    }
+}
+/**
+ * Validates a message offset.
+ *
+ * Offsets are sequential positions in the queue, starting from 0.
+ *
+ * @param offset - The offset value to validate
+ * @throws {QueueValidationError} If the offset is negative
+ */
+export function validateOffset(offset) {
+    if (offset < 0) {
+        throw new QueueValidationError({
+            message: 'Offset cannot be negative',
+            field: 'offset',
+            value: offset,
+        });
+    }
+}
+/**
+ * Validates a limit for list/consume operations.
+ *
+ * @param limit - The limit value to validate
+ * @throws {QueueValidationError} If the limit is less than 1 or exceeds maximum
+ */
+export function validateLimit(limit) {
+    if (limit < 1) {
+        throw new QueueValidationError({
+            message: 'Limit must be at least 1',
+            field: 'limit',
+            value: limit,
+        });
+    }
+    if (limit > MAX_BATCH_SIZE) {
+        throw new QueueValidationError({
+            message: `Limit must not exceed ${MAX_BATCH_SIZE}`,
+            field: 'limit',
+            value: limit,
+        });
+    }
+}
+/**
+ * Validates a batch size for batch operations.
+ *
+ * @param size - The batch size to validate
+ * @throws {QueueValidationError} If the size is less than 1 or exceeds maximum
+ */
+export function validateBatchSize(size) {
+    if (size <= 0) {
+        throw new QueueValidationError({
+            message: 'Batch size must be greater than 0',
+            field: 'batch_size',
+            value: size,
+        });
+    }
+    if (size > MAX_BATCH_SIZE) {
+        throw new QueueValidationError({
+            message: `Batch size must not exceed ${MAX_BATCH_SIZE}`,
+            field: 'batch_size',
+            value: size,
+        });
+    }
+}
+/**
+ * Validates a webhook URL for destinations.
+ *
+ * URLs must use HTTP or HTTPS protocol.
+ *
+ * @param url - The URL to validate
+ * @throws {QueueValidationError} If the URL is missing or not HTTP/HTTPS
+ */
+export function validateWebhookUrl(url) {
+    if (!url) {
+        throw new QueueValidationError({
+            message: 'Webhook URL is required',
+            field: 'url',
+        });
+    }
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+        throw new QueueValidationError({
+            message: 'Webhook URL must be a valid HTTP or HTTPS URL',
+            field: 'url',
+            value: url,
+        });
+    }
+}
+/**
+ * Validates a destination configuration object.
+ *
+ * Checks that the config contains a valid URL and optional method/timeout settings.
+ *
+ * @param config - The destination config object to validate
+ * @throws {QueueValidationError} If the config is invalid
+ */
+export function validateDestinationConfig(config) {
+    if (!config) {
+        throw new QueueValidationError({
+            message: 'Destination config is required',
+            field: 'config',
+        });
+    }
+    const url = config.url;
+    if (typeof url !== 'string' || !url) {
+        throw new QueueValidationError({
+            message: 'config.url is required',
+            field: 'config.url',
+        });
+    }
+    validateWebhookUrl(url);
+    const method = config.method;
+    if (method !== undefined) {
+        if (method !== 'POST' && method !== 'PUT' && method !== 'PATCH') {
+            throw new QueueValidationError({
+                message: 'config.method must be POST, PUT, or PATCH',
+                field: 'config.method',
+                value: method,
+            });
+        }
+    }
+    const timeoutMs = config.timeout_ms;
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== 'number' || timeoutMs < 1000 || timeoutMs > 300000) {
+            throw new QueueValidationError({
+                message: 'config.timeout_ms must be between 1000 and 300000',
+                field: 'config.timeout_ms',
+                value: timeoutMs,
+            });
+        }
+    }
+}
+/**
+ * Validates a source ID format.
+ *
+ * Source IDs must start with the `qsrc_` prefix.
+ *
+ * @param id - The source ID to validate
+ * @throws {QueueValidationError} If the ID format is invalid
+ *
+ * @example
+ * ```typescript
+ * validateSourceId('qsrc_abc123'); // OK
+ * validateSourceId('invalid');     // Throws
+ * ```
+ */
+export function validateSourceId(id) {
+    if (!id || typeof id !== 'string') {
+        throw new QueueValidationError({
+            field: 'source_id',
+            value: id,
+            message: 'Source ID is required',
+        });
+    }
+    if (!VALID_SOURCE_ID_REGEX.test(id)) {
+        throw new QueueValidationError({
+            field: 'source_id',
+            value: id,
+            message: 'Source ID must start with "qsrc_" prefix and contain only alphanumeric characters',
+        });
+    }
+}
+/**
+ * Validates a source name.
+ *
+ * Source names must be non-empty and not exceed the maximum length.
+ *
+ * @param name - The source name to validate
+ * @throws {QueueValidationError} If the name is invalid
+ *
+ * @example
+ * ```typescript
+ * validateSourceName('my-source');   // OK
+ * validateSourceName('');          // Throws
+ * ```
+ */
+export function validateSourceName(name) {
+    if (!name || typeof name !== 'string') {
+        throw new QueueValidationError({
+            field: 'source_name',
+            value: name,
+            message: 'Source name is required',
+        });
+    }
+    if (name.length > MAX_SOURCE_NAME_LENGTH) {
+        throw new QueueValidationError({
+            field: 'source_name',
+            value: name,
+            message: `Source name must be at most ${MAX_SOURCE_NAME_LENGTH} characters`,
+        });
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/services/queue/validation.js.map

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

package/dist/services/queue/websocket.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @module websocket
+ *
+ * WebSocket client for real-time queue message subscriptions.
+ *
+ * Provides both a callback-based API ({@link createQueueWebSocket}) and an
+ * async iterator API ({@link subscribeToQueue}) for receiving messages from
+ * a queue in real time via WebSocket.
+ *
+ * @example Callback-based API
+ * ```typescript
+ * import { createQueueWebSocket } from '@agentuity/server';
+ *
+ * const connection = createQueueWebSocket({
+ *     queueName: 'order-processing',
+ *     baseUrl: 'https://catalyst.agentuity.cloud',
+ *     onMessage: (message) => {
+ *         console.log('Received:', message.id, message.payload);
+ *     },
+ *     onOpen: () => console.log('Connected'),
+ *     onClose: (code, reason) => console.log('Closed:', code, reason),
+ *     onError: (error) => console.error('Error:', error),
+ * });
+ *
+ * // Later: close the connection
+ * connection.close();
+ * ```
+ *
+ * @example Resuming from a previous session
+ * ```typescript
+ * import { createQueueWebSocket } from '@agentuity/server';
+ *
+ * // Use a previously obtained clientId and lastOffset to resume
+ * const connection = createQueueWebSocket({
+ *     queueName: 'order-processing',
+ *     baseUrl: 'https://catalyst.agentuity.cloud',
+ *     clientId: previousClientId,
+ *     lastOffset: previousOffset,
+ *     onMessage: (message) => {
+ *         console.log('Received:', message.id, message.payload);
+ *     },
+ * });
+ * ```
+ *
+ * @example Async iterator API
+ * ```typescript
+ * import { subscribeToQueue } from '@agentuity/server';
+ *
+ * const controller = new AbortController();
+ * for await (const message of subscribeToQueue({
+ *     queueName: 'order-processing',
+ *     baseUrl: 'https://catalyst.agentuity.cloud',
+ *     signal: controller.signal,
+ * })) {
+ *     console.log('Received:', message.id, message.payload);
+ * }
+ * ```
+ */
+import { z } from 'zod';
+import type { Message } from './types.ts';
+/** Connection state for a queue WebSocket connection. */
+export type QueueWebSocketState = 'connecting' | 'authenticating' | 'connected' | 'reconnecting' | 'closed';
+/** Options for creating a queue WebSocket subscription. */
+export declare const QueueWebSocketOptionsSchema: z.ZodObject<{
+    queueName: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    onMessage: z.ZodCustom<(message: Message) => void, (message: Message) => void>;
+    onOpen: z.ZodOptional<z.ZodCustom<() => void, () => void>>;
+    onClose: z.ZodOptional<z.ZodCustom<(code: number, reason: string) => void, (code: number, reason: string) => void>>;
+    onError: z.ZodOptional<z.ZodCustom<(error: Error) => void, (error: Error) => void>>;
+    autoReconnect: z.ZodOptional<z.ZodBoolean>;
+    maxReconnectAttempts: z.ZodOptional<z.ZodNumber>;
+    reconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    maxReconnectDelayMs: z.ZodOptional<z.ZodNumber>;
+    clientId: z.ZodOptional<z.ZodString>;
+    lastOffset: z.ZodOptional<z.ZodNumber>;
+    orgId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type QueueWebSocketOptions = z.infer<typeof QueueWebSocketOptionsSchema>;
+/** Return type from {@link createQueueWebSocket}. */
+export interface QueueWebSocketConnection {
+    /** Close the WebSocket connection. Disables auto-reconnect. */
+    close(): void;
+    /** The current connection state. */
+    readonly state: QueueWebSocketState;
+    /** The client/subscription ID assigned by the server. Stable across reconnections. */
+    readonly clientId: string | undefined;
+    /** The offset of the last message processed. */
+    readonly lastOffset: number | undefined;
+}
+/** Options for the async iterator queue subscription. */
+export declare const SubscribeToQueueOptionsSchema: z.ZodObject<{
+    queueName: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    clientId: z.ZodOptional<z.ZodString>;
+    lastOffset: z.ZodOptional<z.ZodNumber>;
+    orgId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SubscribeToQueueOptions = z.infer<typeof SubscribeToQueueOptionsSchema>;
+/**
+ * Create a WebSocket connection to receive real-time messages from a queue.
+ *
+ * The connection handles authentication, automatic reconnection with exponential
+ * backoff, and ping/pong keep-alive (handled automatically by the WebSocket
+ * implementation).
+ *
+ * @param options - Configuration for the WebSocket connection
+ * @returns A {@link QueueWebSocketConnection} handle for managing the connection
+ * @throws {QueueError} If no API key is available
+ * @throws {QueueValidationError} If the queue name is invalid
+ *
+ * @example
+ * ```typescript
+ * const connection = createQueueWebSocket({
+ *     queueName: 'order-processing',
+ *     baseUrl: 'https://catalyst.agentuity.cloud',
+ *     onMessage: (message) => {
+ *         console.log('Received:', message.id, message.payload);
+ *     },
+ * });
+ *
+ * // Later: close the connection
+ * connection.close();
+ * ```
+ */
+export declare function createQueueWebSocket(options: QueueWebSocketOptions): QueueWebSocketConnection;
+/**
+ * Subscribe to real-time messages from a queue via WebSocket.
+ *
+ * Returns an async iterator that yields messages as they arrive.
+ * The connection is automatically managed (auth, reconnection, cleanup).
+ *
+ * @param options - Configuration for the subscription
+ * @returns An async generator that yields {@link Message} objects
+ * @throws {QueueError} If no API key is available
+ * @throws {QueueValidationError} If the queue name is invalid
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * for await (const message of subscribeToQueue({
+ *     queueName: 'order-processing',
+ *     baseUrl: 'https://catalyst.agentuity.cloud',
+ *     signal: controller.signal,
+ * })) {
+ *     console.log('Received:', message.id, message.payload);
+ * }
+ * ```
+ */
+export declare function subscribeToQueue(options: SubscribeToQueueOptions): AsyncGenerator<Message, void, unknown>;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/services/queue/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../../src/services/queue/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAU1C,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAC5B,YAAY,GACZ,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,QAAQ,CAAC;AAEZ,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B;;;;qCAQpB,OAAO,KAAK,IAAI,YAAhB,OAAO,KAAK,IAAI;4CAEZ,IAAI,QAAJ,IAAI;8CAEX,MAAM,UAAU,MAAM,KAAK,IAAI,SAA/B,MAAM,UAAU,MAAM,KAAK,IAAI;+CAI9B,KAAK,KAAK,IAAI,UAAd,KAAK,KAAK,IAAI;;;;;;;;iBAsB9B,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACxC,+DAA+D;IAC/D,KAAK,IAAI,IAAI,CAAC;IACd,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,yDAAyD;AACzD,eAAO,MAAM,6BAA6B;;;;;;;;iBAiBxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAqCpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,wBAAwB,CA+M7F;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,gBAAgB,CACtC,OAAO,EAAE,uBAAuB,GAC9B,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAmGxC"}