@agirails/sdk 2.0.3 → 2.2.0

package/dist/utils/retry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Retry Utility - Exponential Backoff with Jitter (P1-2)
+ *
+ * Implements retry logic for storage operations with:
+ * - Exponential backoff (doubles delay each attempt)
+ * - Random jitter (prevents thundering herd)
+ * - Maximum retry limit
+ * - Configurable retry conditions
+ *
+ * @module utils/retry
+ */
+/**
+ * Retry configuration options
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Jitter factor 0-1 (default: 0.1 = ±10%) */
+    jitterFactor?: number;
+    /** Function to determine if error is retryable (default: built-in check) */
+    isRetryable?: (error: unknown) => boolean;
+    /** Callback for each retry attempt (for logging) */
+    onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
+}
+/**
+ * Result of retry operation
+ */
+export interface RetryResult<T> {
+    /** Operation result (if successful) */
+    result?: T;
+    /** Final error (if all retries failed) */
+    error?: unknown;
+    /** Number of attempts made */
+    attempts: number;
+    /** Total time spent (including delays) */
+    totalTimeMs: number;
+    /** Whether operation succeeded */
+    success: boolean;
+}
+/**
+ * Default function to determine if error is retryable
+ *
+ * @param error - Error to check
+ * @returns True if error should trigger retry
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+export declare function calculateBackoffDelay(attempt: number, options?: RetryOptions): number;
+/**
+ * Execute async operation with retry logic
+ *
+ * Implements exponential backoff with jitter for handling transient failures.
+ * Particularly useful for storage operations that may fail due to:
+ * - Rate limiting
+ * - Network timeouts
+ * - Temporary service unavailability
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to operation result or throwing final error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await withRetry(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * // With logging
+ * const result = await withRetry(
+ *   () => client.downloadJSON(cid),
+ *   {
+ *     maxAttempts: 5,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt}, waiting ${delay}ms:`, error);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Execute async operation with retry logic, returning detailed result
+ *
+ * Unlike `withRetry`, this function never throws - it returns a result object
+ * with success/failure status and metadata.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to detailed result object
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetryResult(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Uploaded:', result.result);
+ * } else {
+ *   console.error(`Failed after ${result.attempts} attempts:`, result.error);
+ * }
+ * ```
+ */
+export declare function withRetryResult<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C,oDAAoD;IACpD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,uCAAuC;IACvC,MAAM,CAAC,EAAE,CAAC,CAAC;IAEX,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IAEpB,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;CAClB;AA0CD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CA0CxD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,MAAM,CAmBR;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CA8CZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA2DzB"}

package/dist/utils/retry.js

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * Retry Utility - Exponential Backoff with Jitter (P1-2)
+ *
+ * Implements retry logic for storage operations with:
+ * - Exponential backoff (doubles delay each attempt)
+ * - Random jitter (prevents thundering herd)
+ * - Maximum retry limit
+ * - Configurable retry conditions
+ *
+ * @module utils/retry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetryResult = exports.withRetry = exports.calculateBackoffDelay = exports.isRetryableError = void 0;
+const errors_1 = require("../errors");
+// ============================================================================
+// Constants
+// ============================================================================
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 10000; // Reduced from 30s to 10s (NEW-4: prevent long stalls)
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+const DEFAULT_JITTER_FACTOR = 0.1;
+/**
+ * Default list of retryable HTTP status codes
+ */
+const RETRYABLE_STATUS_CODES = new Set([
+    408, // Request Timeout
+    429, // Too Many Requests
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504 // Gateway Timeout
+]);
+/**
+ * Default list of retryable error codes
+ */
+const RETRYABLE_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+    'EPIPE',
+    'EHOSTUNREACH'
+]);
+// ============================================================================
+// Functions
+// ============================================================================
+/**
+ * Default function to determine if error is retryable
+ *
+ * @param error - Error to check
+ * @returns True if error should trigger retry
+ */
+function isRetryableError(error) {
+    if (!error)
+        return false;
+    // Rate limit errors are always retryable
+    if (error instanceof errors_1.StorageRateLimitError) {
+        return true;
+    }
+    const e = error;
+    // Check HTTP status codes
+    if (e.statusCode && RETRYABLE_STATUS_CODES.has(e.statusCode)) {
+        return true;
+    }
+    if (e.status && RETRYABLE_STATUS_CODES.has(e.status)) {
+        return true;
+    }
+    // Check error codes (network errors)
+    if (e.code && RETRYABLE_ERROR_CODES.has(e.code)) {
+        return true;
+    }
+    // Check for timeout errors
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+        return true;
+    }
+    // Check message for common retryable patterns
+    const message = String(e.message || e).toLowerCase();
+    if (message.includes('timeout') ||
+        message.includes('rate limit') ||
+        message.includes('too many requests') ||
+        message.includes('service unavailable') ||
+        message.includes('temporarily unavailable')) {
+        return true;
+    }
+    return false;
+}
+exports.isRetryableError = isRetryableError;
+/**
+ * Calculate delay with exponential backoff and jitter
+ *
+ * @param attempt - Current attempt number (1-based)
+ * @param options - Retry options
+ * @returns Delay in milliseconds
+ */
+function calculateBackoffDelay(attempt, options = {}) {
+    const { initialDelayMs = DEFAULT_INITIAL_DELAY_MS, maxDelayMs = DEFAULT_MAX_DELAY_MS, backoffMultiplier = DEFAULT_BACKOFF_MULTIPLIER, jitterFactor = DEFAULT_JITTER_FACTOR } = options;
+    // Exponential backoff: initialDelay * (multiplier ^ (attempt - 1))
+    const exponentialDelay = initialDelayMs * Math.pow(backoffMultiplier, attempt - 1);
+    // Cap at max delay
+    const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
+    // Add jitter: ±jitterFactor
+    const jitter = cappedDelay * jitterFactor * (Math.random() * 2 - 1);
+    const finalDelay = Math.max(0, cappedDelay + jitter);
+    return Math.round(finalDelay);
+}
+exports.calculateBackoffDelay = calculateBackoffDelay;
+/**
+ * Sleep for specified duration
+ *
+ * @param ms - Milliseconds to sleep
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Execute async operation with retry logic
+ *
+ * Implements exponential backoff with jitter for handling transient failures.
+ * Particularly useful for storage operations that may fail due to:
+ * - Rate limiting
+ * - Network timeouts
+ * - Temporary service unavailability
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to operation result or throwing final error
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = await withRetry(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * // With logging
+ * const result = await withRetry(
+ *   () => client.downloadJSON(cid),
+ *   {
+ *     maxAttempts: 5,
+ *     onRetry: (attempt, error, delay) => {
+ *       console.log(`Retry ${attempt}, waiting ${delay}ms:`, error);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+async function withRetry(operation, options = {}) {
+    const { maxAttempts = DEFAULT_MAX_ATTEMPTS, isRetryable = isRetryableError, onRetry } = options;
+    let lastError;
+    const startTime = Date.now();
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            // Check if this is the last attempt
+            if (attempt >= maxAttempts) {
+                break;
+            }
+            // Check if error is retryable
+            if (!isRetryable(error)) {
+                break;
+            }
+            // Calculate delay
+            let delayMs = calculateBackoffDelay(attempt, options);
+            // If rate limit error with retry-after header, use that instead
+            if (error instanceof errors_1.StorageRateLimitError && error.details?.retryAfter) {
+                delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+            }
+            // Notify callback
+            if (onRetry) {
+                onRetry(attempt, error, delayMs);
+            }
+            // Wait before retry
+            await sleep(delayMs);
+        }
+    }
+    // All retries failed
+    throw lastError;
+}
+exports.withRetry = withRetry;
+/**
+ * Execute async operation with retry logic, returning detailed result
+ *
+ * Unlike `withRetry`, this function never throws - it returns a result object
+ * with success/failure status and metadata.
+ *
+ * @param operation - Async function to execute
+ * @param options - Retry configuration
+ * @returns Promise resolving to detailed result object
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetryResult(
+ *   () => client.uploadJSON(data),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Uploaded:', result.result);
+ * } else {
+ *   console.error(`Failed after ${result.attempts} attempts:`, result.error);
+ * }
+ * ```
+ */
+async function withRetryResult(operation, options = {}) {
+    const { maxAttempts = DEFAULT_MAX_ATTEMPTS, isRetryable = isRetryableError, onRetry } = options;
+    let lastError;
+    const startTime = Date.now();
+    let attempts = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        attempts = attempt;
+        try {
+            const result = await operation();
+            return {
+                result,
+                attempts,
+                totalTimeMs: Date.now() - startTime,
+                success: true
+            };
+        }
+        catch (error) {
+            lastError = error;
+            // Check if this is the last attempt
+            if (attempt >= maxAttempts) {
+                break;
+            }
+            // Check if error is retryable
+            if (!isRetryable(error)) {
+                break;
+            }
+            // Calculate delay
+            let delayMs = calculateBackoffDelay(attempt, options);
+            // If rate limit error with retry-after header, use that instead
+            if (error instanceof errors_1.StorageRateLimitError && error.details?.retryAfter) {
+                delayMs = Math.max(delayMs, error.details.retryAfter * 1000);
+            }
+            // Notify callback
+            if (onRetry) {
+                onRetry(attempt, error, delayMs);
+            }
+            // Wait before retry
+            await sleep(delayMs);
+        }
+    }
+    return {
+        error: lastError,
+        attempts,
+        totalTimeMs: Date.now() - startTime,
+        success: false
+    };
+}
+exports.withRetryResult = withRetryResult;
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/dist/utils/validation.d.ts

@@ -1,6 +1,30 @@
 /**
  * Input validation utilities
  */
+/** Ethereum address validation pattern */
+export declare const ADDRESS_PATTERN: RegExp;
+/** Transaction ID (bytes32) validation pattern */
+export declare const TX_ID_PATTERN: RegExp;
+/** Hash (bytes32) validation pattern */
+export declare const HASH_PATTERN: RegExp;
+/** Signature (65 bytes = 130 hex chars) validation pattern */
+export declare const SIGNATURE_PATTERN: RegExp;
+/** CID validation pattern (CIDv0 or CIDv1) */
+export declare const CID_PATTERN: RegExp;
+/** Arweave TX ID pattern (43 characters, base64url) */
+export declare const ARWEAVE_TX_ID_PATTERN: RegExp;
+/** Semver pattern for version validation */
+export declare const SEMVER_PATTERN: RegExp;
+/**
+ * Allowed IPFS gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export declare const ALLOWED_IPFS_GATEWAYS: readonly ["ipfs.filebase.io", "gateway.pinata.cloud", "cloudflare-ipfs.com", "ipfs.io", "dweb.link", "w3s.link", "nftstorage.link"];
+/**
+ * Allowed Arweave gateway domains
+ * Only whitelisted gateways are allowed for downloads
+ */
+export declare const ALLOWED_ARWEAVE_GATEWAYS: readonly ["arweave.net", "gateway.irys.xyz", "arweave.dev"];
 /**
  * Validate Ethereum address
  */
@@ -43,4 +67,80 @@ export declare function validateTxId(txId: string, fieldName?: string): void;
  * @throws {ValidationError} If endpoint is invalid or points to private IP
  */
 export declare function validateEndpointURL(endpoint: string, fieldName?: string): Promise<void>;
+/**
+ * Validate IPFS CID format
+ *
+ * @param cid - IPFS CID to validate
+ * @param fieldName - Field name for error messages
+ * @throws {InvalidCIDError} If CID is invalid
+ */
+export declare function validateCID(cid: string, fieldName?: string): void;
+/**
+ * Validate Arweave transaction ID format
+ *
+ * @param txId - Arweave TX ID to validate
+ * @param fieldName - Field name for error messages
+ * @throws {InvalidArweaveTxIdError} If TX ID is invalid
+ */
+export declare function validateArweaveTxId(txId: string, fieldName?: string): void;
+/**
+ * Validate gateway URL against whitelist (SSRF Protection - P0-1)
+ *
+ * SECURITY FIX: Only allow downloads from whitelisted gateway domains.
+ * This prevents SSRF attacks where attacker controls the gateway URL.
+ *
+ * @param url - Full gateway URL to validate
+ * @param allowedGateways - List of allowed gateway domains
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If gateway is not whitelisted
+ */
+export declare function validateGatewayURL(url: string, allowedGateways: readonly string[], fieldName?: string): void;
+/**
+ * Validate semver version string
+ *
+ * @param version - Version string to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If version is invalid
+ */
+export declare function validateSemver(version: string, fieldName?: string): void;
+/**
+ * Validate hash (bytes32) format
+ *
+ * @param hash - Hash to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If hash is invalid
+ */
+export declare function validateHash(hash: string, fieldName?: string): void;
+/**
+ * Validate signature format (65 bytes)
+ *
+ * @param signature - Signature to validate
+ * @param fieldName - Field name for error messages
+ * @throws {ValidationError} If signature is invalid
+ */
+export declare function validateSignature(signature: string, fieldName?: string): void;
+/**
+ * Sanitize error messages to remove sensitive data
+ *
+ * SECURITY FIX (P0-2): Removes credentials, private keys, and other
+ * sensitive data from error messages before logging/returning.
+ *
+ * @param error - Error to sanitize
+ * @returns Sanitized error message
+ */
+export declare function sanitizeErrorMessage(error: unknown): string;
+/**
+ * Create a safe error object for external consumption
+ *
+ * SECURITY FIX (P0-2): Returns error without stack trace or sensitive details
+ *
+ * @param error - Original error
+ * @param operation - What operation failed
+ * @returns Safe error object
+ */
+export declare function createSafeError(error: unknown, operation: string): {
+    message: string;
+    code: string;
+    operation: string;
+};
 //# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,GAAE,MAAiB,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,IAAI,CASvF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAwB,GAClC,IAAI,CAaN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAI3E;AAwDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFzG"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AASA;;GAEG;AAMH,0CAA0C;AAC1C,eAAO,MAAM,eAAe,QAAwB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,aAAa,QAAwB,CAAC;AAEnD,wCAAwC;AACxC,eAAO,MAAM,YAAY,QAAwB,CAAC;AAElD,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AAExD,8CAA8C;AAC9C,eAAO,MAAM,WAAW,QAAkD,CAAC;AAE3E,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,QAAwB,CAAC;AAE3D,4CAA4C;AAC5C,eAAO,MAAM,cAAc,QAAoB,CAAC;AAMhD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qIAQxB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,wBAAwB,6DAI3B,CAAC;AAMX;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQpF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,GAAE,MAAiB,GAAG,IAAI,CASlF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,IAAI,CASvF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,MAAwB,GAClC,IAAI,CAaN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAI3E;AA8DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFzG;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,IAAI,CAQxE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAWlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,SAAS,GAAE,MAAqB,GAC/B,IAAI,CA0CN;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkB,GAAG,IAAI,CAQnF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAe,GAAG,IAAI,CAQ3E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,GAAE,MAAoB,GAAG,IAAI,CAW1F;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsC3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAStD"}