near-kit 0.0.0 → 0.2.0

package/dist/core/near.js

@@ -0,0 +1,504 @@
+/**
+ * Main NEAR client class
+ */
+import { createContract } from "../contracts/contract.js";
+import { NearError } from "../errors/index.js";
+import { InMemoryKeyStore } from "../keys/index.js";
+import { parseKey } from "../utils/key.js";
+import { generateNep413Nonce } from "../utils/nep413.js";
+import { normalizeAmount, normalizeGas } from "../utils/validation.js";
+import * as actions from "./actions.js";
+import { NearConfigSchema, resolveNetworkConfig, } from "./config-schemas.js";
+import { DEFAULT_FUNCTION_CALL_GAS } from "./constants.js";
+import { RpcClient } from "./rpc/rpc.js";
+import { TransactionBuilder } from "./transaction.js";
+/**
+ * Main client for interacting with the NEAR blockchain.
+ *
+ * Wraps RPC access, key management, wallet integrations, and the fluent
+ * transaction builder. Most applications create one `Near` instance per
+ * network and reuse it for all operations.
+ *
+ * @remarks
+ * Configure the client with {@link NearConfig} to choose networks, key stores,
+ * wallets, and retry behavior. For a guided overview see
+ * `docs/01-getting-started.md` and `docs/02-core-concepts.md`.
+ */
+export class Near {
+    constructor(config = {}) {
+        const validatedConfig = NearConfigSchema.parse(config);
+        this._initializeRpc(validatedConfig);
+        this._resolveKeyStore(validatedConfig);
+        this._resolveSigner(validatedConfig, config);
+        if (validatedConfig.defaultSignerId) {
+            this.defaultSignerId = validatedConfig.defaultSignerId;
+        }
+        this.defaultWaitUntil =
+            validatedConfig.defaultWaitUntil || "EXECUTED_OPTIMISTIC";
+        this.wallet = validatedConfig.wallet;
+    }
+    /**
+     * Initialize RPC client from configuration
+     * @internal
+     */
+    _initializeRpc(validatedConfig) {
+        const networkConfig = resolveNetworkConfig(validatedConfig.network);
+        const rpcUrl = validatedConfig.rpcUrl || networkConfig.rpcUrl;
+        this.rpc = new RpcClient(rpcUrl, validatedConfig.headers, validatedConfig.retryConfig);
+    }
+    /**
+     * Resolve and initialize keystore from configuration
+     * @internal
+     */
+    _resolveKeyStore(validatedConfig) {
+        this.keyStore = this.resolveKeyStore(validatedConfig.keyStore);
+    }
+    /**
+     * Resolve and initialize signer from configuration
+     * Handles privateKey, custom signer, and sandbox root key auto-detection
+     * @internal
+     */
+    _resolveSigner(validatedConfig, originalConfig) {
+        const signer = validatedConfig.signer;
+        const privateKey = validatedConfig.privateKey;
+        if (signer) {
+            this.signer = signer;
+        }
+        else if (privateKey) {
+            const keyPair = typeof privateKey === "string"
+                ? parseKey(privateKey)
+                : parseKey(privateKey.toString());
+            this.signer = async (message) => keyPair.sign(message);
+            // If network is a Sandbox-like object with rootAccount, add key to keyStore
+            // Use original config.network (before validation) to preserve extra properties
+            const network = originalConfig.network;
+            if (network && typeof network === "object" && "rootAccount" in network) {
+                const rootAccount = network
+                    .rootAccount;
+                void this.keyStore.add(rootAccount.id, keyPair);
+            }
+        }
+        // Auto-add sandbox root key to keyStore if available and no explicit signer/privateKey
+        // This enables simple usage like: new Near({ network: sandbox })
+        // while still allowing multi-account scenarios via keyStore
+        if (!signer && !privateKey) {
+            const network = originalConfig.network;
+            if (network && typeof network === "object" && "rootAccount" in network) {
+                const rootAccount = network;
+                // Guard: only auto-add if both id and secretKey are non-empty strings
+                if (rootAccount.rootAccount?.id &&
+                    rootAccount.rootAccount?.secretKey &&
+                    typeof rootAccount.rootAccount.secretKey === "string") {
+                    const keyPair = parseKey(rootAccount.rootAccount.secretKey);
+                    // Store the promise to ensure async keystores complete initialization
+                    this.pendingKeyStoreInit = this.keyStore.add(rootAccount.rootAccount.id, keyPair);
+                }
+            }
+        }
+    }
+    /**
+     * Ensure any pending keystore initialization is complete
+     * @internal
+     */
+    async ensureKeyStoreReady() {
+        if (this.pendingKeyStoreInit) {
+            await this.pendingKeyStoreInit;
+            delete this.pendingKeyStoreInit;
+        }
+    }
+    /**
+     * Resolve key store from config input
+     * @internal
+     */
+    resolveKeyStore(keyStoreConfig) {
+        if (!keyStoreConfig) {
+            return new InMemoryKeyStore();
+        }
+        if (typeof keyStoreConfig === "string") {
+            // Import FileKeyStore dynamically to avoid bundling in browser
+            // For now, return in-memory
+            return new InMemoryKeyStore();
+        }
+        if ("add" in keyStoreConfig && "get" in keyStoreConfig) {
+            return keyStoreConfig;
+        }
+        // Record of account -> key mappings
+        return new InMemoryKeyStore(keyStoreConfig);
+    }
+    /**
+     * Get signer ID from options, default, or wallet
+     * @internal
+     */
+    async getSignerId(signerId) {
+        if (signerId)
+            return signerId;
+        if (this.defaultSignerId)
+            return this.defaultSignerId;
+        // Get from wallet if available
+        if (this.wallet) {
+            const accounts = await this.wallet.getAccounts();
+            if (accounts.length === 0) {
+                throw new NearError("No accounts connected to wallet", "NO_WALLET_ACCOUNTS");
+            }
+            // Safe to use non-null assertion after length check
+            // biome-ignore lint/style/noNonNullAssertion: verified accounts[0] exists above
+            return accounts[0].accountId;
+        }
+        throw new NearError("No signer ID provided. Set signerId in options or config.", "MISSING_SIGNER");
+    }
+    /**
+     * Call a view function on a contract (read-only, no gas).
+     *
+     * @param contractId - Target contract account ID.
+     * @param methodName - Name of the view method to call.
+     * @param args - Arguments object or raw bytes; defaults to `{}`.
+     * @param options - Optional {@link BlockReference} to specify finality or block.
+     *
+     * @returns Parsed JSON result when the contract returns JSON, otherwise the
+     * raw string value typed as `T`.
+     *
+     * @remarks
+     * - View calls are free and do not require a signer or gas.
+     * - Errors thrown by the contract surface as {@link ContractExecutionError}.
+     *
+     * @see NearConfig.defaultWaitUntil
+     */
+    async view(contractId, methodName, args = {}, options) {
+        const result = await this.rpc.viewFunction(contractId, methodName, args, options);
+        // Decode result
+        const resultBuffer = new Uint8Array(result.result);
+        const resultString = new TextDecoder().decode(resultBuffer);
+        if (!resultString) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(resultString);
+        }
+        catch {
+            return resultString;
+        }
+    }
+    /**
+     * Call a change function on a contract (requires signature and gas).
+     *
+     * Uses the connected wallet when available, otherwise falls back to the
+     * configured signer / private key / key store.
+     *
+     * @param contractId - Target contract account ID.
+     * @param methodName - Name of the change method to call.
+     * @param args - Arguments object or raw bytes; defaults to `{}`.
+     * @param options - Call options such as gas, attached deposit, signerId and wait level.
+     *
+     * @returns The decoded contract return value typed as `T`.
+     *
+     * @throws {NearError} If no signer can be resolved.
+     * @throws {FunctionCallError} If the contract panics or returns an error.
+     * @throws {InvalidTransactionError} If the transaction itself is invalid.
+     * @throws {NetworkError} If the RPC request fails after retries.
+     *
+     * @example
+     * ```typescript
+     * await near.call(
+     *   "contract.near",
+     *   "increment",
+     *   { by: 1 },
+     *   { attachedDeposit: "1 yocto", gas: "30 Tgas" },
+     * )
+     * ```
+     */
+    async call(contractId, methodName, args = {}, options = {}) {
+        const signerId = await this.getSignerId(options.signerId);
+        // Use wallet if available
+        if (this.wallet) {
+            const argsBytes = args instanceof Uint8Array
+                ? args
+                : new TextEncoder().encode(JSON.stringify(args));
+            const gas = options.gas
+                ? normalizeGas(options.gas)
+                : DEFAULT_FUNCTION_CALL_GAS;
+            const deposit = options.attachedDeposit
+                ? normalizeAmount(options.attachedDeposit)
+                : "0";
+            const result = await this.wallet.signAndSendTransaction({
+                signerId,
+                receiverId: contractId,
+                actions: [
+                    actions.functionCall(methodName, argsBytes, BigInt(gas), BigInt(deposit)),
+                ],
+            });
+            return result;
+        }
+        // Use private key/signer approach
+        const functionCallOptions = {};
+        if (options.gas !== undefined) {
+            functionCallOptions.gas = options.gas;
+        }
+        if (options.attachedDeposit !== undefined) {
+            functionCallOptions.attachedDeposit = options.attachedDeposit;
+        }
+        const sendOptions = options.waitUntil
+            ? { waitUntil: options.waitUntil }
+            : {};
+        const result = await this.transaction(signerId)
+            .functionCall(contractId, methodName, args, functionCallOptions)
+            .send(sendOptions);
+        return result;
+    }
+    /**
+     * Send NEAR tokens to an account.
+     *
+     * @param receiverId - Account ID that will receive the tokens.
+     * @param amount - Amount to send, expressed as {@link Amount} (e.g. `"10 NEAR"` or `"1 yocto"`).
+     *
+     * @returns The final transaction outcome from the wallet or RPC.
+     *
+     * @throws {NearError} If no signer can be resolved.
+     * @throws {InvalidTransactionError} If the transfer transaction is invalid.
+     * @throws {NetworkError} If the RPC request fails after retries.
+     *
+     * @remarks
+     * This is a convenience wrapper over {@link Near.transaction} with a single
+     * `transfer` action.
+     */
+    async send(receiverId, amount) {
+        const signerId = await this.getSignerId();
+        // Use wallet if available
+        if (this.wallet) {
+            const amountYocto = normalizeAmount(amount);
+            return await this.wallet.signAndSendTransaction({
+                signerId,
+                receiverId,
+                actions: [actions.transfer(BigInt(amountYocto))],
+            });
+        }
+        // Use private key/signer approach
+        return await this.transaction(signerId).transfer(receiverId, amount).send();
+    }
+    /**
+     * Sign a message using NEP-413 standard.
+     *
+     * NEP-413 enables off-chain message signing for authentication and ownership verification
+     * without gas fees or blockchain transactions. Useful for:
+     * - Login/authentication flows
+     * - Proving account ownership
+     * - Signing intents for meta-transactions
+     * - Off-chain authorization
+     *
+     * @param params - Message signing parameters
+     * @param options - Optional signer ID (defaults to first account)
+     * @returns Signed message with account ID, public key, and signature
+     *
+     * @throws {NearError} If no wallet or keystore is configured
+     * @throws {NearError} If the key doesn't support NEP-413 signing
+     *
+     * @see https://github.com/near/NEPs/blob/master/neps/nep-0413.md
+     *
+     * @example
+     * ```typescript
+     * // Sign a message for authentication
+     * const signedMessage = await near.signMessage({
+     *   message: "Login to MyApp",
+     *   recipient: "myapp.near",
+     *   nonce: crypto.getRandomValues(new Uint8Array(32)),
+     * })
+     *
+     * // Send to backend for verification
+     * await fetch("/api/auth", {
+     *   method: "POST",
+     *   body: JSON.stringify(signedMessage),
+     * })
+     * ```
+     */
+    async signMessage(params, options) {
+        const signerId = await this.getSignerId(options?.signerId);
+        // Add nonce if not provided
+        const fullParams = {
+            ...params,
+            nonce: "nonce" in params ? params.nonce : generateNep413Nonce(),
+        };
+        // Try wallet first if available
+        if (this.wallet?.signMessage) {
+            try {
+                return await this.wallet.signMessage(fullParams);
+            }
+            catch (error) {
+                // Fall through to keystore if wallet doesn't support it
+                console.warn("Wallet signMessage failed, trying keystore:", error);
+            }
+        }
+        // Use keystore approach
+        // Ensure any pending keystore initialization is complete
+        await this.ensureKeyStoreReady();
+        const keyPair = await this.keyStore.get(signerId);
+        if (!keyPair) {
+            throw new NearError(`No key found for account ${signerId}. Add a key using keyStore.add() or configure a wallet.`, "NO_KEY_FOUND");
+        }
+        if (!keyPair.signNep413Message) {
+            throw new NearError("Key pair does not support NEP-413 message signing", "UNSUPPORTED_OPERATION");
+        }
+        return keyPair.signNep413Message(signerId, fullParams);
+    }
+    /**
+     * Get account balance in NEAR.
+     *
+     * @param accountId - Account ID to query.
+     * @param options - Optional {@link BlockReference} to control finality or block.
+     *
+     * @returns Balance formatted as `"X.YY NEAR"`.
+     *
+     * @throws {AccountDoesNotExistError} If the account does not exist.
+     * @throws {NetworkError} If the RPC request fails.
+     *
+     * @remarks
+     * This is a convenience helper over {@link RpcClient.getAccount}. For more
+     * detailed information (storage, locked balance, etc.) call `rpc.getAccount`
+     * directly.
+     */
+    async getBalance(accountId, options) {
+        // RPC client now throws AccountDoesNotExistError directly
+        const account = await this.rpc.getAccount(accountId, options);
+        // Convert yoctoNEAR to NEAR
+        const balanceYocto = BigInt(account.amount);
+        const balanceNear = Number(balanceYocto) / 1e24;
+        return balanceNear.toFixed(2);
+    }
+    /**
+     * Check if an account exists.
+     *
+     * @param accountId - Account ID to check.
+     * @param options - Optional {@link BlockReference} to control finality or block.
+     *
+     * @returns `true` if the account exists, `false` otherwise.
+     *
+     * @remarks
+     * This method swallows all errors and returns `false` on failure. Use
+     * {@link RpcClient.getAccount} if you need to distinguish error causes.
+     */
+    async accountExists(accountId, options) {
+        try {
+            await this.rpc.getAccount(accountId, options);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get transaction status with detailed receipt information
+     *
+     * Queries the status of a transaction by hash using the EXPERIMENTAL_tx_status RPC method,
+     * returning the final transaction result with detailed receipt information.
+     *
+     * @param txHash - Transaction hash to query
+     * @param senderAccountId - Account ID that sent the transaction (used to determine shard)
+     * @param waitUntil - Optional execution level to wait for (default: "EXECUTED_OPTIMISTIC")
+     *
+     * @returns Transaction status with receipts, typed based on waitUntil parameter
+     *
+     * @throws {InvalidTransactionError} If transaction execution failed
+     * @throws {NetworkError} If network request failed
+     *
+     * @example
+     * ```typescript
+     * // Get transaction status with default wait level
+     * const status = await near.getTransactionStatus(
+     *   '7AfonAhbK4ZbdBU9VPcQdrTZVZBXE25HmZAMEABs9To1',
+     *   'alice.near'
+     * )
+     *
+     * // Wait for full finality
+     * const finalStatus = await near.getTransactionStatus(
+     *   '7AfonAhbK4ZbdBU9VPcQdrTZVZBXE25HmZAMEABs9To1',
+     *   'alice.near',
+     *   'FINAL'
+     * )
+     *
+     * // Access receipt details
+     * console.log('Receipts:', finalStatus.receipts)
+     * ```
+     *
+     * @see {@link https://docs.near.org/api/rpc/transactions#transaction-status-with-receipts NEAR RPC Documentation}
+     */
+    async getTransactionStatus(txHash, senderAccountId, waitUntil) {
+        return this.rpc.getTransactionStatus(txHash, senderAccountId, waitUntil);
+    }
+    /**
+     * Get basic network status information.
+     *
+     * @returns An object containing `chainId`, `latestBlockHeight`, and `syncing` flag.
+     */
+    async getStatus() {
+        const status = await this.rpc.getStatus();
+        return {
+            chainId: status.chain_id,
+            latestBlockHeight: status.sync_info.latest_block_height,
+            syncing: status.sync_info.syncing,
+        };
+    }
+    /**
+     * Batch multiple read operations.
+     *
+     * @param promises - Promises to execute in parallel.
+     *
+     * @returns A tuple of resolved values preserving the input order.
+     *
+     * @remarks
+     * This is a thin wrapper over `Promise.all` with a tuple-friendly signature.
+     * It does not perform any RPC-level batching.
+     */
+    async batch(...promises) {
+        return Promise.all(promises);
+    }
+    /**
+     * Create a transaction builder for the specified signer account.
+     *
+     * The `signerId` determines which account will sign and send this transaction.
+     * This account must have keys available in the configured keyStore, privateKey,
+     * custom signer, or be connected via wallet.
+     *
+     * @param signerId - The account ID that will sign and pay for this transaction
+     *
+     * @returns A transaction builder for chaining actions
+     *
+     * @example
+     * ```typescript
+     * // Alice sends NEAR to Bob
+     * await near.transaction('alice.near')
+     *   .transfer('bob.near', '10 NEAR')
+     *   .send()
+     *
+     * // Alice calls a contract and creates a new account
+     * await near.transaction('alice.near')
+     *   .functionCall('market.near', 'buy', { id: 123 })
+     *   .createAccount('sub.alice.near')
+     *   .transfer('sub.alice.near', '5 NEAR')
+     *   .send()
+     * ```
+     *
+     * @see {@link TransactionBuilder} for available actions
+     */
+    transaction(signerId) {
+        return new TransactionBuilder(signerId, this.rpc, this.keyStore, this.signer, this.defaultWaitUntil, this.wallet, this.pendingKeyStoreInit ? () => this.ensureKeyStoreReady() : undefined);
+    }
+    /**
+     * Create a type-safe contract interface.
+     *
+     * @param contractId - Account ID of the target contract.
+     *
+     * @returns A proxy implementing your {@link ContractMethods} interface.
+     *
+     * @example
+     * ```typescript
+     * type Counter = Contract<{
+     *   view: { get_count: () => Promise<number> }
+     *   call: { increment: () => Promise<void> }
+     * }>
+     *
+     * const counter = near.contract<Counter>("counter.near")
+     * ```
+     */
+    contract(contractId) {
+        return createContract(this, contractId);
+    }
+}
+//# sourceMappingURL=near.js.map

package/dist/core/near.js.map

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

package/dist/core/nonce-manager.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Manages nonces for concurrent transactions.
+ *
+ * Prevents nonce collisions when sending multiple transactions in parallel
+ * by caching nonces in memory and incrementing them locally.
+ *
+ * @internal Used by {@link TransactionBuilder}; not typically needed directly.
+ */
+export declare class NonceManager {
+    private nonces;
+    private fetching;
+    /**
+     * Get the next nonce for an account and public key
+     *
+     * Fetches from blockchain on first call, then increments locally.
+     * Handles concurrent calls gracefully by deduplicating fetches.
+     *
+     * @param accountId - Account ID to get nonce for
+     * @param publicKey - Public key to get nonce for
+     * @param fetchFromBlockchain - Callback to fetch current nonce from blockchain
+     * @returns Next nonce to use for transaction
+     */
+    getNextNonce(accountId: string, publicKey: string, fetchFromBlockchain: () => Promise<bigint>): Promise<bigint>;
+    /**
+     * Invalidate cached nonce for an account and public key
+     *
+     * Call this when an InvalidNonceError occurs to force a fresh fetch
+     * from the blockchain on the next transaction.
+     *
+     * @param accountId - Account ID to invalidate
+     * @param publicKey - Public key to invalidate
+     */
+    invalidate(accountId: string, publicKey: string): void;
+    /**
+     * Clear all cached nonces
+     */
+    clear(): void;
+}
+//# sourceMappingURL=nonce-manager.d.ts.map

package/dist/core/nonce-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-manager.d.ts","sourceRoot":"","sources":["../../src/core/nonce-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAmC;IAEnD;;;;;;;;;;OAUG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACzC,OAAO,CAAC,MAAM,CAAC;IAkClB;;;;;;;;OAQG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAItD;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/core/nonce-manager.js

@@ -0,0 +1,73 @@
+/**
+ * Manages nonces for concurrent transactions.
+ *
+ * Prevents nonce collisions when sending multiple transactions in parallel
+ * by caching nonces in memory and incrementing them locally.
+ *
+ * @internal Used by {@link TransactionBuilder}; not typically needed directly.
+ */
+export class NonceManager {
+    constructor() {
+        this.nonces = new Map();
+        this.fetching = new Map();
+    }
+    /**
+     * Get the next nonce for an account and public key
+     *
+     * Fetches from blockchain on first call, then increments locally.
+     * Handles concurrent calls gracefully by deduplicating fetches.
+     *
+     * @param accountId - Account ID to get nonce for
+     * @param publicKey - Public key to get nonce for
+     * @param fetchFromBlockchain - Callback to fetch current nonce from blockchain
+     * @returns Next nonce to use for transaction
+     */
+    async getNextNonce(accountId, publicKey, fetchFromBlockchain) {
+        const key = `${accountId}:${publicKey}`;
+        // Wait if another call is already fetching for this key
+        const pendingFetch = this.fetching.get(key);
+        if (pendingFetch) {
+            await pendingFetch;
+        }
+        // Fetch from blockchain if not cached
+        if (!this.nonces.has(key)) {
+            const fetchPromise = fetchFromBlockchain()
+                .then((blockchainNonce) => {
+                this.nonces.set(key, blockchainNonce + 1n);
+                this.fetching.delete(key);
+            })
+                .catch((error) => {
+                this.fetching.delete(key);
+                throw error;
+            });
+            this.fetching.set(key, fetchPromise);
+            await fetchPromise;
+        }
+        // Return current nonce and increment for next call
+        const nonce = this.nonces.get(key);
+        if (nonce === undefined) {
+            throw new Error(`Nonce not found for ${key} after fetch`);
+        }
+        this.nonces.set(key, nonce + 1n);
+        return nonce;
+    }
+    /**
+     * Invalidate cached nonce for an account and public key
+     *
+     * Call this when an InvalidNonceError occurs to force a fresh fetch
+     * from the blockchain on the next transaction.
+     *
+     * @param accountId - Account ID to invalidate
+     * @param publicKey - Public key to invalidate
+     */
+    invalidate(accountId, publicKey) {
+        this.nonces.delete(`${accountId}:${publicKey}`);
+    }
+    /**
+     * Clear all cached nonces
+     */
+    clear() {
+        this.nonces.clear();
+    }
+}
+//# sourceMappingURL=nonce-manager.js.map

package/dist/core/nonce-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce-manager.js","sourceRoot":"","sources":["../../src/core/nonce-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IAAzB;QACU,WAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;QAClC,aAAQ,GAAG,IAAI,GAAG,EAAyB,CAAA;IAsErD,CAAC;IApEC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,YAAY,CAChB,SAAiB,EACjB,SAAiB,EACjB,mBAA0C;QAE1C,MAAM,GAAG,GAAG,GAAG,SAAS,IAAI,SAAS,EAAE,CAAA;QAEvC,wDAAwD;QACxD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3C,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,YAAY,CAAA;QACpB,CAAC;QAED,sCAAsC;QACtC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,mBAAmB,EAAE;iBACvC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;gBACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,GAAG,EAAE,CAAC,CAAA;gBAC1C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YAC3B,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;gBACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACzB,MAAM,KAAK,CAAA;YACb,CAAC,CAAC,CAAA;YAEJ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAA;YACpC,MAAM,YAAY,CAAA;QACpB,CAAC;QAED,mDAAmD;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,cAAc,CAAC,CAAA;QAC3D,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,EAAE,CAAC,CAAA;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,SAAiB,EAAE,SAAiB;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC,CAAA;IACjD,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF"}