@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.1

package/dist/esm/websocket/ReconnectingWebSocket.d.ts

@@ -0,0 +1,130 @@
+import type { WsConnectionStatus, WsStatusListener } from './types.js';
+type WsEventMap = {
+    open: () => void;
+    close: (code: number, reason: string) => void;
+    error: (error: Event) => void;
+    message: (data: string) => void;
+};
+type WsEvent = keyof WsEventMap;
+/**
+ * Options for {@link ReconnectingWebSocket}.
+ *
+ * @public
+ */
+export interface ReconnectingWebSocketOptions {
+    maxRetries?: number;
+    pingIntervalMs?: number;
+    /**
+     * Keepalive frame sent every `pingIntervalMs` while the socket is open.
+     * Framing is venue-specific, so when omitted no keepalive is sent.
+     */
+    pingPayload?: string;
+    /**
+     * Stale-stream watchdog window. With `pingPayload` configured, the socket is
+     * force-reconnected when no inbound frame arrives within this window.
+     * Defaults to 3× `pingIntervalMs`.
+     */
+    staleWindowMs?: number;
+}
+/**
+ * A `WebSocket` transport that auto-reconnects with jittered exponential
+ * backoff (`partysocket` internals), buffers sends (bounded) while
+ * disconnected, keepalive-pings with the caller-supplied `pingPayload`, and
+ * force-reconnects a silently stale stream. Surfaces the
+ * {@link WsConnectionStatus} state machine: `reconnecting` on transient drops,
+ * terminal `disconnected` once the retry budget is exhausted.
+ *
+ * @public
+ */
+export declare class ReconnectingWebSocket {
+    private readonly socket;
+    private readonly maxRetries;
+    private readonly pingIntervalMs;
+    private readonly pingPayload;
+    private readonly staleWindowMs;
+    private closed;
+    private reconnectRequested;
+    private lastCloseRetryCount;
+    private pingTimer;
+    private staleTimer;
+    private listeners;
+    private statusListeners;
+    private status;
+    private readyResolvers;
+    constructor(url: string, options?: ReconnectingWebSocketOptions);
+    private handleOpen;
+    private handleClose;
+    private handleError;
+    private handleMessage;
+    private setStatus;
+    private callListener;
+    private startPing;
+    private stopPing;
+    private armWatchdog;
+    private clearWatchdog;
+    /**
+     * Send `data`, buffering it (bounded) for replay when the socket is not yet
+     * open.
+     *
+     * @public
+     */
+    send(data: string): void;
+    /**
+     * Permanently close the socket and suppress further reconnection.
+     *
+     * @public
+     */
+    close(): void;
+    /**
+     * Drop the current connection (if any) and reconnect with a fresh retry
+     * budget. Recovers a socket that reached terminal `disconnected`: status
+     * returns to `reconnecting` and the normal backoff cycle restarts.
+     *
+     * @public
+     */
+    reconnect(): void;
+    /**
+     * Register a listener for a socket lifecycle event.
+     *
+     * @public
+     */
+    on<E extends WsEvent>(event: E, fn: WsEventMap[E]): void;
+    /**
+     * Remove a previously registered lifecycle-event listener.
+     *
+     * @public
+     */
+    off<E extends WsEvent>(event: E, fn: WsEventMap[E]): void;
+    /**
+     * Current connection health. `reconnecting` until the first open;
+     * `disconnected` once auto-reconnect is abandoned (terminal until
+     * {@link ReconnectingWebSocket.reconnect} is called).
+     *
+     * @public
+     */
+    getStatus(): WsConnectionStatus;
+    /**
+     * Register a connection-health listener. Fires on every status transition,
+     * including the terminal `disconnected` emitted on reconnect exhaustion.
+     *
+     * @public
+     */
+    onStatus(fn: WsStatusListener): void;
+    /**
+     * Remove a previously registered connection-health listener.
+     *
+     * @public
+     */
+    offStatus(fn: WsStatusListener): void;
+    /**
+     * Resolve once the socket is open; reject if it closes or exhausts retries
+     * before opening. When the socket is already terminally dead — `close()`d or
+     * reconnect-exhausted (`disconnected`) — rejects immediately rather than
+     * queuing a waiter nothing would ever settle.
+     *
+     * @public
+     */
+    ready(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=ReconnectingWebSocket.d.ts.map

package/dist/esm/websocket/ReconnectingWebSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReconnectingWebSocket.d.ts","sourceRoot":"","sources":["../../../src/websocket/ReconnectingWebSocket.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGtE,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7C,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAC7B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC,CAAA;AAED,KAAK,OAAO,GAAG,MAAM,UAAU,CAAA;AAyB/B;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,kBAAkB,CAAQ;IAClC,OAAO,CAAC,mBAAmB,CAAQ;IACnC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,SAAS,CAKhB;IACD,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,cAAc,CAGf;gBAEK,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,4BAA4B;IAyB/D,OAAO,CAAC,UAAU,CAWjB;IAED,OAAO,CAAC,WAAW,CA4BlB;IAED,OAAO,CAAC,WAAW,CAIlB;IAED,OAAO,CAAC,aAAa,CAOpB;IAED,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,aAAa;IAOrB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM;IAIjB;;;;OAIG;IACH,KAAK;IAWL;;;;;;OAMG;IACH,SAAS;IAWT;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAIjD;;;;OAIG;IACH,GAAG,CAAC,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAIlD;;;;;;OAMG;IACH,SAAS,IAAI,kBAAkB;IAI/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,gBAAgB;IAI7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,gBAAgB;IAI9B;;;;;;;OAOG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAcvB"}

package/dist/esm/websocket/ReconnectingWebSocket.js

@@ -0,0 +1,288 @@
+import PartySocketWebSocket from 'partysocket/ws';
+import { wsLog } from './wsLog.js';
+/**
+ * Default reconnect attempt cap. With the jittered backoff below, ten attempts
+ * span roughly 20–60s of retries before the socket is declared `disconnected`
+ * — long enough for a live trading feed to ride out a transient network blip.
+ */
+const DEFAULT_MAX_RETRIES = 10;
+/** Default watchdog window: three keepalive intervals without inbound traffic. */
+const DEFAULT_STALE_WINDOW_PING_INTERVALS = 3;
+const CONNECTION_TIMEOUT_MS = 4_000;
+/** Uptime below which an open does not reset the retry budget, so an accept-then-drop server still exhausts. */
+const MIN_UPTIME_MS = 5_000;
+const MAX_ENQUEUED_MESSAGES = 1_000;
+/** First-retry delay is drawn once per socket from [500, 1500)ms to de-synchronize reconnect storms. */
+const MIN_RECONNECTION_DELAY_MS = 500;
+const RECONNECTION_JITTER_MS = 1_000;
+const MAX_RECONNECTION_DELAY_MS = 10_000;
+const CLOSED_ERROR = 'WebSocket closed';
+const EXHAUSTED_ERROR = 'WebSocket max reconnect attempts reached';
+const WS_PROVIDER_KEY = 'reconnecting-websocket';
+/**
+ * A `WebSocket` transport that auto-reconnects with jittered exponential
+ * backoff (`partysocket` internals), buffers sends (bounded) while
+ * disconnected, keepalive-pings with the caller-supplied `pingPayload`, and
+ * force-reconnects a silently stale stream. Surfaces the
+ * {@link WsConnectionStatus} state machine: `reconnecting` on transient drops,
+ * terminal `disconnected` once the retry budget is exhausted.
+ *
+ * @public
+ */
+export class ReconnectingWebSocket {
+    socket;
+    maxRetries;
+    pingIntervalMs;
+    pingPayload;
+    staleWindowMs;
+    closed = false;
+    reconnectRequested = false;
+    lastCloseRetryCount;
+    pingTimer = null;
+    staleTimer = null;
+    listeners = {
+        open: new Set(),
+        close: new Set(),
+        error: new Set(),
+        message: new Set(),
+    };
+    statusListeners = new Set();
+    status = 'reconnecting';
+    readyResolvers = [];
+    constructor(url, options) {
+        this.maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.pingIntervalMs = options?.pingIntervalMs ?? 30_000;
+        this.pingPayload = options?.pingPayload;
+        this.staleWindowMs =
+            options?.staleWindowMs ??
+                this.pingIntervalMs * DEFAULT_STALE_WINDOW_PING_INTERVALS;
+        this.socket = new PartySocketWebSocket(url, undefined, {
+            maxRetries: this.maxRetries,
+            connectionTimeout: CONNECTION_TIMEOUT_MS,
+            minUptime: MIN_UPTIME_MS,
+            maxEnqueuedMessages: MAX_ENQUEUED_MESSAGES,
+            minReconnectionDelay: MIN_RECONNECTION_DELAY_MS + Math.random() * RECONNECTION_JITTER_MS,
+            maxReconnectionDelay: MAX_RECONNECTION_DELAY_MS,
+        });
+        this.lastCloseRetryCount = this.socket.retryCount;
+        // The onX handlers receive the raw events; addEventListener would hand out
+        // partysocket's clones, which rewrite an empty close reason in Node.
+        this.socket.onopen = this.handleOpen;
+        this.socket.onclose = this.handleClose;
+        this.socket.onerror = this.handleError;
+        this.socket.onmessage = this.handleMessage;
+    }
+    handleOpen = () => {
+        this.startPing();
+        this.armWatchdog();
+        this.setStatus('connected');
+        for (const fn of this.listeners.open) {
+            this.callListener('open', fn);
+        }
+        for (const { resolve } of this.readyResolvers) {
+            resolve();
+        }
+        this.readyResolvers = [];
+    };
+    handleClose = (event) => {
+        this.stopPing();
+        this.clearWatchdog();
+        if (this.closed) {
+            return;
+        }
+        for (const fn of this.listeners.close) {
+            this.callListener('close', fn, event.code, event.reason);
+        }
+        // partysocket schedules the next attempt — incrementing retryCount —
+        // before dispatching close, and exhausts silently: a retryCount at the cap
+        // that did not move since the previous close means no attempt was
+        // scheduled, i.e. the retry budget is spent.
+        const retryCount = this.socket.retryCount;
+        const exhausted = !this.reconnectRequested &&
+            retryCount >= this.maxRetries &&
+            retryCount === this.lastCloseRetryCount;
+        this.lastCloseRetryCount = retryCount;
+        if (exhausted) {
+            for (const { reject } of this.readyResolvers) {
+                reject(new Error(EXHAUSTED_ERROR));
+            }
+            this.readyResolvers = [];
+            this.setStatus('disconnected');
+        }
+        else {
+            this.setStatus('reconnecting');
+        }
+    };
+    handleError = (event) => {
+        for (const fn of this.listeners.error) {
+            this.callListener('error', fn, event);
+        }
+    };
+    handleMessage = (event) => {
+        this.armWatchdog();
+        const data = typeof event.data === 'string' ? event.data : String(event.data);
+        for (const fn of this.listeners.message) {
+            this.callListener('message', fn, data);
+        }
+    };
+    setStatus(status) {
+        if (this.status === status) {
+            return;
+        }
+        this.status = status;
+        for (const fn of this.statusListeners) {
+            this.callListener('status', fn, status);
+        }
+    }
+    callListener(listenerType, listener, ...args) {
+        try {
+            listener(...args);
+        }
+        catch (error) {
+            wsLog.listenerFailure(WS_PROVIDER_KEY, listenerType, error);
+        }
+    }
+    startPing() {
+        const payload = this.pingPayload;
+        if (payload === undefined) {
+            return;
+        }
+        this.pingTimer = setInterval(() => {
+            if (this.socket.readyState === PartySocketWebSocket.OPEN) {
+                this.socket.send(payload);
+            }
+        }, this.pingIntervalMs);
+    }
+    stopPing() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+    }
+    armWatchdog() {
+        if (this.pingPayload === undefined || this.closed) {
+            return;
+        }
+        this.clearWatchdog();
+        this.staleTimer = setTimeout(() => {
+            // The keepalive went unanswered for the whole window: the connection is
+            // half-open and serving stale data — tear it down and reconnect.
+            this.reconnect();
+        }, this.staleWindowMs);
+    }
+    clearWatchdog() {
+        if (this.staleTimer) {
+            clearTimeout(this.staleTimer);
+            this.staleTimer = null;
+        }
+    }
+    /**
+     * Send `data`, buffering it (bounded) for replay when the socket is not yet
+     * open.
+     *
+     * @public
+     */
+    send(data) {
+        this.socket.send(data);
+    }
+    /**
+     * Permanently close the socket and suppress further reconnection.
+     *
+     * @public
+     */
+    close() {
+        this.closed = true;
+        this.stopPing();
+        this.clearWatchdog();
+        this.socket.close();
+        for (const { reject } of this.readyResolvers) {
+            reject(new Error(CLOSED_ERROR));
+        }
+        this.readyResolvers = [];
+    }
+    /**
+     * Drop the current connection (if any) and reconnect with a fresh retry
+     * budget. Recovers a socket that reached terminal `disconnected`: status
+     * returns to `reconnecting` and the normal backoff cycle restarts.
+     *
+     * @public
+     */
+    reconnect() {
+        this.closed = false;
+        // Suppress the exhaustion check for the synchronous teardown close the
+        // underlying reconnect dispatches — a fresh attempt is always scheduled.
+        this.reconnectRequested = true;
+        this.socket.reconnect();
+        this.reconnectRequested = false;
+        this.lastCloseRetryCount = this.socket.retryCount;
+        this.setStatus('reconnecting');
+    }
+    /**
+     * Register a listener for a socket lifecycle event.
+     *
+     * @public
+     */
+    on(event, fn) {
+        ;
+        this.listeners[event].add(fn);
+    }
+    /**
+     * Remove a previously registered lifecycle-event listener.
+     *
+     * @public
+     */
+    off(event, fn) {
+        ;
+        this.listeners[event].delete(fn);
+    }
+    /**
+     * Current connection health. `reconnecting` until the first open;
+     * `disconnected` once auto-reconnect is abandoned (terminal until
+     * {@link ReconnectingWebSocket.reconnect} is called).
+     *
+     * @public
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Register a connection-health listener. Fires on every status transition,
+     * including the terminal `disconnected` emitted on reconnect exhaustion.
+     *
+     * @public
+     */
+    onStatus(fn) {
+        this.statusListeners.add(fn);
+    }
+    /**
+     * Remove a previously registered connection-health listener.
+     *
+     * @public
+     */
+    offStatus(fn) {
+        this.statusListeners.delete(fn);
+    }
+    /**
+     * Resolve once the socket is open; reject if it closes or exhausts retries
+     * before opening. When the socket is already terminally dead — `close()`d or
+     * reconnect-exhausted (`disconnected`) — rejects immediately rather than
+     * queuing a waiter nothing would ever settle.
+     *
+     * @public
+     */
+    ready() {
+        if (this.socket.readyState === PartySocketWebSocket.OPEN) {
+            return Promise.resolve();
+        }
+        if (this.closed) {
+            return Promise.reject(new Error(CLOSED_ERROR));
+        }
+        if (this.status === 'disconnected') {
+            return Promise.reject(new Error(EXHAUSTED_ERROR));
+        }
+        return new Promise((resolve, reject) => {
+            this.readyResolvers.push({ resolve, reject });
+        });
+    }
+}
+//# sourceMappingURL=ReconnectingWebSocket.js.map

package/dist/esm/websocket/ReconnectingWebSocket.js.map

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

package/dist/esm/websocket/WsProviderBase.d.ts

@@ -0,0 +1,89 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types';
+import type { ProviderGetQuoteParams, QuoteListener } from '../types/provider.js';
+import type { ReconnectingWebSocket } from './ReconnectingWebSocket.js';
+import type { SubscriptionListener, WsProvider, WsStatusListener } from './types.js';
+/**
+ * Linger before tearing a channel off the wire after its last listener
+ * releases. A re-subscribe to the same key within this window cancels the
+ * pending teardown, so React StrictMode's synchronous unmount→remount (ref
+ * count 1→0→1) and fast route flips collapse to one wire subscription rather
+ * than a subscribe→unsubscribe→subscribe churn the venue would reject.
+ *
+ * @public
+ */
+export declare const WS_CHANNEL_TEARDOWN_LINGER_MS = 250;
+/**
+ * Base for per-provider realtime transports. Owns the {@link
+ * ReconnectingWebSocket}, the fan-out lifecycle — ref-counted multi-listener
+ * subscription per channel key, deferred teardown, status fan-out — so any
+ * number of consumers (and StrictMode double-mounts) collapse to exactly one
+ * wire subscribe/unsubscribe per key, and the wire-subscription registry:
+ * subs recorded via {@link WsProviderBase.registerSub} are sent only while
+ * connected and replayed (failure-isolated) on every (re)open. Subclasses own
+ * everything wire-specific via {@link WsProviderBase.openChannel}, {@link
+ * WsProviderBase.sendSubscribe} and {@link WsProviderBase.handleMessage}:
+ * payload framing, frame validation and dispatch.
+ *
+ * `TSub` is the per-subscription state {@link WsProviderBase.sendSubscribe}
+ * needs to (re)build one subscribe frame.
+ *
+ * @public
+ */
+export declare abstract class WsProviderBase<TSub = unknown> implements WsProvider {
+    protected readonly rws: ReconnectingWebSocket;
+    protected readonly providerKey: string;
+    private readonly channels;
+    private readonly statusListeners;
+    private readonly wireSubs;
+    constructor(rws: ReconnectingWebSocket, providerKey: string);
+    subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
+    reconnect(): void;
+    close(): void;
+    /** Deliver an event to every listener on `key`. */
+    protected emit(key: string, event: SubscriptionEvent): void;
+    /**
+     * Tear `key` off the wire immediately if no listener holds it — i.e. it is
+     * lingering in the deferred-teardown window (or its open is still
+     * unwinding). Returns `true` when the key is free (absent or just torn
+     * down), `false` — leaving the channel untouched — while live listeners
+     * hold it. Lets a subclass that enforces an exclusivity invariant across
+     * keys reclaim a released channel without waiting out the linger.
+     */
+    protected closeChannelIfIdle(key: string): boolean;
+    /**
+     * Record a wire subscription for replay-on-(re)open and, when the socket is
+     * already connected, send its subscribe frame via {@link sendSubscribe}.
+     * While the socket is down the replay loop on the next open is the sole
+     * sender — sending in both places would double-subscribe. A failed send
+     * removes the sub again so a rejected open leaves no registry entry behind.
+     */
+    protected registerSub(key: string, state: TSub): Promise<void>;
+    /** Forget a wire subscription so the next (re)open no longer replays it. */
+    protected unregisterSub(key: string): void;
+    private replaySubs;
+    /** Venue-specific {@link WsProvider.subscribeQuote}; see `resolveSubscribeQuote`. */
+    abstract subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    /** Canonical fan-out key for `sub`; must match the key the subclass emits to. */
+    protected abstract toKey(sub: Subscription): string;
+    /**
+     * Open the channel on the wire (0→1 transition only). Record the wire
+     * sub(s) via {@link registerSub} and return a closure that unregisters them
+     * and sends the unsubscribe frame(s).
+     */
+    protected abstract openChannel(sub: Subscription): Promise<() => void>;
+    /**
+     * Encode and send the subscribe frame for one registered sub. Called by the
+     * base while connected — once on register and again on every (re)open — so
+     * it must be safe to invoke repeatedly with the same state (e.g. re-fetch a
+     * fresh auth token per call rather than embedding one in `state`).
+     */
+    protected abstract sendSubscribe(state: TSub): void | Promise<void>;
+    /** Parse one inbound frame and route it via {@link emit}. */
+    protected abstract handleMessage(raw: string): void;
+    /** Release subclass-only resources on {@link close} (keep-alive, cached state). */
+    protected onClose(): void;
+    private callListener;
+    private acquireChannel;
+    private releaseChannel;
+}
+//# sourceMappingURL=WsProviderBase.d.ts.map

package/dist/esm/websocket/WsProviderBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WsProviderBase.d.ts","sourceRoot":"","sources":["../../../src/websocket/WsProviderBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAiBhD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,cAAc,CAAC,IAAI,GAAG,OAAO,CAAE,YAAW,UAAU;IACxE,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAA;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM;IAcrD,SAAS,CACb,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IA2BtB,SAAS,IAAI,IAAI;IAOjB,KAAK,IAAI,IAAI;IAab,mDAAmD;IACnD,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAU3D;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgBlD;;;;;;OAMG;cACa,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,4EAA4E;IAC5E,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;YAI5B,UAAU;IAaxB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CACrB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtB,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IAEnD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnE,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEnD,mFAAmF;IACnF,SAAS,CAAC,OAAO,IAAI,IAAI;IAEzB,OAAO,CAAC,YAAY;YAYN,cAAc;IAgD5B,OAAO,CAAC,cAAc;CAwCvB"}