@claw-network/node 0.2.1 → 0.3.0

package/dist/services/message-store.js

@@ -0,0 +1,221 @@
+/**
+ * MessageStore — SQLite-backed inbox/outbox for P2P direct messaging.
+ *
+ * Inbox: messages received from other peers, waiting to be consumed by the local app.
+ * Outbox: messages pending delivery to offline peers, retried when the peer connects.
+ */
+import Database from 'better-sqlite3';
+import crypto from 'node:crypto';
+// ── Schema ───────────────────────────────────────────────────────
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS inbox (
+  id            TEXT PRIMARY KEY,
+  source_did    TEXT NOT NULL,
+  target_did    TEXT NOT NULL,
+  topic         TEXT NOT NULL,
+  payload       TEXT NOT NULL,
+  ttl_sec       INTEGER NOT NULL DEFAULT 86400,
+  sent_at_ms    INTEGER NOT NULL,
+  received_at_ms INTEGER NOT NULL,
+  consumed      INTEGER NOT NULL DEFAULT 0,
+  priority      INTEGER NOT NULL DEFAULT 0,
+  seq           INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_inbox_topic ON inbox(topic, consumed);
+CREATE INDEX IF NOT EXISTS idx_inbox_received ON inbox(received_at_ms);
+CREATE INDEX IF NOT EXISTS idx_inbox_source ON inbox(source_did, consumed);
+CREATE INDEX IF NOT EXISTS idx_inbox_unconsumed ON inbox(consumed, received_at_ms) WHERE consumed = 0;
+
+CREATE TABLE IF NOT EXISTS outbox (
+  id            TEXT PRIMARY KEY,
+  target_did    TEXT NOT NULL,
+  topic         TEXT NOT NULL,
+  payload       TEXT NOT NULL,
+  ttl_sec       INTEGER NOT NULL DEFAULT 86400,
+  sent_at_ms    INTEGER NOT NULL,
+  attempts      INTEGER NOT NULL DEFAULT 0,
+  last_attempt  INTEGER,
+  priority      INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_outbox_target ON outbox(target_did);
+CREATE INDEX IF NOT EXISTS idx_outbox_retry ON outbox(attempts, last_attempt);
+
+-- Deduplication table: stores idempotency keys with TTL for duplicate detection
+CREATE TABLE IF NOT EXISTS dedup (
+  idempotency_key TEXT PRIMARY KEY,
+  message_id      TEXT NOT NULL,
+  created_at_ms   INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_dedup_created ON dedup(created_at_ms);
+
+-- Sequence counter for ordered inbox replay
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+INSERT OR IGNORE INTO meta (key, value) VALUES ('inbox_seq', '0');
+`;
+/** Deduplication window: 24 hours */
+const DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+// ── Store ────────────────────────────────────────────────────────
+export class MessageStore {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.exec(SCHEMA_SQL);
+    }
+    // ── Inbox ──────────────────────────────────────────────────────
+    /**
+     * Store an inbound message in the inbox. Returns the messageId.
+     * If `idempotencyKey` is provided, deduplicates — returns existing messageId on duplicate.
+     */
+    addToInbox(msg) {
+        // Deduplication check
+        if (msg.idempotencyKey) {
+            const existing = this.db.prepare('SELECT message_id FROM dedup WHERE idempotency_key = ?').get(msg.idempotencyKey);
+            if (existing)
+                return existing.message_id;
+        }
+        const id = `msg_${crypto.randomBytes(12).toString('hex')}`;
+        const now = Date.now();
+        const seq = this.nextSeq();
+        this.db.prepare(`
+      INSERT INTO inbox (id, source_did, target_did, topic, payload, ttl_sec, sent_at_ms, received_at_ms, priority, seq)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, msg.sourceDid, msg.targetDid, msg.topic, msg.payload, msg.ttlSec ?? 86400, msg.sentAtMs ?? now, now, msg.priority ?? 0, seq);
+        // Record dedup key
+        if (msg.idempotencyKey) {
+            this.db.prepare('INSERT OR IGNORE INTO dedup (idempotency_key, message_id, created_at_ms) VALUES (?, ?, ?)').run(msg.idempotencyKey, id, now);
+        }
+        return id;
+    }
+    /** Increment and return the next inbox sequence number (monotonic). */
+    nextSeq() {
+        this.db.prepare("UPDATE meta SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT) WHERE key = 'inbox_seq'").run();
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = 'inbox_seq'").get();
+        return parseInt(row.value, 10);
+    }
+    /** Get the current (latest) inbox sequence number. */
+    currentSeq() {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = 'inbox_seq'").get();
+        return row ? parseInt(row.value, 10) : 0;
+    }
+    /** Fetch unconsumed inbox messages, ordered by priority then time. */
+    getInbox(opts = {}) {
+        const limit = Math.min(opts.limit ?? 100, 500);
+        let sql = 'SELECT id, source_did, topic, payload, received_at_ms, priority, seq FROM inbox WHERE consumed = 0';
+        const params = [];
+        if (opts.topic) {
+            sql += ' AND topic = ?';
+            params.push(opts.topic);
+        }
+        if (opts.sinceMs) {
+            sql += ' AND received_at_ms > ?';
+            params.push(opts.sinceMs);
+        }
+        if (opts.sinceSeq !== undefined) {
+            sql += ' AND seq > ?';
+            params.push(opts.sinceSeq);
+        }
+        // Higher priority first, then by received time
+        sql += ' ORDER BY priority DESC, received_at_ms ASC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => ({
+            messageId: r.id,
+            sourceDid: r.source_did,
+            topic: r.topic,
+            payload: r.payload,
+            receivedAtMs: r.received_at_ms,
+            priority: r.priority,
+            seq: r.seq,
+        }));
+    }
+    /** Mark a message as consumed (acknowledged). */
+    consumeMessage(messageId) {
+        const result = this.db.prepare('UPDATE inbox SET consumed = 1 WHERE id = ? AND consumed = 0').run(messageId);
+        return result.changes > 0;
+    }
+    /** Delete consumed and expired messages in batches to avoid locking. Also cleans dedup table. */
+    cleanupInbox() {
+        const now = Date.now();
+        let total = 0;
+        // Delete in batches of 500 to avoid long table locks
+        const stmt = this.db.prepare('DELETE FROM inbox WHERE id IN (SELECT id FROM inbox WHERE consumed = 1 OR (sent_at_ms + ttl_sec * 1000) <= ? LIMIT 500)');
+        let changes;
+        do {
+            changes = stmt.run(now).changes;
+            total += changes;
+        } while (changes > 0);
+        // Clean expired dedup entries
+        const dedupCutoff = now - DEDUP_TTL_MS;
+        this.db.prepare('DELETE FROM dedup WHERE created_at_ms < ?').run(dedupCutoff);
+        return total;
+    }
+    // ── Outbox ─────────────────────────────────────────────────────
+    /** Queue a message for later delivery to an offline peer. */
+    addToOutbox(msg) {
+        const id = `msg_${crypto.randomBytes(12).toString('hex')}`;
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO outbox (id, target_did, topic, payload, ttl_sec, sent_at_ms, priority)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(id, msg.targetDid, msg.topic, msg.payload, msg.ttlSec ?? 86400, now, msg.priority ?? 0);
+        return id;
+    }
+    /** Get pending outbox messages for a specific target DID, ordered by priority then time. */
+    getOutboxForTarget(targetDid, limit = 100) {
+        const now = Date.now();
+        const rows = this.db.prepare(`
+      SELECT id, target_did, topic, payload, ttl_sec, sent_at_ms, attempts, last_attempt
+      FROM outbox
+      WHERE target_did = ? AND (sent_at_ms + ttl_sec * 1000) > ?
+      ORDER BY priority DESC, sent_at_ms ASC LIMIT ?
+    `).all(targetDid, now, limit);
+        return rows.map((r) => ({
+            id: r.id,
+            targetDid: r.target_did,
+            topic: r.topic,
+            payload: r.payload,
+            ttlSec: r.ttl_sec,
+            sentAtMs: r.sent_at_ms,
+            attempts: r.attempts,
+            lastAttempt: r.last_attempt ?? 0,
+        }));
+    }
+    /** Increment attempt count for an outbox message. */
+    recordAttempt(messageId) {
+        this.db.prepare('UPDATE outbox SET attempts = attempts + 1, last_attempt = ? WHERE id = ?').run(Date.now(), messageId);
+    }
+    /** Remove a message from the outbox (successfully delivered). */
+    removeFromOutbox(messageId) {
+        const result = this.db.prepare('DELETE FROM outbox WHERE id = ?').run(messageId);
+        return result.changes > 0;
+    }
+    /** Clean up expired outbox entries in batches. */
+    cleanupOutbox() {
+        const now = Date.now();
+        let total = 0;
+        const stmt = this.db.prepare('DELETE FROM outbox WHERE id IN (SELECT id FROM outbox WHERE (sent_at_ms + ttl_sec * 1000) <= ? LIMIT 500)');
+        let changes;
+        do {
+            changes = stmt.run(now).changes;
+            total += changes;
+        } while (changes > 0);
+        return total;
+    }
+    /** Total count of inbox messages (for rate limiting / stats). */
+    inboxCount(targetDid) {
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM inbox WHERE target_did = ? AND consumed = 0').get(targetDid);
+        return row?.cnt ?? 0;
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=message-store.js.map

package/dist/services/message-store.js.map

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

package/dist/services/messaging-service.d.ts

@@ -0,0 +1,174 @@
+/**
+ * MessagingService — orchestrates P2P direct messaging.
+ *
+ * Responsibilities:
+ * - Send messages to target DIDs via libp2p stream protocol
+ * - Receive inbound messages and store in inbox
+ * - Queue messages for offline peers in outbox, deliver on reconnect
+ * - Maintain DID → PeerId mapping via announce protocol
+ * - Periodic TTL cleanup of expired messages
+ */
+import type { P2PNode } from '@claw-network/core';
+import { MessageStore } from './message-store.js';
+/** Priority levels — higher number = higher priority. */
+export declare enum MessagePriority {
+    LOW = 0,
+    NORMAL = 1,
+    HIGH = 2,
+    URGENT = 3
+}
+export interface SendResult {
+    messageId: string;
+    delivered: boolean;
+    compressed?: boolean;
+    encrypted?: boolean;
+}
+export interface MulticastResult {
+    results: Array<SendResult & {
+        targetDid: string;
+    }>;
+}
+export interface InboxQueryOptions {
+    topic?: string;
+    sinceMs?: number;
+    sinceSeq?: number;
+    limit?: number;
+}
+export interface InboxMessage {
+    messageId: string;
+    sourceDid: string;
+    topic: string;
+    payload: string;
+    receivedAtMs: number;
+    priority: number;
+    seq: number;
+}
+export interface SendOptions {
+    ttlSec?: number;
+    priority?: MessagePriority;
+    /** If true, compress payload > 1 KB with gzip before sending. */
+    compress?: boolean;
+    /** Recipient's X25519 public key hex for E2E encryption. */
+    encryptForKeyHex?: string;
+    /** Idempotency key for deduplication. */
+    idempotencyKey?: string;
+}
+/** Callback for WebSocket subscribers — called when a new message arrives in the inbox. */
+export type InboxSubscriber = (message: InboxMessage) => void;
+export declare class MessagingService {
+    private readonly log;
+    private readonly store;
+    private readonly p2p;
+    private readonly localDid;
+    private cleanupTimer?;
+    /**
+     * DID → PeerId mapping. Populated via the did-announce protocol when
+     * peers connect. This is a best-effort cache; entries are never evicted
+     * but may become stale when peers go offline.
+     */
+    private readonly didToPeerId;
+    private readonly peerIdToDid;
+    /** WebSocket subscribers that receive real-time inbox pushes. */
+    private readonly subscribers;
+    /** Sliding-window rate limiter: DID → array of timestamps (ms). */
+    private readonly rateBuckets;
+    /** Inbound rate limiter: peerId → array of timestamps. */
+    private readonly inboundRateBuckets;
+    /** Timer for periodic rate-bucket garbage collection. */
+    private rateBucketGcTimer?;
+    constructor(p2p: P2PNode, store: MessageStore, localDid: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Send a message to a target DID.
+     * If the target peer is online and reachable, delivers directly.
+     * Otherwise queues in outbox for later delivery.
+     */
+    send(targetDid: string, topic: string, payload: string, opts?: SendOptions): Promise<SendResult>;
+    /**
+     * Send a message to multiple target DIDs (multicast).
+     * Each target is attempted independently — partial success is possible.
+     */
+    sendMulticast(targetDids: string[], topic: string, payload: string, opts?: SendOptions): Promise<MulticastResult>;
+    /** Query the local inbox. */
+    getInbox(opts?: InboxQueryOptions): InboxMessage[];
+    /** Acknowledge (consume) a message from inbox. */
+    ackMessage(messageId: string): boolean;
+    /** Flush outbox: attempt to deliver all pending messages for a specific DID with exponential backoff. */
+    flushOutboxForDid(targetDid: string): Promise<number>;
+    /**
+     * Called when a peer connects. Announces our DID and flushes any
+     * pending outbox messages for that peer's DID.
+     */
+    onPeerConnected(peerId: string): Promise<void>;
+    /** Return the current DID→PeerId mapping (for debugging/status). */
+    getDidPeerMap(): Record<string, string>;
+    /** Register a subscriber for real-time inbox pushes. */
+    addSubscriber(cb: InboxSubscriber): void;
+    /** Remove a subscriber. */
+    removeSubscriber(cb: InboxSubscriber): void;
+    /** Number of active WS subscribers. */
+    get subscriberCount(): number;
+    /** Notify all subscribers of a new inbox message (non-blocking). */
+    private notifySubscribers;
+    /**
+     * Check rate limit for a DID. Throws if limit exceeded.
+     * Uses a sliding window of timestamps with binary search eviction.
+     */
+    enforceRateLimit(did: string): void;
+    /** Check if a DID is currently rate-limited (without consuming a slot). */
+    isRateLimited(did: string): boolean;
+    /**
+     * Enforce inbound rate limit for a peerId. Throws if limit exceeded.
+     * Prevents P2P peers from spamming without limit.
+     */
+    private enforceInboundRateLimit;
+    /**
+     * Core rate-limit check: evict expired entries via binary search,
+     * push new timestamp, throw if over limit.
+     */
+    private checkRateBucket;
+    /** Binary search: find first index where timestamps[i] >= target. */
+    private bisectLeft;
+    /** Remove empty and stale rate-limit buckets to prevent memory leaks. */
+    private pruneRateBuckets;
+    /**
+     * Encode a payload: optionally compress (gzip) then optionally encrypt (X25519+AES-256-GCM).
+     * Returns the encoded string and flags indicating what was applied.
+     */
+    private encodePayload;
+    /**
+     * Decrypt an E2E-encrypted payload using the local node's X25519 private key.
+     * Returns the decrypted payload string or null if not encrypted / decryption fails.
+     */
+    static decryptPayload(payload: string, recipientPrivateKey: Uint8Array): string | null;
+    /**
+     * Decompress a gzip-compressed payload (base64-encoded gzip → utf-8 string).
+     * Returns the decompressed string, or null if decompression fails.
+     */
+    static decompressPayload(payload: string): string | null;
+    /** Get the current inbox sequence number (for WS replay). */
+    getCurrentSeq(): number;
+    private deliverDirect;
+    private handleInboundMessage;
+    private handleDidAnnounce;
+    /** Announce our DID to a specific peer. */
+    private announceDidToPeer;
+    /** Announce our DID to all currently connected peers. */
+    private announceToAll;
+    /**
+     * Deliver to multiple targets concurrently with bounded concurrency.
+     * Uses Promise.allSettled so one failure doesn't block others.
+     */
+    private deliverMulticast;
+    /** Send a delivery receipt to the sender after receiving a message. */
+    private sendDeliveryReceipt;
+    /** Handle an incoming delivery receipt from a remote peer. */
+    private handleDeliveryReceipt;
+}
+export declare class RateLimitError extends Error {
+    readonly did: string;
+    readonly limit: number;
+    constructor(did: string, limit: number);
+}
+//# sourceMappingURL=messaging-service.d.ts.map

package/dist/services/messaging-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging-service.d.ts","sourceRoot":"","sources":["../../src/services/messaging-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,oBAAoB,CAAC;AAUhE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiDlD,yDAAyD;AACzD,oBAAY,eAAe;IACzB,GAAG,IAAI;IACP,MAAM,IAAI;IACV,IAAI,IAAI;IACR,MAAM,IAAI;CACX;AAID,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC,UAAU,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,2FAA2F;AAC3F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;AAoC9D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,YAAY,CAAC,CAAiB;IAEtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAE1D,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAE3D,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA+B;IAElE,yDAAyD;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAAiB;gBAE/B,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM;IASzD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsCtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B;;;;OAIG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+B1G;;;OAGG;IACG,aAAa,CACjB,UAAU,EAAE,MAAM,EAAE,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,eAAe,CAAC;IAoB3B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,YAAY,EAAE;IAIlD,kDAAkD;IAClD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAItC,yGAAyG;IACnG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4B3D;;;OAGG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpD,oEAAoE;IACpE,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMvC,wDAAwD;IACxD,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI;IAIxC,2BAA2B;IAC3B,gBAAgB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI;IAI3C,uCAAuC;IACvC,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC,2EAA2E;IAC3E,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IASnC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAI/B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuBvB,qEAAqE;IACrE,OAAO,CAAC,UAAU;IAUlB,yEAAyE;IACzE,OAAO,CAAC,gBAAgB;IAiBxB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAoCrB;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI;IAmBtF;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAUxD,6DAA6D;IAC7D,aAAa,IAAI,MAAM;YAMT,aAAa;YA+Cb,oBAAoB;YAqFpB,iBAAiB;IAmC/B,2CAA2C;YAC7B,iBAAiB;IAc/B,yDAAyD;YAC3C,aAAa;IAO3B;;;OAGG;YACW,gBAAgB;IAyC9B,uEAAuE;YACzD,mBAAmB;IA4BjC,8DAA8D;YAChD,qBAAqB;CAuCpC;AAID,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAMvC"}