ai-database 2.1.1 → 2.3.0

package/dist/errors.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Error handling utilities for ai-database
+ *
+ * These utilities help distinguish between expected errors that can be safely
+ * ignored and unexpected errors that should be propagated or logged.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Check if an error is a "not found" error that can be safely ignored
+ * when the operation is expected to potentially return nothing.
+ */
+export declare function isNotFoundError(error: unknown): boolean;
+/**
+ * Check if an error is a duplicate key/entity exists error.
+ * These can be safely ignored when creating entities that may already exist.
+ */
+export declare function isEntityExistsError(error: unknown): boolean;
+/**
+ * Check if an error is an expected error that can be safely handled
+ * without re-throwing. This includes not found and entity exists errors.
+ */
+export declare function isExpectedError(error: unknown): boolean;
+/**
+ * Custom error class for database operations with context
+ */
+export declare class DatabaseError extends Error {
+    operation: string;
+    entityType: string;
+    entityId?: string | undefined;
+    cause?: Error | undefined;
+    constructor(message: string, operation: string, entityType: string, entityId?: string | undefined, cause?: Error | undefined);
+}
+/**
+ * Wrap an error with database operation context
+ */
+export declare function wrapDatabaseError(error: unknown, operation: string, entityType: string, entityId?: string): DatabaseError;
+/**
+ * Error thrown when an entity is not found in the database.
+ *
+ * @example
+ * ```ts
+ * throw new EntityNotFoundError('User', 'user-123', 'get')
+ * // Error: Entity not found: User/user-123 (operation: get)
+ * ```
+ */
+export declare class EntityNotFoundError extends DatabaseError {
+    readonly code = "ENTITY_NOT_FOUND";
+    constructor(entityType: string, entityId: string, operation?: string, cause?: Error);
+}
+/**
+ * Error thrown when attempting to create an entity that already exists.
+ *
+ * @example
+ * ```ts
+ * throw new EntityAlreadyExistsError('User', 'user-123', 'create')
+ * // Error: Entity already exists: User/user-123 (operation: create)
+ * ```
+ */
+export declare class EntityAlreadyExistsError extends DatabaseError {
+    readonly code = "ENTITY_ALREADY_EXISTS";
+    constructor(entityType: string, entityId: string, operation?: string, cause?: Error);
+}
+/**
+ * Error thrown when validation of input data fails.
+ *
+ * @example
+ * ```ts
+ * throw new ValidationError('Invalid email format', 'User', 'email', 'not-an-email')
+ * // Error: Validation failed for User.email: Invalid email format
+ * ```
+ */
+export declare class ValidationError extends DatabaseError {
+    readonly field?: string | undefined;
+    readonly value?: unknown | undefined;
+    readonly code = "VALIDATION_ERROR";
+    constructor(message: string, entityType: string, field?: string | undefined, value?: unknown | undefined, cause?: Error);
+}
+/**
+ * Error thrown when AI generation fails.
+ *
+ * @example
+ * ```ts
+ * throw new AIGenerationError('Failed to generate description', 'Product', 'description', err)
+ * // Error: AI generation failed for Product.description: Failed to generate description
+ * ```
+ */
+export declare class AIGenerationError extends DatabaseError {
+    readonly field?: string | undefined;
+    readonly code = "AI_GENERATION_ERROR";
+    constructor(message: string, entityType: string, field?: string | undefined, cause?: Error);
+}
+/**
+ * Error thrown when semantic search operations fail.
+ *
+ * @example
+ * ```ts
+ * throw new SemanticSearchError('Embedding generation failed', 'Product', 'search query', err)
+ * // Error: Semantic search failed for Product: Embedding generation failed
+ * ```
+ */
+export declare class SemanticSearchError extends DatabaseError {
+    readonly query?: string | undefined;
+    readonly code = "SEMANTIC_SEARCH_ERROR";
+    constructor(message: string, entityType: string, query?: string | undefined, cause?: Error);
+}
+/**
+ * Error thrown when an adapter cannot perform a Tier 4 (vector search)
+ * query because the backing index is not configured.
+ *
+ * Distinct from {@link CapabilityNotSupportedError}: that error means the
+ * adapter never claims vector search; this error means the adapter would
+ * support vector search if its sidecar / extension / index were present
+ * but at runtime it isn't (e.g., DO SQLite without a Vectorize binding).
+ *
+ * @example
+ * ```ts
+ * throw new VectorSearchUnavailableError('do-sqlite', 'no Vectorize binding configured')
+ * ```
+ */
+export declare class VectorSearchUnavailableError extends DatabaseError {
+    readonly adapter: string;
+    readonly code = "VECTOR_SEARCH_UNAVAILABLE";
+    constructor(adapter: string, reason: string, cause?: Error);
+}
+export { CapabilityNotSupportedError, isCapabilityNotSupportedError, } from './provider-capabilities.js';
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBvD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuB3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAG7B,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,MAAM;IAClB,QAAQ,CAAC,EAAE,MAAM;IACR,KAAK,CAAC,EAAE,KAAK;gBAJ7B,OAAO,EAAE,MAAM,EACR,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,YAAA,EACR,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAIf;AAMD;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,SAAgB,IAAI,sBAAqB;gBAE7B,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3F;AAED;;;;;;;;GAQG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,SAAgB,IAAI,2BAA0B;gBAElC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAiB,EAAE,KAAK,CAAC,EAAE,KAAK;CAI9F;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAgB,SAAQ,aAAa;aAM9B,KAAK,CAAC,EAAE,MAAM;aACd,KAAK,CAAC,EAAE,OAAO;IANjC,SAAgB,IAAI,sBAAqB;gBAGvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EACF,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,KAAK,CAAC,EAAE,OAAO,YAAA,EAC/B,KAAK,CAAC,EAAE,KAAK;CAOhB;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;aAGe,KAAK,CAAC,EAAE,MAAM;IAF/E,SAAgB,IAAI,yBAAwB;gBAEhC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,MAAM,YAAA,EAAE,KAAK,CAAC,EAAE,KAAK;CAM/F;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;aAGa,KAAK,CAAC,EAAE,MAAM;IAF/E,SAAgB,IAAI,2BAA0B;gBAElC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,MAAM,YAAA,EAAE,KAAK,CAAC,EAAE,KAAK;CAK/F;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,4BAA6B,SAAQ,aAAa;aAGjC,OAAO,EAAE,MAAM;IAF3C,SAAgB,IAAI,+BAA8B;gBAEtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAU3E;AAGD,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,GAC9B,MAAM,4BAA4B,CAAA"}

package/dist/errors.js

@@ -0,0 +1,210 @@
+/**
+ * Error handling utilities for ai-database
+ *
+ * These utilities help distinguish between expected errors that can be safely
+ * ignored and unexpected errors that should be propagated or logged.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Check if an error is a "not found" error that can be safely ignored
+ * when the operation is expected to potentially return nothing.
+ */
+export function isNotFoundError(error) {
+    // Check for custom EntityNotFoundError class
+    if (error && typeof error === 'object' && 'code' in error) {
+        if (error.code === 'ENTITY_NOT_FOUND') {
+            return true;
+        }
+    }
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return (message.includes('not found') ||
+            message.includes('does not exist') ||
+            message.includes('no such') ||
+            error.code === 'NOT_FOUND' ||
+            error.code === 'SQLITE_NOTFOUND' ||
+            error.code === 'ENOENT');
+    }
+    return false;
+}
+/**
+ * Check if an error is a duplicate key/entity exists error.
+ * These can be safely ignored when creating entities that may already exist.
+ */
+export function isEntityExistsError(error) {
+    // Check for custom EntityAlreadyExistsError class
+    if (error && typeof error === 'object' && 'code' in error) {
+        if (error.code === 'ENTITY_ALREADY_EXISTS') {
+            return true;
+        }
+    }
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return (message.includes('already exists') ||
+            message.includes('duplicate key') ||
+            message.includes('duplicate entry') ||
+            message.includes('unique constraint') ||
+            error.code === 'DUPLICATE_KEY' ||
+            error.code === 'SQLITE_CONSTRAINT_UNIQUE' ||
+            error.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' ||
+            error.code === 'ER_DUP_ENTRY' ||
+            error.code === '23505' // PostgreSQL unique violation
+        );
+    }
+    return false;
+}
+/**
+ * Check if an error is an expected error that can be safely handled
+ * without re-throwing. This includes not found and entity exists errors.
+ */
+export function isExpectedError(error) {
+    return isNotFoundError(error) || isEntityExistsError(error);
+}
+/**
+ * Custom error class for database operations with context
+ */
+export class DatabaseError extends Error {
+    operation;
+    entityType;
+    entityId;
+    cause;
+    constructor(message, operation, entityType, entityId, cause) {
+        super(`${operation} ${entityType}${entityId ? `/${entityId}` : ''}: ${message}`);
+        this.operation = operation;
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.cause = cause;
+        this.name = 'DatabaseError';
+    }
+}
+/**
+ * Wrap an error with database operation context
+ */
+export function wrapDatabaseError(error, operation, entityType, entityId) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error ? error : undefined;
+    return new DatabaseError(message, operation, entityType, entityId, cause);
+}
+// =============================================================================
+// Custom Error Classes
+// =============================================================================
+/**
+ * Error thrown when an entity is not found in the database.
+ *
+ * @example
+ * ```ts
+ * throw new EntityNotFoundError('User', 'user-123', 'get')
+ * // Error: Entity not found: User/user-123 (operation: get)
+ * ```
+ */
+export class EntityNotFoundError extends DatabaseError {
+    code = 'ENTITY_NOT_FOUND';
+    constructor(entityType, entityId, operation = 'get', cause) {
+        super('Entity not found', operation, entityType, entityId, cause);
+        this.name = 'EntityNotFoundError';
+    }
+}
+/**
+ * Error thrown when attempting to create an entity that already exists.
+ *
+ * @example
+ * ```ts
+ * throw new EntityAlreadyExistsError('User', 'user-123', 'create')
+ * // Error: Entity already exists: User/user-123 (operation: create)
+ * ```
+ */
+export class EntityAlreadyExistsError extends DatabaseError {
+    code = 'ENTITY_ALREADY_EXISTS';
+    constructor(entityType, entityId, operation = 'create', cause) {
+        super('Entity already exists', operation, entityType, entityId, cause);
+        this.name = 'EntityAlreadyExistsError';
+    }
+}
+/**
+ * Error thrown when validation of input data fails.
+ *
+ * @example
+ * ```ts
+ * throw new ValidationError('Invalid email format', 'User', 'email', 'not-an-email')
+ * // Error: Validation failed for User.email: Invalid email format
+ * ```
+ */
+export class ValidationError extends DatabaseError {
+    field;
+    value;
+    code = 'VALIDATION_ERROR';
+    constructor(message, entityType, field, value, cause) {
+        const fieldInfo = field ? `.${field}` : '';
+        const fullMessage = `Validation failed for ${entityType}${fieldInfo}: ${message}`;
+        super(fullMessage, 'validate', entityType, undefined, cause);
+        this.field = field;
+        this.value = value;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Error thrown when AI generation fails.
+ *
+ * @example
+ * ```ts
+ * throw new AIGenerationError('Failed to generate description', 'Product', 'description', err)
+ * // Error: AI generation failed for Product.description: Failed to generate description
+ * ```
+ */
+export class AIGenerationError extends DatabaseError {
+    field;
+    code = 'AI_GENERATION_ERROR';
+    constructor(message, entityType, field, cause) {
+        const fieldInfo = field ? `.${field}` : '';
+        const fullMessage = `AI generation failed for ${entityType}${fieldInfo}: ${message}`;
+        super(fullMessage, 'generate', entityType, undefined, cause);
+        this.field = field;
+        this.name = 'AIGenerationError';
+    }
+}
+/**
+ * Error thrown when semantic search operations fail.
+ *
+ * @example
+ * ```ts
+ * throw new SemanticSearchError('Embedding generation failed', 'Product', 'search query', err)
+ * // Error: Semantic search failed for Product: Embedding generation failed
+ * ```
+ */
+export class SemanticSearchError extends DatabaseError {
+    query;
+    code = 'SEMANTIC_SEARCH_ERROR';
+    constructor(message, entityType, query, cause) {
+        const fullMessage = `Semantic search failed for ${entityType}: ${message}`;
+        super(fullMessage, 'semanticSearch', entityType, undefined, cause);
+        this.query = query;
+        this.name = 'SemanticSearchError';
+    }
+}
+/**
+ * Error thrown when an adapter cannot perform a Tier 4 (vector search)
+ * query because the backing index is not configured.
+ *
+ * Distinct from {@link CapabilityNotSupportedError}: that error means the
+ * adapter never claims vector search; this error means the adapter would
+ * support vector search if its sidecar / extension / index were present
+ * but at runtime it isn't (e.g., DO SQLite without a Vectorize binding).
+ *
+ * @example
+ * ```ts
+ * throw new VectorSearchUnavailableError('do-sqlite', 'no Vectorize binding configured')
+ * ```
+ */
+export class VectorSearchUnavailableError extends DatabaseError {
+    adapter;
+    code = 'VECTOR_SEARCH_UNAVAILABLE';
+    constructor(adapter, reason, cause) {
+        super(`Vector search unavailable on ${adapter}: ${reason}`, 'vectorSearch', 'unknown', undefined, cause);
+        this.adapter = adapter;
+        this.name = 'VectorSearchUnavailableError';
+    }
+}
+// Re-export CapabilityNotSupportedError for convenience
+export { CapabilityNotSupportedError, isCapabilityNotSupportedError, } from './provider-capabilities.js';
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/eventbridge.d.ts

@@ -0,0 +1,117 @@
+/**
+ * EventBridge with Cloudflare Queues
+ *
+ * Enables publishing database events to Cloudflare Queues for async processing.
+ * Supports:
+ * - Publishing events to queues with optional delays
+ * - Batch publishing for efficiency
+ * - Event routing based on patterns
+ * - Dead letter queue (DLQ) handling for failed events
+ * - Message processing with retry logic
+ * - Statistics tracking
+ *
+ * @packageDocumentation
+ */
+/**
+ * Cloudflare Queue message type
+ */
+export interface QueueMessage<T = unknown> {
+    id: string;
+    timestamp: Date;
+    body: T;
+    attempts: number;
+}
+/**
+ * Cloudflare Queue binding interface
+ */
+export interface QueueBinding {
+    send(message: unknown, options?: {
+        delaySeconds?: number;
+    }): Promise<void>;
+    sendBatch(messages: Array<{
+        body: unknown;
+        delaySeconds?: number;
+    }>): Promise<void>;
+}
+/**
+ * EventBridge configuration
+ */
+export interface EventBridgeConfig {
+    /** The Cloudflare Queue binding for publishing events */
+    queue?: QueueBinding;
+    /** Dead letter queue for failed events */
+    dlq?: QueueBinding;
+    /** Maximum retry attempts before sending to DLQ */
+    maxRetries?: number;
+    /** Batch size for bulk publishing */
+    batchSize?: number;
+    /** Event patterns to route to specific queues */
+    routes?: Record<string, QueueBinding>;
+}
+/**
+ * Event to publish
+ */
+export interface PublishEvent {
+    event: string;
+    data?: unknown;
+    actor?: string;
+    object?: string;
+    delay?: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Published event with generated fields
+ */
+export interface PublishedEvent extends PublishEvent {
+    id: string;
+    timestamp: string;
+}
+/**
+ * Result of processing messages
+ */
+export interface ProcessResult {
+    processed: number;
+    failed: number;
+    retried: number;
+    deadLettered: number;
+}
+/**
+ * Queue statistics
+ */
+export interface EventBridgeStats {
+    published: number;
+    processed: number;
+    failed: number;
+    deadLettered: number;
+    pending: number;
+}
+/**
+ * Subscription handler
+ */
+export type SubscriptionHandler = (message: QueueMessage) => Promise<void>;
+/**
+ * EventBridge API interface
+ */
+export interface EventBridgeAPI {
+    /** Publish an event to the queue */
+    publish(event: PublishEvent): Promise<void>;
+    /** Publish multiple events in a batch */
+    publishBatch(events: PublishEvent[]): Promise<void>;
+    /** Subscribe to events with a handler */
+    subscribe(pattern: string, handler: SubscriptionHandler): () => void;
+    /** Process incoming queue messages */
+    process(messages: QueueMessage[]): Promise<ProcessResult>;
+    /** Get queue statistics */
+    getStats(): EventBridgeStats;
+    /** Configure the bridge */
+    configure(config: EventBridgeConfig): void;
+}
+/**
+ * Create an EventBridge instance
+ */
+export declare function createEventBridge(): EventBridgeAPI;
+/**
+ * Create the EventBridge API factory for DB integration
+ */
+export declare function createEventBridgeAPI(): EventBridgeAPI;
+//# sourceMappingURL=eventbridge.d.ts.map

package/dist/eventbridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventbridge.d.ts","sourceRoot":"","sources":["../src/eventbridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,IAAI,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;IACP,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1E,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpF;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,YAAY,CAAA;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;AAU1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,yCAAyC;IACzC,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,yCAAyC;IACzC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAA;IACpE,sCAAsC;IACtC,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IACzD,2BAA2B;IAC3B,QAAQ,IAAI,gBAAgB,CAAA;IAC5B,2BAA2B;IAC3B,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC3C;AAgED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CA6LlD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAErD"}