@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/index.js

@@ -16,6 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VAULT_ADDRESSES = void 0;
 require("./polyfills");
+/**
+ * Export other packages
+ */
 __exportStar(require("./types"), exports);
 __exportStar(require("./core"), exports);
 __exportStar(require("./abis"), exports);
@@ -23,11 +26,27 @@ __exportStar(require("./services/debank"), exports);
 __exportStar(require("./services/swap-quotes"), exports);
 __exportStar(require("./modules/vaults"), exports);
 __exportStar(require("./modules/sub-accounts"), exports);
+__exportStar(require("./modules/api"), exports);
+/**
+ * EVM cross-chain (LayerZero OVault) exports
+ */
 __exportStar(require("./evm"), exports);
+/**
+ * Solana export
+ */
 __exportStar(require("./adapters/solana"), exports);
+/**
+ * Stellar export
+ */
 __exportStar(require("./adapters/stellar"), exports);
+/**
+ * Upshift Vaults
+ */
 const vaults_1 = require("./core/constants/vaults");
 exports.VAULT_ADDRESSES = vaults_1.VAULT_SYMBOLS_REVERSE;
+/**
+ * Export the SDK class as default
+ */
 const main_1 = require("./main");
 exports.default = main_1.AugustSDK;
 //# sourceMappingURL=index.js.map

package/lib/main.d.ts

@@ -1,27 +1,84 @@
+/**
+ * The main August SDK class.
+ *
+ * @module AugustSDK
+ */
 import SolanaAdapter from './adapters/solana';
 import SuiAdapter from './adapters/sui';
 import StellarAdapter from './adapters/stellar';
 import EVMAdapter from './adapters/evm';
-import { IAddress, IChainId, IVaultHistoricalParams, IWSMonitorHeaders } from './types';
-import { AugustBase, IAugustBase } from './core';
-import { AugustVaults, IVaultBaseOptions, IVaultCustomOptions } from './modules/vaults';
-import { Signer, Wallet } from 'ethers';
-import { IContractWriteOptions } from './modules/vaults/write.actions';
+import type { IAddress, IChainId, IVaultHistoricalParams, IWSMonitorHeaders } from './types';
+import { AugustBase, type IAugustBase } from './core';
+import { AugustVaults, type IVaultBaseOptions, type IVaultCustomOptions } from './modules/vaults';
+import type { Signer, Wallet } from 'ethers';
+import type { IContractWriteOptions } from './modules/vaults/write.actions';
 import { AugustSubAccounts } from './modules/sub-accounts';
+import { AugustApi } from './modules/api';
+/**
+ * Main SDK class for interacting with August Digital vaults and services.
+ * Provides unified access to EVM, Solana, Sui, and Stellar blockchain adapters.
+ */
 export declare class AugustSDK extends AugustBase {
     private vaults;
     private subaccounts;
+    private api;
     solana: SolanaAdapter;
     sui: SuiAdapter;
     stellar: StellarAdapter;
     evm: EVMAdapter;
+    /**
+     * Initialize the August SDK with provider configuration.
+     * Automatically sets up EVM adapter and optionally initializes Solana if RPC URL is provided.
+     */
     constructor(baseConfig: IAugustBase);
+    /**
+     * Get the Sub-Accounts module instance.
+     */
     get subAccountsModule(): AugustSubAccounts;
+    /**
+     * Get the Vaults module instance.
+     */
     get vaultsModule(): AugustVaults;
+    /**
+     * Get the backend API module instance ({@link AugustApi}) — read-only
+     * access to backend-computed data with no on-chain equivalent
+     * (unrealized-PnL series).
+     */
+    get apiModule(): AugustApi;
+    /**
+     * Switch the active network for vault operations.
+     * Updates the SDK's active chain and RPC provider.
+     */
     switchNetwork(chainId: IChainId): void;
+    /**
+     * Set the active wallet address for tracking user-specific vault data.
+     * Updates monitoring headers with the wallet address.
+     */
     updateWallet(address: IAddress): void;
+    /**
+     * Clear the active wallet address from the SDK state and monitoring headers.
+     */
     clearWallet(): void;
+    /**
+     * Pricing and Market Data
+     */
+    /**
+     * Get the current USD price of a token by symbol or contract address.
+     * Falls back to CoinGecko if primary price source fails.
+     *
+     * @param symbol - Token symbol or contract address
+     * @returns Current price in USD
+     */
     getPrice(symbol: string): Promise<any>;
+    /**
+     * Vault Data and Operations
+     */
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
     getVaults(options?: {
         chainIds?: number[];
         headers?: IWSMonitorHeaders;
@@ -32,7 +89,18 @@ export declare class AugustSDK extends AugustBase {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;
     }): Promise<number>;
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
     vaultDeposit(signer: Signer | Wallet, options: IContractWriteOptions): Promise<string>;
+    /**
+     * Fetch detailed information for a specific vault.
+     * @param props - Vault address, chain ID, and optional enrichment options
+     * @returns Single vault object with full metadata
+     */
     getVault(props: {
         vault: IAddress;
         chainId?: IChainId;
@@ -40,10 +108,20 @@ export declare class AugustSDK extends AugustBase {
         loadSubaccounts?: boolean;
         loadSnapshots?: boolean;
     }): Promise<import("./types").IVault>;
+    /**
+     * Get active loans deployed from a vault.
+     * @param props - Vault address and chain ID
+     * @returns Array of loan details including borrower, principal, APR
+     */
     getVaultLoans(props: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("./types").IVaultLoan[]>;
+    /**
+     * Get vault asset allocations across DeFi protocols, CeFi, and OTC positions.
+     * @param props - Vault address and chain ID
+     * @returns Detailed breakdown of vault allocations by category
+     */
     getVaultAllocations(props: {
         vault: IAddress;
         chainId?: IChainId;
@@ -51,6 +129,14 @@ export declare class AugustSDK extends AugustBase {
         status: number;
         message: string;
     }>;
+    /**
+     * Get current or historical APY for a vault.
+     *
+     * @deprecated use getVaultHistoricalTimeseries instead
+     *
+     * @param props - Vault address and optional historical lookback period
+     * @returns APY data including rewards breakdown
+     */
     getVaultApy(props: {
         vault: IAddress;
         historical?: {
@@ -60,6 +146,11 @@ export declare class AugustSDK extends AugustBase {
         value: number;
         timestamp: string;
     }[]>;
+    /**
+     * Get current or historical TVL for a vault.
+     * @param props - Vault address and optional historical parameters
+     * @returns TVL in vault's base asset units
+     */
     getVaultTvl(props: {
         vault: IAddress;
         historical?: IVaultHistoricalParams;
@@ -68,14 +159,29 @@ export declare class AugustSDK extends AugustBase {
         value: import("./types").INormalizedNumber;
         timestamp: string;
     }[]>;
+    /**
+     * Get historical timeseries data for a vault.
+     * @param props - Vault address and optional number of days
+     * @returns Historical timeseries data with TVL, APY, PnL, share price, and other metrics
+     */
     getVaultHistoricalTimeseries(props: {
         vault: IAddress;
         nDays?: number;
     }): Promise<import("./types").IHistoricalTimeseriesResponse>;
+    /**
+     * Get the timestamp when yield was last realized for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+     */
     getYieldLastRealizedOn(props: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<number>;
+    /**
+     * Get redemption requests that are ready to be claimed.
+     * @param props - Vault address, chain ID, and optional wallet filter
+     * @returns Array of available redemption requests with amounts and timestamps
+     */
     getVaultAvailableRedemptions(props: {
         vault: IAddress;
         chainId?: IChainId;
@@ -87,12 +193,26 @@ export declare class AugustSDK extends AugustBase {
         availableRedemptions: import("./types").IVaultAvailableRedemption[];
         pendingRedemptions: import("./types").IVaultAvailableRedemption[];
     }>;
+    /**
+     * Get historical redemption requests for a vault (settled, cancelled,
+     * pending-but-out-of-window), optionally filtered to one wallet.
+     *
+     * @param props - Vault address, chain ID, optional wallet, and an
+     *   optional `lookbackBlocks` for how far back to scan.
+     * @returns Historical redemption records, newest first.
+     */
     getVaultRedemptionHistory(props: {
         vault: IAddress;
         chainId?: IChainId;
         wallet?: IAddress;
         lookbackBlocks?: number;
     }): Promise<import("./types").IVaultRedemptionHistoryItem[]>;
+    /**
+     * Get user positions across vaults including shares and claimable redemptions.
+     * Supports both EVM and Solana vaults.
+     * @param props - Wallet address, chain ID, and optional vault filter
+     * @returns Array of positions with balances and pending redemptions
+     */
     getVaultPositions(props: {
         vault?: IAddress;
         wallet?: IAddress;
@@ -102,12 +222,22 @@ export declare class AugustSDK extends AugustBase {
         stellarWallet?: string;
         options?: IVaultBaseOptions;
     }): Promise<import("./types").IVaultPosition[]>;
+    /**
+     * Get user's historical vault interactions including deposits and withdrawals.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of historical transactions with amounts and timestamps
+     */
     getVaultUserHistory(props: {
         wallet: IAddress;
         chainId?: IChainId;
         vault?: IAddress;
         options?: IVaultBaseOptions;
     }): Promise<import("./types").IVaultUserHistoryItem[]>;
+    /**
+     * Get user's vault share transfer history from subgraph.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of transfer events
+     */
     getVaultUserTransfers(props: {
         wallet: IAddress;
         chainId?: IChainId;
@@ -123,49 +253,202 @@ export declare class AugustSDK extends AugustBase {
         timestamp: number;
         transactionHash: string;
     }[]>;
+    /**
+     * Get lifetime PnL for a user in a specific vault.
+     * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.
+     * @param props - Vault address, wallet address, and optional chain ID
+     * @returns Lifetime PnL data including realized and unrealized PnL in both native token and USD
+     */
     getVaultUserLifetimePnl(props: {
         vault: IAddress;
         wallet: IAddress;
         chainId?: IChainId;
     }): Promise<import("./types").IVaultUserLifetimePnl>;
+    /**
+     * Get PnL for a vault (vault-level, not user-specific).
+     * Returns the vault's overall profit and loss across all users.
+     * @param props - Vault address and optional chain ID
+     * @returns Vault PnL in USD and notional value
+     */
     getVaultPnl(props: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("./types").IVaultPnl>;
+    /**
+     * Get user's staking positions for vault receipt tokens.
+     * @param props - Wallet address and optional chain ID
+     * @returns Array of staking positions with rewards
+     */
     getVaultStakingPositions(props: {
         wallet?: IAddress;
         chainId?: IChainId;
     }): Promise<import("./types").IActiveStakingPosition[]>;
+    /**
+     * Get the borrower's health factor by vault.
+     *
+     * Pass `vault` whenever the caller knows which pool it cares about — it
+     * skips the all-vaults cross-chain fanout and only reads the loans for
+     * that one pool. The response map is keyed by **lowercased** vault
+     * address; look entries up with `address.toLowerCase()`.
+     *
+     * @param props.chainId Optional chain to scope the read to.
+     * @param props.vault Optional vault address. When provided alongside
+     *   `chainId`, only that vault's borrower-health-factor data is fetched.
+     * @returns Object containing the borrower's health factor by vault.
+     */
     getVaultBorrowerHealthFactor(props?: {
         chainId?: IChainId;
         vault?: IAddress;
     }): Promise<Record<string, import("./types").IVaultBorrowerHealthFactor[]> | Record<string, import("./types").IVaultBorrowerHealthFactor[]>[]>;
+    /**
+     * Get user points from the backend API.
+     * This fetches processed points data directly from the backend,
+     * removing the need for client-side points calculation.
+     * @param userAddress - User wallet address
+     * @returns Points data from the backend API
+     */
     getUserPoints(userAddress: IAddress): Promise<any>;
+    /**
+     * Register a user for the points program, authenticated by a wallet signature.
+     *
+     * The caller produces a personal_sign signature over a canonical message
+     * containing the user address, referrer (or `"none"`), chain, nonce, and
+     * expiry — see `AugustVaults.registerUserForPoints` for the exact template.
+     *
+     * @param userAddress - EVM wallet address being registered.
+     * @param referrerAddress - Optional EVM referrer address.
+     * @param chainId - Chain on which the wallet signed; powers the EIP-1271
+     *   fallback for smart-contract wallets and pins the signature cross-chain.
+     * @param signature - 0x-prefixed personal_sign signature over the canonical message.
+     * @param nonce - Single-use random string (8–128 chars).
+     * @param expiry - Unix seconds; must be in the future, within the backend's TTL.
+     * @returns Raw `Response` from the backend.
+     */
     registerUserForPoints(userAddress: IAddress, referrerAddress: IAddress | undefined, chainId: number, signature: string, nonce: string, expiry: number): Promise<Response>;
+    /**
+     * Fetch the points leaderboard data.
+     * @param params - Optional parameters for pagination and sorting
+     * @returns Leaderboard response data
+     */
     fetchPointsLeaderboard(params?: {
         page?: number;
         perPage?: number;
         sortBy?: 'streakDays' | 'totalPoints';
     }): Promise<any>;
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first.
+     * Delegates to {@link AugustApi.getVaultUnrealizedPnlHistory} — see it for
+     * parameter semantics and thrown errors.
+     */
+    getVaultUnrealizedPnlHistory(params: {
+        vault: string;
+        limit?: number;
+    }): Promise<import("./types").IUnrealizedPnlSnapshot[]>;
+    /**
+     * Fetch the latest unrealized-PnL snapshot for every tracked vault.
+     * Delegates to {@link AugustApi.getLatestUnrealizedPnl} — see it for
+     * return shape and thrown errors.
+     */
+    getLatestUnrealizedPnl(): Promise<import("./types").IUnrealizedPnlSnapshot[]>;
+    /**
+     * Get annualized APY metrics for a vault.
+     *
+     * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+     *
+     * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
+     * These fields will be removed on 2026-01-01.
+     * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+     *
+     * @param props - Vault address
+     * @returns Annualized APY data including liquidity APY
+     */
     getVaultAnnualizedApy(props: {
         vault: IAddress;
     }): Promise<import("./types").IVaultAnnualizedApy>;
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param props - Vault address
+     * @returns Vault summary data
+     */
     getVaultSummary(props: {
         vault: IAddress;
     }): Promise<import("./types").IVaultSummary>;
+    /**
+     * Get withdrawal summary and pending queue for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Withdrawal summary and pending queue
+     */
     getVaultWithdrawals(props: {
         vault: IAddress;
         chainId?: IChainId;
     }): Promise<import("./types").IVaultWithdrawals>;
+    /**
+     * Preview the amount of assets that would be received for redeeming shares (queued redemption).
+     * @param props - Vault contract address, shares amount, and optional chain ID
+     * @returns The amount of assets as {@link INormalizedNumber}
+     */
     previewRedemption(props: {
         vault: IAddress;
         sharesAmount: string | bigint | number;
         chainId?: IChainId;
     }): Promise<import("./types").INormalizedNumber>;
+    /**
+     * Query LayerZero USDC deposits from the august-layerzero subgraphs.
+     * Returns all deposits or filters by sender wallet address if provided.
+     *
+     * **Important Notes:**
+     * - Only deposit transactions are tracked (not withdrawals or other operations)
+     * - Sender and recipient addresses are stored in bytes32 format in the subgraph
+     * - Timestamps are available from the subgraph
+     *
+     * **Supported Vaults:**
+     * - `upusdc`: 0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42
+     * - `coreusdc`: 0xE9B725010A9E419412ed67d0fA5f3A5f40159D32
+     * - `earnausd`: 0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA
+     *
+     * @param props - Receipt token type ('upusdc', 'coreusdc', or 'earnausd') and optional wallet address to filter by sender
+     * @returns Array of deposit events with the following structure:
+     * - `assetAmt`: Amount of assets deposited (as string)
+     * - `shareAmt`: Amount of shares received (as string)
+     * - `sender`: Sender address in bytes32 format
+     * - `recipient`: Recipient address in bytes32 format
+     * - `dstEid`: Destination endpoint ID (LayerZero chain identifier)
+     * - `transactionHash_`: Transaction hash
+     *
+     * @throws Error if receipt token is invalid or GraphQL request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all coreUSDC deposits
+     * const allDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'coreusdc'
+     * });
+     *
+     * // Get deposits for a specific wallet
+     * const userDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'upusdc',
+     *   wallet: '0xb0280B58F541131b29D1B33319CD440a99eA0305'
+     * });
+     * ```
+     */
     getLayerZeroDeposits(props: {
         receiptToken: 'upusdc' | 'coreusdc' | 'earnausd';
         wallet?: IAddress;
     }): Promise<import("./services/layerzero/deposits").ILayerZeroDeposit[]>;
+    /**
+     * Get LayerZero redeems for earnAUSD vault
+     *
+     * @example
+     * ```typescript
+     * // Get all earnAUSD redeems
+     * const allRedeems = await sdk.getLayerZeroRedeems();
+     *
+     * // Get redeems for a specific wallet
+     * const userRedeems = await sdk.getLayerZeroRedeems({
+     *   wallet: '0x2de1DCB8EaAd40fAd327fa3eE3F48774b8e20649'
+     * });
+     * ```
+     */
     getLayerZeroRedeems(props?: {
         wallet?: IAddress;
     }): Promise<import("./services/layerzero/redeems").ILayerZeroRedeem[]>;