@dotdo/do 0.1.0

package/dist/do/domains/ssl.d.ts

@@ -0,0 +1,217 @@
+/**
+ * SSL Certificate Management
+ *
+ * Handles SSL certificate status checking and provisioning triggers.
+ * Cloudflare manages certificates automatically for proxied records;
+ * this module provides visibility and control for edge cases.
+ *
+ * @module domains/ssl
+ */
+import type { PlatformTLD } from '../../types/domains';
+/**
+ * SSL certificate status
+ */
+export type SSLStatus = 'active' | 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'validation_timed_out' | 'issuance_timed_out' | 'deployment_timed_out' | 'deleted' | 'inactive';
+/**
+ * SSL certificate type
+ */
+export type SSLCertificateType = 'universal' | 'advanced' | 'custom' | 'dedicated';
+/**
+ * SSL validation method
+ */
+export type SSLValidationMethod = 'http' | 'txt' | 'email';
+/**
+ * SSL certificate information
+ */
+export interface SSLCertificate {
+    /** Certificate ID */
+    id: string;
+    /** Certificate type */
+    type: SSLCertificateType;
+    /** Current status */
+    status: SSLStatus;
+    /** Hostnames covered by this certificate */
+    hosts: string[];
+    /** Certificate authority */
+    issuer: string;
+    /** Expiration timestamp */
+    expiresAt: number;
+    /** When the certificate was issued */
+    issuedAt?: number;
+    /** Validation method used */
+    validationMethod?: SSLValidationMethod;
+}
+/**
+ * Options for checking certificate status
+ */
+export interface CheckCertificateOptions {
+    /** The full hostname (e.g., 'acme.saas.group') */
+    hostname: string;
+    /** The platform TLD (extracted from hostname if not provided) */
+    tld?: PlatformTLD;
+}
+/**
+ * Options for waiting for certificate
+ */
+export interface WaitForCertificateOptions {
+    /** Maximum time to wait in milliseconds */
+    timeout?: number;
+    /** Polling interval in milliseconds */
+    pollInterval?: number;
+}
+/**
+ * Error from SSL operations
+ */
+export declare class SSLError extends Error {
+    code: 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION_FAILED' | 'API_ERROR';
+    details?: Record<string, unknown> | undefined;
+    constructor(code: 'NOT_FOUND' | 'TIMEOUT' | 'VALIDATION_FAILED' | 'API_ERROR', message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Get SSL certificate status for a hostname
+ *
+ * @param options - Check options
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Certificate information or null if not found
+ *
+ * @example
+ * ```typescript
+ * const cert = await getCertificateStatus({
+ *   hostname: 'acme.saas.group'
+ * }, env)
+ *
+ * if (cert?.status === 'active') {
+ *   console.log('SSL active, expires:', new Date(cert.expiresAt))
+ * }
+ * ```
+ */
+export declare function getCertificateStatus(options: CheckCertificateOptions, env: {
+    CF_API_TOKEN: string;
+}): Promise<SSLCertificate | null>;
+/**
+ * Wait for a certificate to become active
+ *
+ * Useful after creating DNS records or triggering certificate provisioning.
+ *
+ * @param hostname - The hostname to check
+ * @param options - Wait options
+ * @param env - Environment with CF_API_TOKEN
+ * @returns The active certificate
+ * @throws SSLError if timeout or validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const cert = await waitForCertificate('acme.saas.group', {
+ *     timeout: 60000,
+ *     pollInterval: 5000
+ *   }, env)
+ *   console.log('Certificate active!')
+ * } catch (error) {
+ *   if (error instanceof SSLError && error.code === 'TIMEOUT') {
+ *     console.log('Certificate not ready yet')
+ *   }
+ * }
+ * ```
+ */
+export declare function waitForCertificate(hostname: string, options: WaitForCertificateOptions, env: {
+    CF_API_TOKEN: string;
+}): Promise<SSLCertificate>;
+/**
+ * Check if a hostname is covered by an active certificate
+ *
+ * @param hostname - The hostname to check
+ * @param env - Environment with CF_API_TOKEN
+ * @returns True if covered by an active certificate
+ *
+ * @example
+ * ```typescript
+ * const covered = await isCertificateActive('acme.saas.group', env)
+ * ```
+ */
+export declare function isCertificateActive(hostname: string, env: {
+    CF_API_TOKEN: string;
+}): Promise<boolean>;
+/**
+ * List all SSL certificates for a zone
+ *
+ * @param zone - The platform TLD
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Array of certificates
+ *
+ * @example
+ * ```typescript
+ * const certs = await listCertificates('saas.group', env)
+ * ```
+ */
+export declare function listCertificates(zone: PlatformTLD, env: {
+    CF_API_TOKEN: string;
+}): Promise<SSLCertificate[]>;
+/**
+ * Check if a hostname requires Advanced Certificate Manager
+ *
+ * Deep subdomains (a.b.saas.group) are not covered by Universal SSL
+ * and require Advanced Certificate Manager.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if Advanced Certificate Manager is required
+ *
+ * @example
+ * ```typescript
+ * requiresAdvancedCertificate('acme.saas.group') // false
+ * requiresAdvancedCertificate('api.acme.saas.group') // true
+ * ```
+ */
+export declare function requiresAdvancedCertificate(hostname: string): boolean;
+/**
+ * Get certificates expiring within a time window
+ *
+ * @param zone - The platform TLD
+ * @param withinMs - Time window in milliseconds
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Certificates expiring within the window
+ *
+ * @example
+ * ```typescript
+ * // Get certificates expiring in the next 30 days
+ * const expiring = await getExpiringCertificates('saas.group', 30 * 24 * 60 * 60 * 1000, env)
+ * ```
+ */
+export declare function getExpiringCertificates(zone: PlatformTLD, withinMs: number, env: {
+    CF_API_TOKEN: string;
+}): Promise<SSLCertificate[]>;
+/**
+ * Order an Advanced Certificate for deep subdomains
+ *
+ * @param hostnames - Hostnames to cover
+ * @param zone - The platform TLD
+ * @param env - Environment with CF_API_TOKEN
+ * @returns The ordered certificate (pending)
+ *
+ * @example
+ * ```typescript
+ * const cert = await orderAdvancedCertificate(
+ *   ['api.acme.saas.group', 'admin.acme.saas.group'],
+ *   'saas.group',
+ *   env
+ * )
+ * ```
+ */
+export declare function orderAdvancedCertificate(hostnames: string[], zone: PlatformTLD, env: {
+    CF_API_TOKEN: string;
+}): Promise<SSLCertificate>;
+/**
+ * Extract TLD from a hostname
+ *
+ * @param hostname - Full hostname (e.g., 'acme.saas.group')
+ * @returns The TLD portion (e.g., 'saas.group')
+ */
+export declare function extractTLD(hostname: string): string;
+/**
+ * Extract subdomain from a hostname
+ *
+ * @param hostname - Full hostname (e.g., 'acme.saas.group')
+ * @returns The subdomain portion (e.g., 'acme')
+ */
+export declare function extractSubdomain(hostname: string): string;
+//# sourceMappingURL=ssl.d.ts.map

package/dist/do/domains/ssl.d.ts.map

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

package/dist/do/domains/ssl.js

@@ -0,0 +1,231 @@
+/**
+ * SSL Certificate Management
+ *
+ * Handles SSL certificate status checking and provisioning triggers.
+ * Cloudflare manages certificates automatically for proxied records;
+ * this module provides visibility and control for edge cases.
+ *
+ * @module domains/ssl
+ */
+/**
+ * Error from SSL operations
+ */
+export class SSLError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'SSLError';
+    }
+}
+// =============================================================================
+// Cloudflare API Constants
+// =============================================================================
+const CF_API_BASE = 'https://api.cloudflare.com/client/v4';
+/** Default timeout for waiting (60 seconds) */
+const DEFAULT_TIMEOUT = 60_000;
+/** Default poll interval (5 seconds) */
+const DEFAULT_POLL_INTERVAL = 5_000;
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get SSL certificate status for a hostname
+ *
+ * @param options - Check options
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Certificate information or null if not found
+ *
+ * @example
+ * ```typescript
+ * const cert = await getCertificateStatus({
+ *   hostname: 'acme.saas.group'
+ * }, env)
+ *
+ * if (cert?.status === 'active') {
+ *   console.log('SSL active, expires:', new Date(cert.expiresAt))
+ * }
+ * ```
+ */
+export async function getCertificateStatus(options, env) {
+    // TODO: Implement Cloudflare API call
+    // GET /zones/{zone_id}/ssl/certificate_packs
+    throw new Error('Not implemented');
+}
+/**
+ * Wait for a certificate to become active
+ *
+ * Useful after creating DNS records or triggering certificate provisioning.
+ *
+ * @param hostname - The hostname to check
+ * @param options - Wait options
+ * @param env - Environment with CF_API_TOKEN
+ * @returns The active certificate
+ * @throws SSLError if timeout or validation fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const cert = await waitForCertificate('acme.saas.group', {
+ *     timeout: 60000,
+ *     pollInterval: 5000
+ *   }, env)
+ *   console.log('Certificate active!')
+ * } catch (error) {
+ *   if (error instanceof SSLError && error.code === 'TIMEOUT') {
+ *     console.log('Certificate not ready yet')
+ *   }
+ * }
+ * ```
+ */
+export async function waitForCertificate(hostname, options, env) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const pollInterval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        const cert = await getCertificateStatus({ hostname }, env);
+        if (cert?.status === 'active') {
+            return cert;
+        }
+        if (cert?.status === 'validation_timed_out' || cert?.status === 'issuance_timed_out') {
+            throw new SSLError('VALIDATION_FAILED', `Certificate validation failed: ${cert.status}`, { hostname, status: cert.status });
+        }
+        await sleep(pollInterval);
+    }
+    throw new SSLError('TIMEOUT', `Timed out waiting for certificate: ${hostname}`, { hostname, timeout });
+}
+/**
+ * Check if a hostname is covered by an active certificate
+ *
+ * @param hostname - The hostname to check
+ * @param env - Environment with CF_API_TOKEN
+ * @returns True if covered by an active certificate
+ *
+ * @example
+ * ```typescript
+ * const covered = await isCertificateActive('acme.saas.group', env)
+ * ```
+ */
+export async function isCertificateActive(hostname, env) {
+    const cert = await getCertificateStatus({ hostname }, env);
+    return cert?.status === 'active';
+}
+/**
+ * List all SSL certificates for a zone
+ *
+ * @param zone - The platform TLD
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Array of certificates
+ *
+ * @example
+ * ```typescript
+ * const certs = await listCertificates('saas.group', env)
+ * ```
+ */
+export async function listCertificates(zone, env) {
+    // TODO: Implement Cloudflare API call
+    // GET /zones/{zone_id}/ssl/certificate_packs
+    throw new Error('Not implemented');
+}
+/**
+ * Check if a hostname requires Advanced Certificate Manager
+ *
+ * Deep subdomains (a.b.saas.group) are not covered by Universal SSL
+ * and require Advanced Certificate Manager.
+ *
+ * @param hostname - The hostname to check
+ * @returns True if Advanced Certificate Manager is required
+ *
+ * @example
+ * ```typescript
+ * requiresAdvancedCertificate('acme.saas.group') // false
+ * requiresAdvancedCertificate('api.acme.saas.group') // true
+ * ```
+ */
+export function requiresAdvancedCertificate(hostname) {
+    // Count subdomain depth
+    // acme.saas.group = depth 1 (covered by *.saas.group)
+    // api.acme.saas.group = depth 2 (NOT covered)
+    const parts = hostname.split('.');
+    // Assuming TLD is last 2 parts (e.g., saas.group)
+    const subdomainDepth = parts.length - 2;
+    return subdomainDepth > 1;
+}
+/**
+ * Get certificates expiring within a time window
+ *
+ * @param zone - The platform TLD
+ * @param withinMs - Time window in milliseconds
+ * @param env - Environment with CF_API_TOKEN
+ * @returns Certificates expiring within the window
+ *
+ * @example
+ * ```typescript
+ * // Get certificates expiring in the next 30 days
+ * const expiring = await getExpiringCertificates('saas.group', 30 * 24 * 60 * 60 * 1000, env)
+ * ```
+ */
+export async function getExpiringCertificates(zone, withinMs, env) {
+    const certs = await listCertificates(zone, env);
+    const expiryThreshold = Date.now() + withinMs;
+    return certs.filter((cert) => cert.expiresAt < expiryThreshold);
+}
+// =============================================================================
+// Advanced Certificate Management
+// =============================================================================
+/**
+ * Order an Advanced Certificate for deep subdomains
+ *
+ * @param hostnames - Hostnames to cover
+ * @param zone - The platform TLD
+ * @param env - Environment with CF_API_TOKEN
+ * @returns The ordered certificate (pending)
+ *
+ * @example
+ * ```typescript
+ * const cert = await orderAdvancedCertificate(
+ *   ['api.acme.saas.group', 'admin.acme.saas.group'],
+ *   'saas.group',
+ *   env
+ * )
+ * ```
+ */
+export async function orderAdvancedCertificate(hostnames, zone, env) {
+    // TODO: Implement Cloudflare API call
+    // POST /zones/{zone_id}/ssl/certificate_packs/order
+    throw new Error('Not implemented');
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Extract TLD from a hostname
+ *
+ * @param hostname - Full hostname (e.g., 'acme.saas.group')
+ * @returns The TLD portion (e.g., 'saas.group')
+ */
+export function extractTLD(hostname) {
+    const parts = hostname.split('.');
+    // Assumes TLD is last 2 parts
+    return parts.slice(-2).join('.');
+}
+/**
+ * Extract subdomain from a hostname
+ *
+ * @param hostname - Full hostname (e.g., 'acme.saas.group')
+ * @returns The subdomain portion (e.g., 'acme')
+ */
+export function extractSubdomain(hostname) {
+    const parts = hostname.split('.');
+    // Everything except last 2 parts
+    return parts.slice(0, -2).join('.');
+}
+//# sourceMappingURL=ssl.js.map

package/dist/do/domains/ssl.js.map

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

package/dist/do/domains/subdomains.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Subdomain Registration
+ *
+ * CRUD operations for subdomain registrations on platform TLDs.
+ * Interacts with the Builder.Domains DO for centralized registration management.
+ *
+ * @module domains/subdomains
+ */
+import type { PlatformTLD, SubdomainStatus, SubdomainRegistration, ClaimSubdomainRequest, ClaimSubdomainResult, DomainsManager } from '../../types/domains';
+/**
+ * Options for listing subdomains
+ */
+export interface ListSubdomainsOptions {
+    /** Filter by TLD */
+    tld?: PlatformTLD;
+    /** Filter by status */
+    status?: SubdomainStatus;
+    /** Maximum results to return */
+    limit?: number;
+    /** Pagination cursor */
+    cursor?: string;
+}
+/**
+ * Result of listing subdomains
+ */
+export interface ListSubdomainsResult {
+    /** The subdomain registrations */
+    items: SubdomainRegistration[];
+    /** Cursor for next page (if more results exist) */
+    cursor?: string;
+    /** Whether more results are available */
+    hasMore: boolean;
+}
+/**
+ * Options for searching subdomains
+ */
+export interface SearchSubdomainsOptions {
+    /** Search query (matches subdomain prefix) */
+    query: string;
+    /** Filter by TLD */
+    tld?: PlatformTLD;
+    /** Maximum results */
+    limit?: number;
+}
+/**
+ * Client for subdomain operations
+ *
+ * Wraps the Builder.Domains DO stub for subdomain management.
+ */
+export declare class SubdomainClient implements DomainsManager {
+    private domainsStub;
+    /**
+     * Create a new SubdomainClient
+     *
+     * @param domainsStub - Durable Object stub for Builder.Domains
+     */
+    constructor(domainsStub: DurableObjectStub);
+    /**
+     * Check if a subdomain is available
+     *
+     * @param subdomain - The subdomain to check (e.g., 'acme')
+     * @param tld - The platform TLD (e.g., 'saas.group')
+     * @returns The subdomain status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.check('acme', 'saas.group')
+     * if (status === 'available') {
+     *   // Can be claimed
+     * }
+     * ```
+     */
+    check(subdomain: string, tld: PlatformTLD): Promise<SubdomainStatus>;
+    /**
+     * Claim a subdomain
+     *
+     * @param request - The claim request
+     * @returns The claim result
+     *
+     * @example
+     * ```typescript
+     * const result = await client.claim({
+     *   subdomain: 'acme',
+     *   tld: 'saas.group',
+     *   ownerRef: 'do://Startup/acme'
+     * })
+     *
+     * if (result.success) {
+     *   console.log('Claimed:', result.$id) // https://acme.saas.group
+     * }
+     * ```
+     */
+    claim(request: ClaimSubdomainRequest): Promise<ClaimSubdomainResult>;
+    /**
+     * Release a subdomain
+     *
+     * @param subdomain - The subdomain to release
+     * @param tld - The platform TLD
+     * @param ownerRef - The owner's DO $id (must match registration)
+     * @returns True if released successfully
+     *
+     * @example
+     * ```typescript
+     * const released = await client.release('acme', 'saas.group', 'do://Startup/acme')
+     * ```
+     */
+    release(subdomain: string, tld: PlatformTLD, ownerRef: string): Promise<boolean>;
+    /**
+     * List subdomains owned by a specific DO
+     *
+     * @param ownerRef - The owner's DO $id
+     * @returns Array of subdomain registrations
+     *
+     * @example
+     * ```typescript
+     * const subdomains = await client.listByOwner('do://Startup/acme')
+     * // [{ $id: 'https://acme.saas.group', subdomain: 'acme', ... }]
+     * ```
+     */
+    listByOwner(ownerRef: string): Promise<SubdomainRegistration[]>;
+    /**
+     * Get a specific subdomain registration
+     *
+     * @param subdomain - The subdomain
+     * @param tld - The platform TLD
+     * @returns The registration or null if not found
+     *
+     * @example
+     * ```typescript
+     * const reg = await client.get('acme', 'saas.group')
+     * if (reg) {
+     *   console.log('Owner:', reg.ownerRef)
+     * }
+     * ```
+     */
+    get(subdomain: string, tld: PlatformTLD): Promise<SubdomainRegistration | null>;
+    /**
+     * Search subdomains by prefix
+     *
+     * @param query - Search query (prefix match)
+     * @param tld - Optional TLD filter
+     * @returns Matching registrations
+     *
+     * @example
+     * ```typescript
+     * const results = await client.search('acm', 'saas.group')
+     * // [{ subdomain: 'acme', ... }, { subdomain: 'acme-dev', ... }]
+     * ```
+     */
+    search(query: string, tld?: PlatformTLD): Promise<SubdomainRegistration[]>;
+}
+/**
+ * Create a subdomain client from a Durable Object namespace
+ *
+ * @param namespace - The Builder.Domains DO namespace
+ * @returns A SubdomainClient instance
+ *
+ * @example
+ * ```typescript
+ * const client = createSubdomainClient(env.BUILDER_DOMAINS)
+ * ```
+ */
+export declare function createSubdomainClient(namespace: DurableObjectNamespace): SubdomainClient;
+/**
+ * Build the full domain URL from subdomain and TLD
+ *
+ * @param subdomain - The subdomain (e.g., 'acme')
+ * @param tld - The platform TLD (e.g., 'saas.group')
+ * @returns The full URL (e.g., 'https://acme.saas.group')
+ *
+ * @example
+ * ```typescript
+ * buildDomainUrl('acme', 'saas.group')
+ * // 'https://acme.saas.group'
+ * ```
+ */
+export declare function buildDomainUrl(subdomain: string, tld: PlatformTLD): string;
+/**
+ * Parse a domain URL into subdomain and TLD
+ *
+ * @param url - The domain URL (e.g., 'https://acme.saas.group')
+ * @returns Object with subdomain and tld, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * parseDomainUrl('https://acme.saas.group')
+ * // { subdomain: 'acme', tld: 'saas.group' }
+ * ```
+ */
+export declare function parseDomainUrl(url: string): {
+    subdomain: string;
+    tld: PlatformTLD;
+} | null;
+/**
+ * Check if a URL is a platform domain
+ *
+ * @param url - The URL to check
+ * @returns True if the URL is on a platform TLD
+ *
+ * @example
+ * ```typescript
+ * isPlatformDomain('https://acme.saas.group') // true
+ * isPlatformDomain('https://example.com') // false
+ * ```
+ */
+export declare function isPlatformDomain(url: string): boolean;
+//# sourceMappingURL=subdomains.d.ts.map

package/dist/do/domains/subdomains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subdomains.d.ts","sourceRoot":"","sources":["../../../do/domains/subdomains.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACf,MAAM,qBAAqB,CAAA;AAQ5B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,uBAAuB;IACvB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kCAAkC;IAClC,KAAK,EAAE,qBAAqB,EAAE,CAAA;IAC9B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,GAAG,CAAC,EAAE,WAAW,CAAA;IACjB,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,cAAc;IAMxC,OAAO,CAAC,WAAW;IAL/B;;;;OAIG;gBACiB,WAAW,EAAE,iBAAiB;IAElD;;;;;;;;;;;;;;OAcG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAK1E;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwB1E;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtF;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAKrE;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAKrF;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;CAIjF;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,sBAAsB,GAAG,eAAe,CAIxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,WAAW,CAAA;CAAE,GAAG,IAAI,CAG1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD"}