@bloomneo/appkit 1.2.9

package/dist/storage/strategies/r2.js

@@ -0,0 +1,470 @@
+/**
+ * Cloudflare R2 storage strategy with zero egress fees and automatic CDN integration
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/strategies/r2.ts
+ *
+ * @llm-rule WHEN: App has CLOUDFLARE_R2_BUCKET env var for cost-effective distributed storage
+ * @llm-rule AVOID: Manual R2 setup - this handles connection, CDN integration, and S3-compatible API
+ * @llm-rule NOTE: Production-ready with zero egress fees, automatic CDN, S3-compatible operations
+ */
+/**
+ * Cloudflare R2 storage strategy with cost optimization and CDN integration
+ */
+export class R2Strategy {
+    config;
+    r2Client = null;
+    connected = false;
+    bucket;
+    accountId;
+    cdnUrl;
+    endpoint;
+    /**
+     * Creates R2 strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Storage initialization with Cloudflare R2 environment variables detected
+     * @llm-rule AVOID: Manual R2 configuration - environment detection handles Cloudflare specifics
+     */
+    constructor(config) {
+        this.config = config;
+        if (!config.r2) {
+            throw new Error('R2 storage configuration missing');
+        }
+        this.bucket = config.r2.bucket;
+        this.accountId = config.r2.accountId;
+        this.cdnUrl = config.r2.cdnUrl;
+        // Build R2 endpoint URL
+        this.endpoint = `https://${this.accountId}.r2.cloudflarestorage.com`;
+    }
+    /**
+     * Connects to Cloudflare R2 with automatic account validation
+     * @llm-rule WHEN: Storage initialization or reconnection after failure
+     * @llm-rule AVOID: Manual R2 client setup - this handles Cloudflare-specific configuration
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        try {
+            // Dynamic import for S3 client (R2 is S3-compatible)
+            const { S3Client } = await import('@aws-sdk/client-s3');
+            const r2Config = this.config.r2;
+            // Build R2 client configuration (S3-compatible)
+            const clientConfig = {
+                region: 'auto', // R2 uses 'auto' region
+                endpoint: this.endpoint,
+                credentials: {
+                    accessKeyId: r2Config.accessKeyId,
+                    secretAccessKey: r2Config.secretAccessKey,
+                },
+                forcePathStyle: false, // R2 uses virtual-hosted-style
+                maxAttempts: 3, // Built-in retry logic
+            };
+            // Create R2 client using S3 SDK
+            this.r2Client = new S3Client(clientConfig);
+            // Test connection by checking if bucket exists
+            await this.testConnection();
+            this.connected = true;
+            if (this.config.environment.isDevelopment) {
+                console.log(`✅ [AppKit] R2 storage connected (account: ${this.accountId}, bucket: ${this.bucket})`);
+                if (this.cdnUrl) {
+                    console.log(`🚀 [AppKit] R2 CDN enabled: ${this.cdnUrl}`);
+                }
+            }
+        }
+        catch (error) {
+            this.connected = false;
+            this.r2Client = null;
+            throw new Error(`R2 storage connection failed: ${error.message}`);
+        }
+    }
+    /**
+     * Tests R2 connection by checking bucket access
+     */
+    async testConnection() {
+        const { HeadBucketCommand } = await import('@aws-sdk/client-s3');
+        try {
+            await this.r2Client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+        }
+        catch (error) {
+            if (error.name === 'NotFound') {
+                throw new Error(`R2 bucket not found: ${this.bucket}`);
+            }
+            if (error.name === 'Forbidden') {
+                throw new Error(`R2 bucket access denied: ${this.bucket}. Check API token permissions.`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Stores file to R2 with automatic content type detection and zero egress cost
+     * @llm-rule WHEN: Uploading files to Cloudflare R2 for cost-effective storage
+     * @llm-rule AVOID: Manual R2 operations - this handles R2-specific optimizations
+     */
+    async put(key, data, options) {
+        if (!this.connected || !this.r2Client) {
+            throw new Error('R2 storage not connected');
+        }
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            // Build R2 put parameters (S3-compatible)
+            const params = {
+                Bucket: this.bucket,
+                Key: key,
+                Body: data,
+                ContentType: options?.contentType || this.detectContentType(key, data),
+            };
+            // Add R2-optimized parameters
+            if (options?.cacheControl) {
+                params.CacheControl = options.cacheControl;
+            }
+            else {
+                // R2 default cache control for better CDN performance
+                params.CacheControl = 'public, max-age=31536000'; // 1 year for static assets
+            }
+            if (options?.expires) {
+                params.Expires = options.expires;
+            }
+            if (options?.metadata) {
+                params.Metadata = options.metadata;
+            }
+            // Execute upload to R2
+            await this.r2Client.send(new PutObjectCommand(params));
+            if (this.config.environment.isDevelopment) {
+                console.log(`☁️ [AppKit] R2 file uploaded: ${key} (${data.length} bytes, zero egress cost)`);
+            }
+            return key;
+        }
+        catch (error) {
+            throw new Error(`R2 upload failed: ${error.message}`);
+        }
+    }
+    /**
+     * Retrieves file from R2 with streaming support and zero egress cost
+     * @llm-rule WHEN: Downloading files from Cloudflare R2
+     * @llm-rule AVOID: Manual R2 operations - this handles streaming and cost optimization
+     */
+    async get(key) {
+        if (!this.connected || !this.r2Client) {
+            throw new Error('R2 storage not connected');
+        }
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                Key: key,
+            };
+            const result = await this.r2Client.send(new GetObjectCommand(params));
+            if (!result.Body) {
+                throw new Error(`R2 object has no body: ${key}`);
+            }
+            // Convert stream to buffer
+            const buffer = await this.streamToBuffer(result.Body);
+            if (this.config.environment.isDevelopment) {
+                console.log(`☁️ [AppKit] R2 file downloaded: ${key} (${buffer.length} bytes, zero egress cost)`);
+            }
+            return buffer;
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey') {
+                throw new Error(`File not found: ${key}`);
+            }
+            throw new Error(`R2 download failed: ${error.message}`);
+        }
+    }
+    /**
+     * Deletes file from R2 with confirmation
+     * @llm-rule WHEN: Removing files from Cloudflare R2 storage
+     * @llm-rule AVOID: Silent failures - this confirms deletion success
+     */
+    async delete(key) {
+        if (!this.connected || !this.r2Client) {
+            console.error('R2 storage not connected');
+            return false;
+        }
+        try {
+            const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                Key: key,
+            };
+            await this.r2Client.send(new DeleteObjectCommand(params));
+            if (this.config.environment.isDevelopment) {
+                console.log(`🗑️ [AppKit] R2 file deleted: ${key}`);
+            }
+            return true;
+        }
+        catch (error) {
+            console.error(`[AppKit] R2 delete error for "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Lists files with prefix filtering and R2-optimized pagination
+     * @llm-rule WHEN: Browsing R2 files or implementing file managers
+     * @llm-rule AVOID: Loading all objects - R2 has same limits as S3
+     */
+    async list(prefix = '') {
+        if (!this.connected || !this.r2Client) {
+            throw new Error('R2 storage not connected');
+        }
+        try {
+            const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                MaxKeys: 1000, // R2 limit same as S3
+            };
+            if (prefix) {
+                params.Prefix = prefix;
+            }
+            const result = await this.r2Client.send(new ListObjectsV2Command(params));
+            const files = [];
+            if (result.Contents) {
+                for (const object of result.Contents) {
+                    if (object.Key) {
+                        files.push({
+                            key: object.Key,
+                            size: object.Size || 0,
+                            lastModified: object.LastModified || new Date(),
+                            etag: object.ETag?.replace(/"/g, ''), // Remove quotes from ETag
+                            contentType: await this.getObjectContentType(object.Key),
+                        });
+                    }
+                }
+            }
+            if (this.config.environment.isDevelopment) {
+                console.log(`☁️ [AppKit] R2 files listed: ${prefix}* (${files.length} files)`);
+            }
+            return files;
+        }
+        catch (error) {
+            console.error(`[AppKit] R2 list error for prefix "${prefix}":`, error.message);
+            return [];
+        }
+    }
+    /**
+     * Gets CDN or public URL for R2 object with automatic CDN detection
+     * @llm-rule WHEN: Generating URLs for R2 file access with CDN optimization
+     * @llm-rule AVOID: Hardcoded URLs - this handles CDN and R2-specific URLs
+     */
+    url(key) {
+        // Use custom CDN URL if configured (recommended for production)
+        if (this.cdnUrl) {
+            const baseUrl = this.cdnUrl.endsWith('/') ? this.cdnUrl : this.cdnUrl + '/';
+            const cleanKey = key.startsWith('/') ? key.slice(1) : key;
+            return baseUrl + cleanKey;
+        }
+        // Use R2 public URL (has rate limits, CDN recommended)
+        return `https://pub-${this.generatePublicHash()}.r2.dev/${key}`;
+    }
+    /**
+     * Generates R2 public URL hash (simplified for demo)
+     */
+    generatePublicHash() {
+        // In production, this would be the actual R2 public URL hash
+        // For now, we'll use a placeholder that works with the R2 endpoint
+        return this.accountId.slice(0, 8);
+    }
+    /**
+     * Generates signed URL for temporary R2 object access
+     * @llm-rule WHEN: Creating temporary download/upload links for R2 objects
+     * @llm-rule AVOID: Public URLs for private files - use signed URLs with expiration
+     */
+    async signedUrl(key, expiresIn = 3600) {
+        if (!this.connected || !this.r2Client) {
+            throw new Error('R2 storage not connected');
+        }
+        try {
+            const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+            const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
+            const command = new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+            });
+            const signedUrl = await getSignedUrl(this.r2Client, command, {
+                expiresIn,
+            });
+            if (this.config.environment.isDevelopment) {
+                console.log(`🔐 [AppKit] R2 signed URL generated: ${key} (expires in ${expiresIn}s)`);
+            }
+            return signedUrl;
+        }
+        catch (error) {
+            throw new Error(`R2 signed URL generation failed: ${error.message}`);
+        }
+    }
+    /**
+     * Checks if R2 object exists without downloading
+     * @llm-rule WHEN: Validating R2 object existence efficiently
+     * @llm-rule AVOID: Downloading objects just to check existence
+     */
+    async exists(key) {
+        if (!this.connected || !this.r2Client) {
+            return false;
+        }
+        try {
+            const { HeadObjectCommand } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                Key: key,
+            };
+            await this.r2Client.send(new HeadObjectCommand(params));
+            return true;
+        }
+        catch (error) {
+            if (error.name === 'NotFound' || error.name === 'NoSuchKey') {
+                return false;
+            }
+            console.error(`[AppKit] R2 exists check error for "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Copies R2 object efficiently using server-side copy (zero egress cost)
+     * @llm-rule WHEN: Duplicating R2 objects without bandwidth costs
+     * @llm-rule AVOID: Download and upload - R2 server-side copy has zero egress fees
+     */
+    async copy(sourceKey, destKey) {
+        if (!this.connected || !this.r2Client) {
+            throw new Error('R2 storage not connected');
+        }
+        try {
+            const { CopyObjectCommand } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                Key: destKey,
+                CopySource: `${this.bucket}/${sourceKey}`,
+            };
+            await this.r2Client.send(new CopyObjectCommand(params));
+            if (this.config.environment.isDevelopment) {
+                console.log(`☁️ [AppKit] R2 file copied: ${sourceKey} → ${destKey} (zero egress cost)`);
+            }
+            return destKey;
+        }
+        catch (error) {
+            throw new Error(`R2 copy failed: ${error.message}`);
+        }
+    }
+    /**
+     * Disconnects R2 strategy gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents connection issues
+     */
+    async disconnect() {
+        if (!this.connected)
+            return;
+        try {
+            // R2 client doesn't need explicit disconnection (uses S3 SDK)
+            this.connected = false;
+            this.r2Client = null;
+            if (this.config.environment.isDevelopment) {
+                console.log(`👋 [AppKit] R2 storage strategy disconnected`);
+            }
+        }
+        catch (error) {
+            console.error(`[AppKit] R2 disconnect error:`, error.message);
+        }
+    }
+    // Private helper methods
+    /**
+     * Converts readable stream to buffer
+     */
+    async streamToBuffer(stream) {
+        const chunks = [];
+        return new Promise((resolve, reject) => {
+            stream.on('data', (chunk) => chunks.push(chunk));
+            stream.on('error', reject);
+            stream.on('end', () => resolve(Buffer.concat(chunks)));
+        });
+    }
+    /**
+     * Detects content type from file extension and buffer
+     */
+    detectContentType(key, buffer) {
+        // Get extension from key
+        const ext = key.split('.').pop()?.toLowerCase();
+        // Common MIME types optimized for web delivery
+        const mimeTypes = {
+            'jpg': 'image/jpeg',
+            'jpeg': 'image/jpeg',
+            'png': 'image/png',
+            'gif': 'image/gif',
+            'webp': 'image/webp',
+            'avif': 'image/avif', // Modern format support
+            'svg': 'image/svg+xml',
+            'pdf': 'application/pdf',
+            'txt': 'text/plain',
+            'json': 'application/json',
+            'csv': 'text/csv',
+            'zip': 'application/zip',
+            'mp4': 'video/mp4',
+            'webm': 'video/webm',
+            'mp3': 'audio/mpeg',
+            'wav': 'audio/wav',
+            'woff2': 'font/woff2',
+            'woff': 'font/woff',
+            'css': 'text/css',
+            'js': 'text/javascript',
+        };
+        if (ext && mimeTypes[ext]) {
+            return mimeTypes[ext];
+        }
+        // Buffer-based detection for common formats
+        const magic = buffer.subarray(0, 4);
+        if (magic[0] === 0xFF && magic[1] === 0xD8 && magic[2] === 0xFF) {
+            return 'image/jpeg';
+        }
+        if (magic[0] === 0x89 && magic[1] === 0x50 && magic[2] === 0x4E && magic[3] === 0x47) {
+            return 'image/png';
+        }
+        if (magic[0] === 0x47 && magic[1] === 0x49 && magic[2] === 0x46) {
+            return 'image/gif';
+        }
+        return 'application/octet-stream';
+    }
+    /**
+     * Gets content type for existing R2 object
+     */
+    async getObjectContentType(key) {
+        try {
+            const { HeadObjectCommand } = await import('@aws-sdk/client-s3');
+            const params = {
+                Bucket: this.bucket,
+                Key: key,
+            };
+            const result = await this.r2Client.send(new HeadObjectCommand(params));
+            return result.ContentType;
+        }
+        catch (error) {
+            // If we can't get content type, return undefined
+            return undefined;
+        }
+    }
+    /**
+     * Gets R2 connection info for debugging
+     */
+    getConnectionInfo() {
+        return {
+            connected: this.connected,
+            bucket: this.bucket,
+            accountId: this.accountId,
+            endpoint: this.endpoint,
+            cdnEnabled: !!this.cdnUrl,
+            zeroEgressFees: true, // R2's key advantage
+        };
+    }
+    /**
+     * Gets R2-specific cost optimization info
+     */
+    getCostInfo() {
+        return {
+            egressFees: 'Zero egress fees',
+            storageClass: 'Hot storage with instant access',
+            cdnIntegration: !!this.cdnUrl,
+            recommendedFor: [
+                'High-bandwidth applications',
+                'Media streaming',
+                'Global CDN delivery',
+                'Cost-sensitive workloads'
+            ],
+        };
+    }
+}
+//# sourceMappingURL=r2.js.map

package/dist/storage/strategies/r2.js.map

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

package/dist/storage/strategies/s3.d.ts

@@ -0,0 +1,121 @@
+/**
+ * S3-compatible storage strategy with automatic connection management and multi-provider support
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/strategies/s3.ts
+ *
+ * @llm-rule WHEN: App has AWS_S3_BUCKET or S3_ENDPOINT env vars for distributed cloud storage
+ * @llm-rule AVOID: Manual S3 setup - this handles AWS, Wasabi, MinIO, DigitalOcean Spaces automatically
+ * @llm-rule NOTE: Production-ready with retry logic, signed URLs, CDN support, automatic MIME detection
+ */
+import type { StorageStrategy, StorageFile, PutOptions } from '../storage.js';
+import type { StorageConfig } from '../defaults.js';
+/**
+ * S3-compatible storage strategy with multi-provider support and reliability features
+ */
+export declare class S3Strategy implements StorageStrategy {
+    private config;
+    private s3Client;
+    private connected;
+    private bucket;
+    private region;
+    private endpoint?;
+    private cdnUrl?;
+    /**
+     * Creates S3 strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Storage initialization with S3-compatible environment variables detected
+     * @llm-rule AVOID: Manual S3 configuration - environment detection handles AWS/Wasabi/MinIO
+     */
+    constructor(config: StorageConfig);
+    /**
+     * Connects to S3-compatible service with automatic retry and provider detection
+     * @llm-rule WHEN: Storage initialization or reconnection after failure
+     * @llm-rule AVOID: Manual S3 client setup - this handles all provider configurations
+     */
+    connect(): Promise<void>;
+    /**
+     * Tests S3 connection by checking bucket access
+     */
+    private testConnection;
+    /**
+     * Detects S3 provider from configuration
+     */
+    private detectProvider;
+    /**
+     * Stores file to S3 with automatic content type detection and metadata
+     * @llm-rule WHEN: Uploading files to S3-compatible cloud storage
+     * @llm-rule AVOID: Manual S3 operations - this handles multipart uploads and metadata
+     */
+    put(key: string, data: Buffer, options?: PutOptions): Promise<string>;
+    /**
+     * Retrieves file from S3 with streaming support
+     * @llm-rule WHEN: Downloading files from S3-compatible storage
+     * @llm-rule AVOID: Manual S3 operations - this handles streaming and errors
+     */
+    get(key: string): Promise<Buffer>;
+    /**
+     * Deletes file from S3 with confirmation
+     * @llm-rule WHEN: Removing files from S3-compatible storage
+     * @llm-rule AVOID: Silent failures - this confirms deletion success
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Lists files with prefix filtering and pagination
+     * @llm-rule WHEN: Browsing S3 files or implementing file managers
+     * @llm-rule AVOID: Loading all objects - use prefix filtering and pagination
+     */
+    list(prefix?: string): Promise<StorageFile[]>;
+    /**
+     * Gets public or CDN URL for S3 object
+     * @llm-rule WHEN: Generating URLs for S3 file access with CDN support
+     * @llm-rule AVOID: Hardcoded URLs - this handles CDN and region-specific URLs
+     */
+    url(key: string): string;
+    /**
+     * Generates signed URL for temporary S3 object access
+     * @llm-rule WHEN: Creating temporary download/upload links for S3 objects
+     * @llm-rule AVOID: Permanent URLs for private files - use signed URLs with expiration
+     */
+    signedUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Checks if S3 object exists without downloading
+     * @llm-rule WHEN: Validating S3 object existence efficiently
+     * @llm-rule AVOID: Downloading objects just to check existence
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Copies S3 object efficiently using server-side copy
+     * @llm-rule WHEN: Duplicating S3 objects without downloading/uploading
+     * @llm-rule AVOID: Download and upload - S3 server-side copy is much faster
+     */
+    copy(sourceKey: string, destKey: string): Promise<string>;
+    /**
+     * Disconnects S3 strategy gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents connection issues
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Converts readable stream to buffer
+     */
+    private streamToBuffer;
+    /**
+     * Detects content type from file extension and buffer
+     */
+    private detectContentType;
+    /**
+     * Gets content type for existing S3 object
+     */
+    private getObjectContentType;
+    /**
+     * Gets S3 connection info for debugging
+     */
+    getConnectionInfo(): {
+        connected: boolean;
+        bucket: string;
+        region: string;
+        endpoint?: string;
+        provider: string;
+        cdnEnabled: boolean;
+    };
+}
+//# sourceMappingURL=s3.d.ts.map

package/dist/storage/strategies/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../../src/storage/strategies/s3.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;GAEG;AACH,qBAAa,UAAW,YAAW,eAAe;IAChD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAS;IAExB;;;;OAIG;gBACS,MAAM,EAAE,aAAa;IAajC;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C9B;;OAEG;YACW,cAAc;IAgB5B;;OAEG;IACH,OAAO,CAAC,cAAc;IAatB;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA0C3E;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmCvC;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B3C;;;;OAIG;IACG,IAAI,CAAC,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA8CvD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAmBxB;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BvE;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB3C;;;;OAIG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0B/D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBjC;;OAEG;YACW,cAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6CzB;;OAEG;YACW,oBAAoB;IAiBlC;;OAEG;IACH,iBAAiB,IAAI;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB;CAUF"}