@oobe-protocol-labs/synapse-sap-sdk 0.14.0 → 0.15.1

package/dist/esm/core/connection.d.ts

@@ -0,0 +1,305 @@
+/**
+ * @module core/connection
+ * @description RPC connection factory for SAP v2 SDK.
+ *
+ * Provides a high-level, synapse-client-sdk–compatible entry point
+ * for creating {@link SapClient} instances from an RPC URL and wallet.
+ *
+ * @category Core
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapConnection } from "@synapse-sap/sdk";
+ *
+ * // Quick start — RPC URL + Keypair
+ * const sap = SapConnection.fromKeypair("https://api.devnet.solana.com", keypair);
+ * const agent = await sap.client.agent.fetch();
+ *
+ * // Or build step-by-step
+ * const conn = new SapConnection({
+ *   rpcUrl: "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=xxx",
+ *   cluster: "mainnet-beta",
+ *   commitment: "confirmed",
+ * });
+ * const client = conn.createClient(wallet);
+ * ```
+ */
+import { Connection, type Commitment, Keypair, type PublicKey, type Transaction, type VersionedTransaction } from "@solana/web3.js";
+import { SapClient } from "./client";
+/**
+ * @interface SapWallet
+ * @description Minimal wallet/signer interface compatible with
+ * Anchor's `AnchorProvider`. Avoids importing `Wallet` from
+ * `@coral-xyz/anchor` which is absent in ESM builds.
+ * @category Core
+ * @since v0.4.1
+ */
+export interface SapWallet {
+    readonly publicKey: PublicKey;
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+/**
+ * @name KeypairWallet
+ * @description Simple wallet wrapper around a `Keypair`.
+ * Drop-in replacement for Anchor's `NodeWallet` / `Wallet` class.
+ * @category Core
+ * @since v0.4.1
+ */
+export declare class KeypairWallet implements SapWallet {
+    readonly payer: Keypair;
+    readonly publicKey: PublicKey;
+    constructor(payer: Keypair);
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+/**
+ * @name SapCluster
+ * @description Supported Solana cluster names used to select the RPC endpoint
+ * and corresponding SAP program ID.
+ * @category Core
+ * @since v0.1.0
+ */
+export type SapCluster = "mainnet-beta" | "devnet" | "localnet";
+/**
+ * @interface SapConnectionConfig
+ * @description Configuration object used to initialise a {@link SapConnection}.
+ * @category Core
+ * @since v0.1.0
+ * @see {@link SapConnection}
+ */
+export interface SapConnectionConfig {
+    /**
+     * @property {string} rpcUrl
+     * @description Solana JSON-RPC endpoint URL (e.g. `https://api.devnet.solana.com`).
+     */
+    rpcUrl: string;
+    /**
+     * @property {string} [wsUrl]
+     * @description WebSocket endpoint URL. When omitted the SDK derives it
+     * automatically from {@link rpcUrl} by swapping the protocol scheme.
+     */
+    wsUrl?: string;
+    /**
+     * @property {Commitment} [commitment]
+     * @description Commitment level for queries and transaction confirmations.
+     * Defaults to `"confirmed"` when not provided.
+     */
+    commitment?: Commitment;
+    /**
+     * @property {SapCluster} [cluster]
+     * @description Cluster hint (`mainnet-beta` | `devnet` | `localnet`).
+     * When omitted the SDK infers it from {@link rpcUrl} via
+     * {@link SapConnection.detectCluster}.
+     */
+    cluster?: SapCluster;
+}
+/**
+ * @name SapConnection
+ * @description Lightweight RPC connection wrapper that creates
+ * properly-configured {@link SapClient} instances.
+ *
+ * Compatible with the `synapse-client-sdk` connection model:
+ * start from an RPC URL, attach a wallet, get a typed client.
+ *
+ * @category Core
+ * @since v0.1.0
+ * @see {@link SapClient}
+ * @see {@link SapConnectionConfig}
+ *
+ * @example
+ * ```ts
+ * // Factory shortcut for devnet
+ * const conn = SapConnection.devnet();
+ * const client = conn.createClient(wallet);
+ *
+ * // One-liner with Keypair
+ * const { client } = SapConnection.fromKeypair(
+ *   "https://api.devnet.solana.com",
+ *   keypair,
+ * );
+ * ```
+ */
+export declare class SapConnection {
+    /**
+     * @readonly
+     * @description Raw Solana {@link Connection}. Exposed for advanced
+     * use-cases that need direct RPC access.
+     */
+    readonly connection: Connection;
+    /**
+     * @readonly
+     * @description The resolved Solana cluster for this connection,
+     * either explicitly provided or auto-detected from the RPC URL.
+     */
+    readonly cluster: SapCluster;
+    /**
+     * @readonly
+     * @description Commitment level used for all queries and
+     * transaction confirmations on this connection.
+     */
+    readonly commitment: Commitment;
+    /**
+     * @readonly
+     * @description The SAP on-chain program {@link PublicKey} resolved
+     * for the current {@link cluster}.
+     * @see {@link SapConnection.programIdForCluster}
+     */
+    readonly programId: PublicKey;
+    constructor(config: SapConnectionConfig);
+    /**
+     * Create a {@link SapConnection} for **devnet** with sensible defaults.
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana devnet.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.devnet();
+     * ```
+     */
+    static devnet(commitment?: Commitment): SapConnection;
+    /**
+     * Create a {@link SapConnection} for **mainnet-beta** with sensible defaults.
+     *
+     * @static
+     * @param {string} [rpcUrl="https://api.mainnet-beta.solana.com"] — Custom RPC URL.
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana mainnet-beta.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.mainnet("https://my-rpc.example.com");
+     * ```
+     */
+    static mainnet(rpcUrl?: string, commitment?: Commitment): SapConnection;
+    /**
+     * Create a {@link SapConnection} for **localnet** (`localhost:8899`).
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting a local validator.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.localnet();
+     * ```
+     */
+    static localnet(commitment?: Commitment): SapConnection;
+    /**
+     * One-liner: create a {@link SapConnection} + {@link SapClient} from
+     * an RPC URL and a `Keypair`. Perfect for scripts and CLI tools.
+     *
+     * @static
+     * @param {string} rpcUrl — Solana JSON-RPC endpoint.
+     * @param {Keypair} keypair — Signer keypair.
+     * @param {object} [opts] — Optional overrides.
+     * @param {Commitment} [opts.commitment] — Commitment level.
+     * @param {SapCluster} [opts.cluster] — Explicit cluster hint.
+     * @returns {SapConnection & { readonly client: SapClient }} Connection with an attached client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const { client, connection } = SapConnection.fromKeypair(
+     *   "https://api.devnet.solana.com",
+     *   Keypair.generate(),
+     * );
+     * ```
+     */
+    static fromKeypair(rpcUrl: string, keypair: Keypair, opts?: {
+        commitment?: Commitment;
+        cluster?: SapCluster;
+    }): SapConnection & {
+        readonly client: SapClient;
+    };
+    /**
+     * Create a {@link SapClient} from a {@link SapWallet} (signer).
+     *
+     * @param {SapWallet} wallet — A wallet/signer implementing {@link SapWallet}.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.createClient(new KeypairWallet(keypair));
+     * ```
+     */
+    createClient(wallet: SapWallet): SapClient;
+    /**
+     * Create a {@link SapClient} from a raw {@link Keypair}.
+     *
+     * @param {Keypair} keypair — The signer keypair.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.fromKeypair(Keypair.generate());
+     * ```
+     */
+    fromKeypair(keypair: Keypair): SapClient;
+    /**
+     * Request an airdrop (devnet / localnet only).
+     *
+     * @param {PublicKey} to — Recipient public key.
+     * @param {number} solAmount — Amount of SOL to airdrop.
+     * @returns {Promise<string>} The confirmed transaction signature.
+     * @throws {Error} If the airdrop request or confirmation fails (e.g. on mainnet).
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sig = await conn.airdrop(wallet.publicKey, 2);
+     * ```
+     */
+    airdrop(to: PublicKey, solAmount: number): Promise<string>;
+    /**
+     * Get the SOL balance of an address in **lamports**.
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in lamports.
+     * @since v0.1.0
+     */
+    getBalance(address: PublicKey): Promise<number>;
+    /**
+     * Get the SOL balance of an address in **SOL** (human-readable).
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in SOL.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sol = await conn.getBalanceSol(wallet.publicKey);
+     * console.log(`Balance: ${sol} SOL`);
+     * ```
+     */
+    getBalanceSol(address: PublicKey): Promise<number>;
+    /**
+     * Infer the {@link SapCluster} from an RPC URL by inspecting
+     * well-known substrings (`devnet`, `localhost`, `:8899`).
+     *
+     * @static
+     * @param {string} rpcUrl — The RPC endpoint to inspect.
+     * @returns {SapCluster} The detected cluster, defaulting to `"mainnet-beta"`.
+     * @since v0.1.0
+     */
+    static detectCluster(rpcUrl: string): SapCluster;
+    /**
+     * Map a {@link SapCluster} to the canonical SAP on-chain program ID.
+     *
+     * @static
+     * @param {SapCluster} cluster — Target cluster.
+     * @returns {PublicKey} The program {@link PublicKey} for the given cluster.
+     * @since v0.1.0
+     * @see {@link SAP_PROGRAM_ID}
+     */
+    static programIdForCluster(cluster: SapCluster): PublicKey;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/esm/core/connection.d.ts.map

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

package/dist/esm/core/connection.js

@@ -0,0 +1,345 @@
+/**
+ * @module core/connection
+ * @description RPC connection factory for SAP v2 SDK.
+ *
+ * Provides a high-level, synapse-client-sdk–compatible entry point
+ * for creating {@link SapClient} instances from an RPC URL and wallet.
+ *
+ * @category Core
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapConnection } from "@synapse-sap/sdk";
+ *
+ * // Quick start — RPC URL + Keypair
+ * const sap = SapConnection.fromKeypair("https://api.devnet.solana.com", keypair);
+ * const agent = await sap.client.agent.fetch();
+ *
+ * // Or build step-by-step
+ * const conn = new SapConnection({
+ *   rpcUrl: "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=xxx",
+ *   cluster: "mainnet-beta",
+ *   commitment: "confirmed",
+ * });
+ * const client = conn.createClient(wallet);
+ * ```
+ */
+import { Connection, LAMPORTS_PER_SOL, } from "@solana/web3.js";
+import { AnchorProvider } from "@coral-xyz/anchor";
+import { SAP_PROGRAM_ID, MAINNET_SAP_PROGRAM_ID, DEVNET_SAP_PROGRAM_ID, LOCALNET_SAP_PROGRAM_ID, } from "../constants";
+import { SapClient } from "./client";
+/**
+ * @name KeypairWallet
+ * @description Simple wallet wrapper around a `Keypair`.
+ * Drop-in replacement for Anchor's `NodeWallet` / `Wallet` class.
+ * @category Core
+ * @since v0.4.1
+ */
+export class KeypairWallet {
+    payer;
+    publicKey;
+    constructor(payer) {
+        this.payer = payer;
+        this.publicKey = payer.publicKey;
+    }
+    async signTransaction(tx) {
+        if ("partialSign" in tx) {
+            tx.partialSign(this.payer);
+        }
+        else {
+            tx.sign([this.payer]);
+        }
+        return tx;
+    }
+    async signAllTransactions(txs) {
+        for (const tx of txs) {
+            await this.signTransaction(tx);
+        }
+        return txs;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+//  Implementation
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapConnection
+ * @description Lightweight RPC connection wrapper that creates
+ * properly-configured {@link SapClient} instances.
+ *
+ * Compatible with the `synapse-client-sdk` connection model:
+ * start from an RPC URL, attach a wallet, get a typed client.
+ *
+ * @category Core
+ * @since v0.1.0
+ * @see {@link SapClient}
+ * @see {@link SapConnectionConfig}
+ *
+ * @example
+ * ```ts
+ * // Factory shortcut for devnet
+ * const conn = SapConnection.devnet();
+ * const client = conn.createClient(wallet);
+ *
+ * // One-liner with Keypair
+ * const { client } = SapConnection.fromKeypair(
+ *   "https://api.devnet.solana.com",
+ *   keypair,
+ * );
+ * ```
+ */
+export class SapConnection {
+    /**
+     * @readonly
+     * @description Raw Solana {@link Connection}. Exposed for advanced
+     * use-cases that need direct RPC access.
+     */
+    connection;
+    /**
+     * @readonly
+     * @description The resolved Solana cluster for this connection,
+     * either explicitly provided or auto-detected from the RPC URL.
+     */
+    cluster;
+    /**
+     * @readonly
+     * @description Commitment level used for all queries and
+     * transaction confirmations on this connection.
+     */
+    commitment;
+    /**
+     * @readonly
+     * @description The SAP on-chain program {@link PublicKey} resolved
+     * for the current {@link cluster}.
+     * @see {@link SapConnection.programIdForCluster}
+     */
+    programId;
+    constructor(config) {
+        this.commitment = config.commitment ?? "confirmed";
+        this.cluster = config.cluster ?? SapConnection.detectCluster(config.rpcUrl);
+        this.programId = SapConnection.programIdForCluster(this.cluster);
+        this.connection = new Connection(config.rpcUrl, {
+            commitment: this.commitment,
+            wsEndpoint: config.wsUrl,
+        });
+    }
+    // ─────────────────────────────────────────────
+    //  Factory helpers
+    // ─────────────────────────────────────────────
+    /**
+     * Create a {@link SapConnection} for **devnet** with sensible defaults.
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana devnet.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.devnet();
+     * ```
+     */
+    static devnet(commitment = "confirmed") {
+        return new SapConnection({
+            rpcUrl: "https://api.devnet.solana.com",
+            cluster: "devnet",
+            commitment,
+        });
+    }
+    /**
+     * Create a {@link SapConnection} for **mainnet-beta** with sensible defaults.
+     *
+     * @static
+     * @param {string} [rpcUrl="https://api.mainnet-beta.solana.com"] — Custom RPC URL.
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting Solana mainnet-beta.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.mainnet("https://my-rpc.example.com");
+     * ```
+     */
+    static mainnet(rpcUrl = "https://api.mainnet-beta.solana.com", commitment = "confirmed") {
+        return new SapConnection({ rpcUrl, cluster: "mainnet-beta", commitment });
+    }
+    /**
+     * Create a {@link SapConnection} for **localnet** (`localhost:8899`).
+     *
+     * @static
+     * @param {Commitment} [commitment="confirmed"] — Commitment level.
+     * @returns {SapConnection} A connection targeting a local validator.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const conn = SapConnection.localnet();
+     * ```
+     */
+    static localnet(commitment = "confirmed") {
+        return new SapConnection({
+            rpcUrl: "http://localhost:8899",
+            cluster: "localnet",
+            commitment,
+        });
+    }
+    /**
+     * One-liner: create a {@link SapConnection} + {@link SapClient} from
+     * an RPC URL and a `Keypair`. Perfect for scripts and CLI tools.
+     *
+     * @static
+     * @param {string} rpcUrl — Solana JSON-RPC endpoint.
+     * @param {Keypair} keypair — Signer keypair.
+     * @param {object} [opts] — Optional overrides.
+     * @param {Commitment} [opts.commitment] — Commitment level.
+     * @param {SapCluster} [opts.cluster] — Explicit cluster hint.
+     * @returns {SapConnection & { readonly client: SapClient }} Connection with an attached client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const { client, connection } = SapConnection.fromKeypair(
+     *   "https://api.devnet.solana.com",
+     *   Keypair.generate(),
+     * );
+     * ```
+     */
+    static fromKeypair(rpcUrl, keypair, opts) {
+        const conn = new SapConnection({
+            rpcUrl,
+            commitment: opts?.commitment,
+            cluster: opts?.cluster,
+        });
+        const client = conn.createClient(new KeypairWallet(keypair));
+        return Object.assign(conn, { client });
+    }
+    // ─────────────────────────────────────────────
+    //  Client creation
+    // ─────────────────────────────────────────────
+    /**
+     * Create a {@link SapClient} from a {@link SapWallet} (signer).
+     *
+     * @param {SapWallet} wallet — A wallet/signer implementing {@link SapWallet}.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.createClient(new KeypairWallet(keypair));
+     * ```
+     */
+    createClient(wallet) {
+        const provider = new AnchorProvider(this.connection, wallet, {
+            commitment: this.commitment,
+        });
+        return SapClient.from(provider, this.programId);
+    }
+    /**
+     * Create a {@link SapClient} from a raw {@link Keypair}.
+     *
+     * @param {Keypair} keypair — The signer keypair.
+     * @returns {SapClient} A fully-configured SAP client.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const client = conn.fromKeypair(Keypair.generate());
+     * ```
+     */
+    fromKeypair(keypair) {
+        return this.createClient(new KeypairWallet(keypair));
+    }
+    // ─────────────────────────────────────────────
+    //  Utility methods
+    // ─────────────────────────────────────────────
+    /**
+     * Request an airdrop (devnet / localnet only).
+     *
+     * @param {PublicKey} to — Recipient public key.
+     * @param {number} solAmount — Amount of SOL to airdrop.
+     * @returns {Promise<string>} The confirmed transaction signature.
+     * @throws {Error} If the airdrop request or confirmation fails (e.g. on mainnet).
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sig = await conn.airdrop(wallet.publicKey, 2);
+     * ```
+     */
+    async airdrop(to, solAmount) {
+        const sig = await this.connection.requestAirdrop(to, solAmount * LAMPORTS_PER_SOL);
+        await this.connection.confirmTransaction(sig, this.commitment);
+        return sig;
+    }
+    /**
+     * Get the SOL balance of an address in **lamports**.
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in lamports.
+     * @since v0.1.0
+     */
+    async getBalance(address) {
+        return this.connection.getBalance(address, this.commitment);
+    }
+    /**
+     * Get the SOL balance of an address in **SOL** (human-readable).
+     *
+     * @param {PublicKey} address — The account to query.
+     * @returns {Promise<number>} Balance in SOL.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const sol = await conn.getBalanceSol(wallet.publicKey);
+     * console.log(`Balance: ${sol} SOL`);
+     * ```
+     */
+    async getBalanceSol(address) {
+        const lamports = await this.getBalance(address);
+        return lamports / LAMPORTS_PER_SOL;
+    }
+    // ─────────────────────────────────────────────
+    //  Internal helpers
+    // ─────────────────────────────────────────────
+    /**
+     * Infer the {@link SapCluster} from an RPC URL by inspecting
+     * well-known substrings (`devnet`, `localhost`, `:8899`).
+     *
+     * @static
+     * @param {string} rpcUrl — The RPC endpoint to inspect.
+     * @returns {SapCluster} The detected cluster, defaulting to `"mainnet-beta"`.
+     * @since v0.1.0
+     */
+    static detectCluster(rpcUrl) {
+        const lower = rpcUrl.toLowerCase();
+        if (lower.includes("devnet"))
+            return "devnet";
+        if (lower.includes("localhost") ||
+            lower.includes("127.0.0.1") ||
+            lower.includes(":8899"))
+            return "localnet";
+        return "mainnet-beta";
+    }
+    /**
+     * Map a {@link SapCluster} to the canonical SAP on-chain program ID.
+     *
+     * @static
+     * @param {SapCluster} cluster — Target cluster.
+     * @returns {PublicKey} The program {@link PublicKey} for the given cluster.
+     * @since v0.1.0
+     * @see {@link SAP_PROGRAM_ID}
+     */
+    static programIdForCluster(cluster) {
+        switch (cluster) {
+            case "mainnet-beta":
+                return MAINNET_SAP_PROGRAM_ID;
+            case "devnet":
+                return DEVNET_SAP_PROGRAM_ID;
+            case "localnet":
+                return LOCALNET_SAP_PROGRAM_ID;
+            default:
+                return SAP_PROGRAM_ID;
+        }
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/esm/core/connection.js.map

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

package/dist/esm/core/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module core
+ * @description Core infrastructure — client creation and RPC connection.
+ *
+ * @example
+ * ```ts
+ * import { SapClient, SapConnection } from "@synapse-sap/sdk";
+ *
+ * // From Anchor provider
+ * const client = SapClient.from(provider);
+ *
+ * // From RPC URL + keypair (synapse-client-sdk compatible)
+ * const conn = SapConnection.devnet();
+ * const client2 = conn.fromKeypair(keypair);
+ * ```
+ */
+export { SapClient } from "./client";
+export { SapConnection, KeypairWallet } from "./connection";
+export type { SapCluster, SapConnectionConfig, SapWallet } from "./connection";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}