@alphafi/alphafi-sdk 0.0.107 → 1.0.1

package/dist/cjs/strategies/strategy.d.ts.map

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

package/dist/cjs/strategies/strategy.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Strategy interfaces and shared helpers used by all strategy implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseStrategy = exports.ALPHA_COIN_TYPE = void 0;
+const decimal_js_1 = require("decimal.js");
+const constants_js_1 = require("../utils/constants.js");
+/**
+ * Struct tag for the ALPHA coin used by the distributor.
+ */
+exports.ALPHA_COIN_TYPE = 'fe3afec26c59e874f3c1d60b8203cb3852d2bb2aa415df9548b8d688e6683f93::alpha::ALPHA';
+/**
+ * Base class shared by all strategies.
+ * Provides parsing helpers and common reward calculation logic.
+ */
+class BaseStrategy {
+    createAlphaFiReceipt(tx) {
+        return tx.moveCall({
+            target: `${constants_js_1.PACKAGE_IDS.ALPHAFI_RECEIPT}::alphafi_receipt::create_alphafi_receipt_v2`,
+            arguments: [tx.pure.string(constants_js_1.IMAGE_URLS.ALPHAFI_RECEIPT)],
+        });
+    }
+    /**
+     * Compute claimable ALPHA rewards using the distributor + pool/receipt accounting.
+     * Returns a human-readable amount (divided by 1e9).
+     */
+    getAlphaMiningRewardsToClaim(distributor) {
+        const data = this.getAlphaMiningData();
+        // No receipt -> no position -> no alpha rewards.
+        if (!data.receipt) {
+            return new decimal_js_1.Decimal(0);
+        }
+        const { poolId, accRewardsPerXtoken, xTokenSupply, receipt } = data;
+        const { lastAccRewardPerXtoken, pendingRewards, xTokenBalance } = receipt;
+        // Get user's last accumulated reward per xtoken for ALPHA
+        const userLastAccEntry = lastAccRewardPerXtoken.find((entry) => entry.key === exports.ALPHA_COIN_TYPE);
+        const userLastAcc = new decimal_js_1.Decimal(userLastAccEntry?.value || '0');
+        // Get user's xtoken balance
+        const userXtokenBalance = new decimal_js_1.Decimal(xTokenBalance || '0');
+        // Get pending alpha rewards from receipt
+        const pendingAlphaRewards = pendingRewards
+            .filter((entry) => entry.key === exports.ALPHA_COIN_TYPE)
+            .reduce((acc, entry) => acc.add(new decimal_js_1.Decimal(entry.value || '0')), new decimal_js_1.Decimal(0));
+        // Get total alpha weight across all pools from distributor
+        const alphaRewardTotalWeight = distributor.poolAllocator.totalWeights.find((w) => w.key === exports.ALPHA_COIN_TYPE)?.value || '0';
+        // Get distribution status for this pool
+        const memberEntry = distributor.poolAllocator.members.find((m) => m.key === poolId);
+        const alphaAllocatorDetailsForPool = memberEntry?.value.poolData.find((pd) => pd.key === exports.ALPHA_COIN_TYPE)?.value;
+        // Calculate pending rewards for pool
+        let pendingRewardsForPool = new decimal_js_1.Decimal(0);
+        if (alphaAllocatorDetailsForPool) {
+            const currentTime = Date.now();
+            const pendingRewardsInAllocator = new decimal_js_1.Decimal(alphaAllocatorDetailsForPool.pendingRewards || '0');
+            const lastUpdateTime = parseInt(alphaAllocatorDetailsForPool.lastUpdateTime || '0', 10);
+            const weight = new decimal_js_1.Decimal(alphaAllocatorDetailsForPool.weight || '0');
+            const totalWeight = new decimal_js_1.Decimal(alphaRewardTotalWeight);
+            const target = new decimal_js_1.Decimal(distributor.target || '0');
+            // Calculate unlockPerMS (target per millisecond)
+            // unlock_per_ms = target * 2750000 / (4250000 * 100 * 86400000)
+            const unlockPerMs = target
+                .mul(new decimal_js_1.Decimal('2750000'))
+                .div(new decimal_js_1.Decimal('4250000').mul('100').mul('86400000'));
+            // Calculate time diff
+            const timeDiff = Math.max(0, currentTime - lastUpdateTime);
+            // Calculate additional rewards
+            let additionalRewards = new decimal_js_1.Decimal(0);
+            if (totalWeight.gt(0)) {
+                additionalRewards = new decimal_js_1.Decimal(timeDiff).mul(unlockPerMs).mul(weight).div(totalWeight);
+            }
+            pendingRewardsForPool = pendingRewardsInAllocator.add(additionalRewards);
+        }
+        // Get pool's accumulated rewards per xtoken for ALPHA
+        const alphaOldAccEntry = accRewardsPerXtoken.find((entry) => entry.key === exports.ALPHA_COIN_TYPE);
+        const alphaOldAccInPool = new decimal_js_1.Decimal(alphaOldAccEntry?.value || '0');
+        // Get total xtoken supply from pool
+        const totalXtokenSupply = new decimal_js_1.Decimal(xTokenSupply || '0');
+        // Calculate new accumulated rewards per xtoken
+        const SCALE = new decimal_js_1.Decimal('1000000000000000000'); // 1e18
+        let addAcc = new decimal_js_1.Decimal(0);
+        if (totalXtokenSupply.gt(0)) {
+            addAcc = pendingRewardsForPool.div(totalXtokenSupply).mul(SCALE).mul(SCALE);
+        }
+        const alphaNewAccInPool = alphaOldAccInPool.add(addAcc);
+        // Calculate user's accrued rewards
+        // user_accrued_rewards = ((acc_new - acc_last) / SCALE^2) * user_balance
+        const deltaAcc = alphaNewAccInPool.sub(userLastAcc);
+        const userAccruedRewards = deltaAcc.div(SCALE.mul(SCALE)).mul(userXtokenBalance);
+        // Combine pending rewards and accrued rewards, then divide by 1e9 for human-readable amount
+        const totalPendingRewards = pendingAlphaRewards.add(userAccruedRewards).div(new decimal_js_1.Decimal(1e9));
+        return totalPendingRewards;
+    }
+    // ===== Parsing Helper Methods =====
+    /**
+     * Helper function to get string field from JSON with validation
+     */
+    getStringField(fieldsJson, fieldName) {
+        const value = fieldsJson?.[fieldName];
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (value !== undefined && value !== null) {
+            return String(value);
+        }
+        return '';
+    }
+    /**
+     * Helper function to get boolean field from JSON with default value
+     */
+    getBooleanField(fieldsJson, fieldName, defaultValue) {
+        const value = fieldsJson?.[fieldName];
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        return defaultValue;
+    }
+    /**
+     * Helper function to get number field from JSON
+     */
+    getNumberField(fieldsJson, fieldName) {
+        const value = fieldsJson?.[fieldName];
+        if (typeof value === 'number') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const parsed = parseInt(value, 10);
+            return isNaN(parsed) ? 0 : parsed;
+        }
+        return 0;
+    }
+    /**
+     * Helper function to parse VecMap structures from Move objects into StringMap format
+     */
+    parseVecMap(vecMapField) {
+        if (!vecMapField || typeof vecMapField !== 'object') {
+            return [];
+        }
+        const contents = vecMapField.contents;
+        if (!Array.isArray(contents)) {
+            return [];
+        }
+        return contents.map((entry) => {
+            const key = entry?.key?.name;
+            const value = entry?.value;
+            return { key, value };
+        });
+    }
+    /**
+     * Helper function to convert ASCII array from JSON to string
+     */
+    asciiToString(asciiArray) {
+        if (Array.isArray(asciiArray)) {
+            try {
+                const bytes = asciiArray.map((n) => {
+                    const num = typeof n === 'number' ? n : parseInt(n);
+                    if (num < 0 || num > 255) {
+                        throw new Error('ASCII value out of range');
+                    }
+                    return num;
+                });
+                return String.fromCharCode(...bytes);
+            }
+            catch (error) {
+                console.error('Error converting ASCII array to string:', error);
+                return '';
+            }
+        }
+        return '';
+    }
+    /**
+     * Helper function to extract fields from various response formats
+     */
+    extractFields(response) {
+        return response.fields || response.content?.fields || response;
+    }
+    /**
+     * Helper function to safely parse nested object fields
+     */
+    getNestedField(obj, path) {
+        return path.split('.').reduce((current, key) => current?.[key], obj);
+    }
+    /**
+     * Helper function to parse object with error handling
+     */
+    safeParseObject(parseFunction, errorMessage) {
+        try {
+            return parseFunction();
+        }
+        catch (error) {
+            console.error(`${errorMessage}:`, error);
+            throw new Error(`${errorMessage}: ${error}`);
+        }
+    }
+}
+exports.BaseStrategy = BaseStrategy;
+//# sourceMappingURL=strategy.js.map

package/dist/cjs/strategies/strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../src/strategies/strategy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Strategy interfaces and shared helpers used by all strategy implementations.\n */\n\nimport { Decimal } from 'decimal.js';\nimport { SingleTvl, DoubleTvl, PoolData, PoolBalance, DistributorObject } from '../models/types.js';\nimport { Transaction, TransactionResult } from '@mysten/sui/transactions';\nimport { DepositOptions, WithdrawOptions } from '../core/types.js';\nimport { IMAGE_URLS, PACKAGE_IDS } from '../utils/constants.js';\n\nexport interface StringMap {\n  [key: string]: string;\n}\n\n/**\n * Minimal data needed to compute ALPHA mining rewards for a user.\n *\n * Strategies that don't participate in alpha mining should return `receipt: null`.\n */\nexport interface AlphaMiningData {\n  poolId: string;\n  accRewardsPerXtoken: StringMap[];\n  xTokenSupply: string;\n  receipt: {\n    lastAccRewardPerXtoken: StringMap[];\n    pendingRewards: StringMap[];\n    xTokenBalance: string;\n  } | null;\n}\n\n/**\n * Struct tag for the ALPHA coin used by the distributor.\n */\nexport const ALPHA_COIN_TYPE =\n  'fe3afec26c59e874f3c1d60b8203cb3852d2bb2aa415df9548b8d688e6683f93::alpha::ALPHA';\n\n// ===== Common Pool Label Types =====\n\nexport type StrategyType =\n  | 'AlphaVault'\n  | 'Lp'\n  | 'FungibleLp'\n  | 'AutobalanceLp'\n  | 'Lending'\n  | 'SlushLending'\n  | 'Looping'\n  | 'SingleAssetLooping'\n  | 'Lyf'\n  | 'FungibleLending';\n\nexport type ProtocolType =\n  | 'AlphaFi'\n  | 'Navi'\n  | 'Alphalend'\n  | 'Cetus'\n  | 'Bluefin'\n  | 'Bucket'\n  | 'DeepBook';\n\n// Forward declarations for pool label types (will be imported from individual strategy files)\nexport type LpPoolLabel = import('./lp.js').LpPoolLabel;\nexport type AlphaVaultPoolLabel = import('./alphaVault.js').AlphaVaultPoolLabel;\nexport type AutobalanceLpPoolLabel = import('./autobalanceLp.js').AutobalanceLpPoolLabel;\nexport type FungibleLpPoolLabel = import('./fungibleLp.js').FungibleLpPoolLabel;\nexport type LendingPoolLabel = import('./lending.js').LendingPoolLabel;\nexport type SlushLendingPoolLabel = import('./slushLending.js').SlushLendingPoolLabel;\nexport type LoopingPoolLabel = import('./looping.js').LoopingPoolLabel;\nexport type SingleAssetLoopingPoolLabel =\n  import('./singleAssetLooping.js').SingleAssetLoopingPoolLabel;\nexport type LyfPoolLabel = import('./lyf.js').LyfPoolLabel;\nexport type FungibleLendingPoolLabel = import('./fungibleLending.js').FungibleLendingPoolLabel;\n\n/**\n * Union of all strategy-specific pool label types.\n */\nexport type PoolLabel =\n  | LpPoolLabel\n  | AlphaVaultPoolLabel\n  | AutobalanceLpPoolLabel\n  | FungibleLpPoolLabel\n  | LendingPoolLabel\n  | SlushLendingPoolLabel\n  | LoopingPoolLabel\n  | SingleAssetLoopingPoolLabel\n  | LyfPoolLabel\n  | FungibleLendingPoolLabel;\n\n/**\n * Common strategy surface used by the SDK.\n */\nexport interface Strategy<TPool = any, TInvestor = any, TParentPool = any, TReceipt = any> {\n  /**\n   * Parse a pool object fetched from chain into a typed shape.\n   */\n  parsePoolObject(response: any): TPool;\n\n  /**\n   * Parse an investor object fetched from chain into a typed shape.\n   */\n  parseInvestorObject(response: any): TInvestor;\n\n  /**\n   * Parse a parent pool object (underlying protocol) fetched from chain.\n   */\n  parseParentPoolObject(response: any): TParentPool;\n\n  /**\n   * Parse receipt objects fetched from chain.\n   */\n  parseReceiptObjects(responses: any[]): TReceipt[];\n\n  /**\n   * Current exchange rate used by the strategy.\n   * Typically: `tokens_invested / xToken_supply`.\n   */\n  exchangeRate(): Decimal;\n\n  /**\n   * TVL for the AlphaFi pool and the underlying parent protocol (if any).\n   */\n  getTvl(): Promise<SingleTvl | DoubleTvl>;\n  getParentTvl(): Promise<SingleTvl | DoubleTvl>;\n\n  /**\n   * User balance breakdown for this pool.\n   */\n  getBalance(userAddress: string): Promise<PoolBalance>;\n\n  /**\n   * Static metadata/config for this pool (from config API).\n   */\n  getPoolLabel(): PoolLabel;\n\n  /**\n   * High-level pool summary (APR + TVL + strategy-specific metadata).\n   */\n  getData(): Promise<PoolData>;\n\n  /**\n   * Compute ALPHA mining rewards claimable for this pool.\n   *\n   * Note: this uses the cached distributor object from `StrategyContext`.\n   */\n  getAlphaMiningRewardsToClaim(distributor: DistributorObject): Decimal;\n\n  /**\n   * Get the other amount for a given amount and isAmountA flag.\n   *\n   * @param amount - The amount to get the other amount for\n   * @param isAmountA - Whether the amount is amount A\n   * @returns The other amount\n   */\n  getOtherAmount(amount: string, isAmountA: boolean): [string, string];\n\n  /**\n   * Deposit assets into the pool.\n   *\n   * @param options - The options for the deposit\n   * @returns Transaction to deposit assets into the pool\n   */\n  deposit(tx: Transaction, options: DepositOptions): Promise<void>;\n\n  /**\n   * Withdraw assets from the pool.\n   *\n   * @param options - The options for the withdrawal\n   * @returns Transaction to withdraw assets from the pool\n   */\n  withdraw(tx: Transaction, options: WithdrawOptions): Promise<void>;\n\n  /**\n   * Claim rewards for a specific pool.\n   *\n   * @param poolId - The ID of the pool to claim rewards for\n   * @param address - The address of the user to claim rewards for\n   * @returns Transaction to claim rewards for the specified pool\n   */\n  claimRewards(tx: Transaction, alphaReceipt: TransactionResult): Promise<void>;\n\n  /**\n   * Create an AlphaFi receipt.\n   *\n   * @param tx - The transaction to create the AlphaFi receipt\n   * @returns Transaction to create the AlphaFi receipt\n   */\n  createAlphaFiReceipt(tx: Transaction): TransactionResult;\n}\n\n/**\n * Base class shared by all strategies.\n * Provides parsing helpers and common reward calculation logic.\n */\nexport abstract class BaseStrategy<TPool = any, TInvestor = any, TParentPool = any, TReceipt = any>\n  implements Strategy<TPool, TInvestor, TParentPool, TReceipt>\n{\n  abstract parsePoolObject(response: any): TPool;\n  abstract parseInvestorObject(response: any): TInvestor;\n  abstract parseParentPoolObject(response: any): TParentPool;\n  abstract parseReceiptObjects(responses: any[]): TReceipt[];\n  abstract exchangeRate(): Decimal;\n  abstract getTvl(): Promise<SingleTvl | DoubleTvl>;\n  abstract getParentTvl(): Promise<SingleTvl | DoubleTvl>;\n  abstract getData(): Promise<PoolData>;\n  abstract getBalance(userAddress: string): Promise<PoolBalance>;\n  abstract getPoolLabel(): PoolLabel;\n  abstract getOtherAmount(amount: string, isAmountA: boolean): [string, string];\n  abstract deposit(tx: Transaction, options: DepositOptions): Promise<void>;\n  abstract withdraw(tx: Transaction, options: WithdrawOptions): Promise<void>;\n  abstract claimRewards(tx: Transaction, alphaReceipt: TransactionResult): Promise<void>;\n\n  createAlphaFiReceipt(tx: Transaction) {\n    return tx.moveCall({\n      target: `${PACKAGE_IDS.ALPHAFI_RECEIPT}::alphafi_receipt::create_alphafi_receipt_v2`,\n      arguments: [tx.pure.string(IMAGE_URLS.ALPHAFI_RECEIPT)],\n    });\n  }\n\n  /**\n   * Provide the inputs needed to compute ALPHA mining rewards for this strategy.\n   * Return `receipt: null` if the strategy/user has no alpha mining position.\n   */\n  protected abstract getAlphaMiningData(): AlphaMiningData;\n\n  /**\n   * Compute claimable ALPHA rewards using the distributor + pool/receipt accounting.\n   * Returns a human-readable amount (divided by 1e9).\n   */\n  getAlphaMiningRewardsToClaim(distributor: DistributorObject): Decimal {\n    const data = this.getAlphaMiningData();\n\n    // No receipt -> no position -> no alpha rewards.\n    if (!data.receipt) {\n      return new Decimal(0);\n    }\n\n    const { poolId, accRewardsPerXtoken, xTokenSupply, receipt } = data;\n    const { lastAccRewardPerXtoken, pendingRewards, xTokenBalance } = receipt;\n\n    // Get user's last accumulated reward per xtoken for ALPHA\n    const userLastAccEntry = lastAccRewardPerXtoken.find((entry) => entry.key === ALPHA_COIN_TYPE);\n    const userLastAcc = new Decimal(userLastAccEntry?.value || '0');\n\n    // Get user's xtoken balance\n    const userXtokenBalance = new Decimal(xTokenBalance || '0');\n\n    // Get pending alpha rewards from receipt\n    const pendingAlphaRewards = pendingRewards\n      .filter((entry) => entry.key === ALPHA_COIN_TYPE)\n      .reduce((acc, entry) => acc.add(new Decimal(entry.value || '0')), new Decimal(0));\n\n    // Get total alpha weight across all pools from distributor\n    const alphaRewardTotalWeight =\n      distributor.poolAllocator.totalWeights.find((w) => w.key === ALPHA_COIN_TYPE)?.value || '0';\n\n    // Get distribution status for this pool\n    const memberEntry = distributor.poolAllocator.members.find((m) => m.key === poolId);\n    const alphaAllocatorDetailsForPool = memberEntry?.value.poolData.find(\n      (pd) => pd.key === ALPHA_COIN_TYPE,\n    )?.value;\n\n    // Calculate pending rewards for pool\n    let pendingRewardsForPool = new Decimal(0);\n    if (alphaAllocatorDetailsForPool) {\n      const currentTime = Date.now();\n      const pendingRewardsInAllocator = new Decimal(\n        alphaAllocatorDetailsForPool.pendingRewards || '0',\n      );\n      const lastUpdateTime = parseInt(alphaAllocatorDetailsForPool.lastUpdateTime || '0', 10);\n      const weight = new Decimal(alphaAllocatorDetailsForPool.weight || '0');\n      const totalWeight = new Decimal(alphaRewardTotalWeight);\n      const target = new Decimal(distributor.target || '0');\n\n      // Calculate unlockPerMS (target per millisecond)\n      // unlock_per_ms = target * 2750000 / (4250000 * 100 * 86400000)\n      const unlockPerMs = target\n        .mul(new Decimal('2750000'))\n        .div(new Decimal('4250000').mul('100').mul('86400000'));\n\n      // Calculate time diff\n      const timeDiff = Math.max(0, currentTime - lastUpdateTime);\n\n      // Calculate additional rewards\n      let additionalRewards = new Decimal(0);\n      if (totalWeight.gt(0)) {\n        additionalRewards = new Decimal(timeDiff).mul(unlockPerMs).mul(weight).div(totalWeight);\n      }\n\n      pendingRewardsForPool = pendingRewardsInAllocator.add(additionalRewards);\n    }\n\n    // Get pool's accumulated rewards per xtoken for ALPHA\n    const alphaOldAccEntry = accRewardsPerXtoken.find((entry) => entry.key === ALPHA_COIN_TYPE);\n    const alphaOldAccInPool = new Decimal(alphaOldAccEntry?.value || '0');\n\n    // Get total xtoken supply from pool\n    const totalXtokenSupply = new Decimal(xTokenSupply || '0');\n\n    // Calculate new accumulated rewards per xtoken\n    const SCALE = new Decimal('1000000000000000000'); // 1e18\n    let addAcc = new Decimal(0);\n    if (totalXtokenSupply.gt(0)) {\n      addAcc = pendingRewardsForPool.div(totalXtokenSupply).mul(SCALE).mul(SCALE);\n    }\n    const alphaNewAccInPool = alphaOldAccInPool.add(addAcc);\n\n    // Calculate user's accrued rewards\n    // user_accrued_rewards = ((acc_new - acc_last) / SCALE^2) * user_balance\n    const deltaAcc = alphaNewAccInPool.sub(userLastAcc);\n    const userAccruedRewards = deltaAcc.div(SCALE.mul(SCALE)).mul(userXtokenBalance);\n\n    // Combine pending rewards and accrued rewards, then divide by 1e9 for human-readable amount\n    const totalPendingRewards = pendingAlphaRewards.add(userAccruedRewards).div(new Decimal(1e9));\n\n    return totalPendingRewards;\n  }\n\n  // ===== Parsing Helper Methods =====\n\n  /**\n   * Helper function to get string field from JSON with validation\n   */\n  protected getStringField(fieldsJson: any, fieldName: string): string {\n    const value = fieldsJson?.[fieldName];\n    if (typeof value === 'string') {\n      return value;\n    }\n    if (value !== undefined && value !== null) {\n      return String(value);\n    }\n    return '';\n  }\n\n  /**\n   * Helper function to get boolean field from JSON with default value\n   */\n  protected getBooleanField(fieldsJson: any, fieldName: string, defaultValue: boolean): boolean {\n    const value = fieldsJson?.[fieldName];\n    if (typeof value === 'boolean') {\n      return value;\n    }\n    return defaultValue;\n  }\n\n  /**\n   * Helper function to get number field from JSON\n   */\n  protected getNumberField(fieldsJson: any, fieldName: string): number {\n    const value = fieldsJson?.[fieldName];\n    if (typeof value === 'number') {\n      return value;\n    }\n    if (typeof value === 'string') {\n      const parsed = parseInt(value, 10);\n      return isNaN(parsed) ? 0 : parsed;\n    }\n    return 0;\n  }\n\n  /**\n   * Helper function to parse VecMap structures from Move objects into StringMap format\n   */\n  protected parseVecMap(vecMapField: any) {\n    if (!vecMapField || typeof vecMapField !== 'object') {\n      return [];\n    }\n\n    const contents = vecMapField.contents;\n    if (!Array.isArray(contents)) {\n      return [];\n    }\n\n    return contents.map((entry: any) => {\n      const key = entry?.key?.name;\n      const value = entry?.value;\n      return { key, value };\n    });\n  }\n\n  /**\n   * Helper function to convert ASCII array from JSON to string\n   */\n  protected asciiToString(asciiArray: any): string {\n    if (Array.isArray(asciiArray)) {\n      try {\n        const bytes = asciiArray.map((n: any) => {\n          const num = typeof n === 'number' ? n : parseInt(n);\n          if (num < 0 || num > 255) {\n            throw new Error('ASCII value out of range');\n          }\n          return num;\n        });\n        return String.fromCharCode(...bytes);\n      } catch (error) {\n        console.error('Error converting ASCII array to string:', error);\n        return '';\n      }\n    }\n    return '';\n  }\n\n  /**\n   * Helper function to extract fields from various response formats\n   */\n  protected extractFields(response: any): any {\n    return response.fields || response.content?.fields || response;\n  }\n\n  /**\n   * Helper function to safely parse nested object fields\n   */\n  protected getNestedField(obj: any, path: string): any {\n    return path.split('.').reduce((current, key) => current?.[key], obj);\n  }\n\n  /**\n   * Helper function to parse object with error handling\n   */\n  protected safeParseObject<T>(parseFunction: () => T, errorMessage: string): T {\n    try {\n      return parseFunction();\n    } catch (error) {\n      console.error(`${errorMessage}:`, error);\n      throw new Error(`${errorMessage}: ${error}`);\n    }\n  }\n}\n"]}

package/dist/cjs/utils/cache.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Generic time-based cache with promise memoization.
+ * Prevents duplicate concurrent fetches and auto-expires entries.
+ */
+/**
+ * A generic cache that stores values with TTL (time-to-live).
+ * Supports promise memoization to prevent duplicate concurrent fetches.
+ *
+ * @example
+ * ```typescript
+ * const cache = new Cache<string, UserData>(60000); // 60 second TTL
+ *
+ * // Fetch with automatic caching and deduplication
+ * const data = await cache.getOrFetch('user-123', async () => {
+ *   return await fetchUserFromAPI('user-123');
+ * });
+ * ```
+ */
+export declare class Cache<K, V> {
+    private cache;
+    private pendingPromises;
+    private defaultTtl;
+    /**
+     * Create a new cache instance.
+     * @param defaultTtlMs - Default time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTtlMs?: number);
+    /**
+     * Get a value from cache if it exists and hasn't expired.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Set a value in the cache with optional custom TTL.
+     */
+    set(key: K, value: V, ttlMs?: number): void;
+    /**
+     * Check if a key exists and hasn't expired.
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a specific key from cache.
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get value from cache or fetch it using the provided function.
+     * Handles promise memoization to prevent duplicate concurrent fetches.
+     *
+     * @param key - Cache key
+     * @param fetcher - Async function to fetch the value if not cached
+     * @param ttlMs - Optional custom TTL for this entry
+     */
+    getOrFetch(key: K, fetcher: () => Promise<V>, ttlMs?: number): Promise<V>;
+    /**
+     * Get the number of cached entries (including potentially expired ones).
+     */
+    get size(): number;
+    /**
+     * Remove all expired entries from cache.
+     */
+    prune(): void;
+}
+/**
+ * A singleton cache for a single value (useful for global data like config).
+ * Supports promise memoization and TTL.
+ */
+export declare class SingletonCache<V> {
+    private value;
+    private expiresAt;
+    private pendingPromise;
+    private defaultTtl;
+    constructor(defaultTtlMs?: number);
+    /**
+     * Get the cached value if it exists and hasn't expired.
+     */
+    get(): V | undefined;
+    /**
+     * Set the cached value with optional custom TTL.
+     */
+    set(value: V, ttlMs?: number): void;
+    /**
+     * Check if value exists and hasn't expired.
+     */
+    has(): boolean;
+    /**
+     * Clear the cached value.
+     */
+    clear(): void;
+    /**
+     * Get value from cache or fetch it using the provided function.
+     * Handles promise memoization to prevent duplicate concurrent fetches.
+     */
+    getOrFetch(fetcher: () => Promise<V>, ttlMs?: number): Promise<V>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cjs/utils/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK,CAAC,CAAC,EAAE,CAAC;IACrB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,UAAU,CAAS;IAE3B;;;OAGG;gBACS,YAAY,GAAE,MAA0B;IAIpD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAY1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ3C;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAKvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;OAOG;IACG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA6B/E;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAQd;AAED;;;GAGG;AACH,qBAAa,cAAc,CAAC,CAAC;IAC3B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,cAAc,CAA2B;IACjD,OAAO,CAAC,UAAU,CAAS;gBAEf,YAAY,GAAE,MAA0B;IAIpD;;OAEG;IACH,GAAG,IAAI,CAAC,GAAG,SAAS;IASpB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAMnC;;OAEG;IACH,GAAG,IAAI,OAAO;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CA0BxE"}

package/dist/cjs/utils/cache.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Generic time-based cache with promise memoization.
+ * Prevents duplicate concurrent fetches and auto-expires entries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SingletonCache = exports.Cache = void 0;
+const constants_js_1 = require("./constants.js");
+/**
+ * A generic cache that stores values with TTL (time-to-live).
+ * Supports promise memoization to prevent duplicate concurrent fetches.
+ *
+ * @example
+ * ```typescript
+ * const cache = new Cache<string, UserData>(60000); // 60 second TTL
+ *
+ * // Fetch with automatic caching and deduplication
+ * const data = await cache.getOrFetch('user-123', async () => {
+ *   return await fetchUserFromAPI('user-123');
+ * });
+ * ```
+ */
+class Cache {
+    cache = new Map();
+    pendingPromises = new Map();
+    defaultTtl;
+    /**
+     * Create a new cache instance.
+     * @param defaultTtlMs - Default time-to-live in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTtlMs = constants_js_1.CACHE_TTL.DEFAULT) {
+        this.defaultTtl = defaultTtlMs;
+    }
+    /**
+     * Get a value from cache if it exists and hasn't expired.
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache with optional custom TTL.
+     */
+    set(key, value, ttlMs) {
+        const ttl = ttlMs ?? this.defaultTtl;
+        this.cache.set(key, {
+            value,
+            expiresAt: Date.now() + ttl,
+        });
+    }
+    /**
+     * Check if a key exists and hasn't expired.
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Delete a specific key from cache.
+     */
+    delete(key) {
+        this.pendingPromises.delete(key);
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cached entries.
+     */
+    clear() {
+        this.cache.clear();
+        this.pendingPromises.clear();
+    }
+    /**
+     * Get value from cache or fetch it using the provided function.
+     * Handles promise memoization to prevent duplicate concurrent fetches.
+     *
+     * @param key - Cache key
+     * @param fetcher - Async function to fetch the value if not cached
+     * @param ttlMs - Optional custom TTL for this entry
+     */
+    async getOrFetch(key, fetcher, ttlMs) {
+        // Return cached value if available
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Return pending promise if fetch is already in progress
+        const pending = this.pendingPromises.get(key);
+        if (pending) {
+            return pending;
+        }
+        // Create new fetch promise
+        const fetchPromise = fetcher()
+            .then((value) => {
+            this.set(key, value, ttlMs);
+            this.pendingPromises.delete(key);
+            return value;
+        })
+            .catch((error) => {
+            this.pendingPromises.delete(key);
+            throw error;
+        });
+        this.pendingPromises.set(key, fetchPromise);
+        return fetchPromise;
+    }
+    /**
+     * Get the number of cached entries (including potentially expired ones).
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Remove all expired entries from cache.
+     */
+    prune() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
+exports.Cache = Cache;
+/**
+ * A singleton cache for a single value (useful for global data like config).
+ * Supports promise memoization and TTL.
+ */
+class SingletonCache {
+    value;
+    expiresAt = 0;
+    pendingPromise = null;
+    defaultTtl;
+    constructor(defaultTtlMs = constants_js_1.CACHE_TTL.DEFAULT) {
+        this.defaultTtl = defaultTtlMs;
+    }
+    /**
+     * Get the cached value if it exists and hasn't expired.
+     */
+    get() {
+        if (this.value === undefined)
+            return undefined;
+        if (Date.now() > this.expiresAt) {
+            this.value = undefined;
+            return undefined;
+        }
+        return this.value;
+    }
+    /**
+     * Set the cached value with optional custom TTL.
+     */
+    set(value, ttlMs) {
+        const ttl = ttlMs ?? this.defaultTtl;
+        this.value = value;
+        this.expiresAt = Date.now() + ttl;
+    }
+    /**
+     * Check if value exists and hasn't expired.
+     */
+    has() {
+        return this.get() !== undefined;
+    }
+    /**
+     * Clear the cached value.
+     */
+    clear() {
+        this.value = undefined;
+        this.pendingPromise = null;
+    }
+    /**
+     * Get value from cache or fetch it using the provided function.
+     * Handles promise memoization to prevent duplicate concurrent fetches.
+     */
+    async getOrFetch(fetcher, ttlMs) {
+        // Return cached value if available
+        const cached = this.get();
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Return pending promise if fetch is already in progress
+        if (this.pendingPromise) {
+            return this.pendingPromise;
+        }
+        // Create new fetch promise
+        this.pendingPromise = fetcher()
+            .then((value) => {
+            this.set(value, ttlMs);
+            this.pendingPromise = null;
+            return value;
+        })
+            .catch((error) => {
+            this.pendingPromise = null;
+            throw error;
+        });
+        return this.pendingPromise;
+    }
+}
+exports.SingletonCache = SingletonCache;
+//# sourceMappingURL=cache.js.map

package/dist/cjs/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/utils/cache.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Generic time-based cache with promise memoization.\n * Prevents duplicate concurrent fetches and auto-expires entries.\n */\n\nimport { CACHE_TTL } from './constants.js';\n\ninterface CacheEntry<T> {\n  value: T;\n  expiresAt: number;\n}\n\n/**\n * A generic cache that stores values with TTL (time-to-live).\n * Supports promise memoization to prevent duplicate concurrent fetches.\n *\n * @example\n * ```typescript\n * const cache = new Cache<string, UserData>(60000); // 60 second TTL\n *\n * // Fetch with automatic caching and deduplication\n * const data = await cache.getOrFetch('user-123', async () => {\n *   return await fetchUserFromAPI('user-123');\n * });\n * ```\n */\nexport class Cache<K, V> {\n  private cache: Map<K, CacheEntry<V>> = new Map();\n  private pendingPromises: Map<K, Promise<V>> = new Map();\n  private defaultTtl: number;\n\n  /**\n   * Create a new cache instance.\n   * @param defaultTtlMs - Default time-to-live in milliseconds (default: 5 minutes)\n   */\n  constructor(defaultTtlMs: number = CACHE_TTL.DEFAULT) {\n    this.defaultTtl = defaultTtlMs;\n  }\n\n  /**\n   * Get a value from cache if it exists and hasn't expired.\n   */\n  get(key: K): V | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) return undefined;\n\n    if (Date.now() > entry.expiresAt) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    return entry.value;\n  }\n\n  /**\n   * Set a value in the cache with optional custom TTL.\n   */\n  set(key: K, value: V, ttlMs?: number): void {\n    const ttl = ttlMs ?? this.defaultTtl;\n    this.cache.set(key, {\n      value,\n      expiresAt: Date.now() + ttl,\n    });\n  }\n\n  /**\n   * Check if a key exists and hasn't expired.\n   */\n  has(key: K): boolean {\n    return this.get(key) !== undefined;\n  }\n\n  /**\n   * Delete a specific key from cache.\n   */\n  delete(key: K): boolean {\n    this.pendingPromises.delete(key);\n    return this.cache.delete(key);\n  }\n\n  /**\n   * Clear all cached entries.\n   */\n  clear(): void {\n    this.cache.clear();\n    this.pendingPromises.clear();\n  }\n\n  /**\n   * Get value from cache or fetch it using the provided function.\n   * Handles promise memoization to prevent duplicate concurrent fetches.\n   *\n   * @param key - Cache key\n   * @param fetcher - Async function to fetch the value if not cached\n   * @param ttlMs - Optional custom TTL for this entry\n   */\n  async getOrFetch(key: K, fetcher: () => Promise<V>, ttlMs?: number): Promise<V> {\n    // Return cached value if available\n    const cached = this.get(key);\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    // Return pending promise if fetch is already in progress\n    const pending = this.pendingPromises.get(key);\n    if (pending) {\n      return pending;\n    }\n\n    // Create new fetch promise\n    const fetchPromise = fetcher()\n      .then((value) => {\n        this.set(key, value, ttlMs);\n        this.pendingPromises.delete(key);\n        return value;\n      })\n      .catch((error) => {\n        this.pendingPromises.delete(key);\n        throw error;\n      });\n\n    this.pendingPromises.set(key, fetchPromise);\n    return fetchPromise;\n  }\n\n  /**\n   * Get the number of cached entries (including potentially expired ones).\n   */\n  get size(): number {\n    return this.cache.size;\n  }\n\n  /**\n   * Remove all expired entries from cache.\n   */\n  prune(): void {\n    const now = Date.now();\n    for (const [key, entry] of this.cache.entries()) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n      }\n    }\n  }\n}\n\n/**\n * A singleton cache for a single value (useful for global data like config).\n * Supports promise memoization and TTL.\n */\nexport class SingletonCache<V> {\n  private value: V | undefined;\n  private expiresAt: number = 0;\n  private pendingPromise: Promise<V> | null = null;\n  private defaultTtl: number;\n\n  constructor(defaultTtlMs: number = CACHE_TTL.DEFAULT) {\n    this.defaultTtl = defaultTtlMs;\n  }\n\n  /**\n   * Get the cached value if it exists and hasn't expired.\n   */\n  get(): V | undefined {\n    if (this.value === undefined) return undefined;\n    if (Date.now() > this.expiresAt) {\n      this.value = undefined;\n      return undefined;\n    }\n    return this.value;\n  }\n\n  /**\n   * Set the cached value with optional custom TTL.\n   */\n  set(value: V, ttlMs?: number): void {\n    const ttl = ttlMs ?? this.defaultTtl;\n    this.value = value;\n    this.expiresAt = Date.now() + ttl;\n  }\n\n  /**\n   * Check if value exists and hasn't expired.\n   */\n  has(): boolean {\n    return this.get() !== undefined;\n  }\n\n  /**\n   * Clear the cached value.\n   */\n  clear(): void {\n    this.value = undefined;\n    this.pendingPromise = null;\n  }\n\n  /**\n   * Get value from cache or fetch it using the provided function.\n   * Handles promise memoization to prevent duplicate concurrent fetches.\n   */\n  async getOrFetch(fetcher: () => Promise<V>, ttlMs?: number): Promise<V> {\n    // Return cached value if available\n    const cached = this.get();\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    // Return pending promise if fetch is already in progress\n    if (this.pendingPromise) {\n      return this.pendingPromise;\n    }\n\n    // Create new fetch promise\n    this.pendingPromise = fetcher()\n      .then((value) => {\n        this.set(value, ttlMs);\n        this.pendingPromise = null;\n        return value;\n      })\n      .catch((error) => {\n        this.pendingPromise = null;\n        throw error;\n      });\n\n    return this.pendingPromise;\n  }\n}\n"]}