@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/types/typed-contract.d.ts

@@ -1,3 +1,12 @@
+/**
+ * TypedContract type definitions for ethers v6 with abitype.
+ *
+ * This is a local copy of types from ethers-abitype to avoid the global
+ * abitype module augmentation that pollutes AddressType with `string | Addressable`,
+ * which breaks viem type compatibility.
+ *
+ * @see https://github.com/ethers-io/ethers.js/issues/4475
+ */
 import type { BaseContract, ContractTransaction, ContractTransactionResponse, DeferredTopicFilter, EventFragment, FunctionFragment, Result, Overrides } from 'ethers';
 import type { Abi, AbiParametersToPrimitiveTypes, ExtractAbiEvent, ExtractAbiEventNames, ExtractAbiEvents, ExtractAbiFunction, ExtractAbiFunctionNames, ExtractAbiFunctions } from 'abitype';
 type AsArray<T> = T extends readonly unknown[] ? T : never;
@@ -11,26 +20,81 @@ export type TypedFragment<TAbi extends Abi, TFunctionName extends string, TFunct
 };
 export interface TypedContractFunction<TAbi extends Abi, TFunctionName extends string, TFunction extends ExtractAbiFunctions<TAbi> = ExtractAbiFunction<TAbi, TFunctionName>, TInputArgs extends readonly unknown[] = AsArray<AbiParametersToPrimitiveTypes<TFunction['inputs']>>, TResult = TypedContractFunctionResult<TAbi, TFunctionName>, TFragment = TypedFragment<TAbi, TFunctionName>> {
     (...args: [...TInputArgs, overrides?: Overrides]): Promise<TFunction['stateMutability'] extends 'view' | 'pure' ? TResult : ContractTransactionResponse>;
+    /**
+     * The name of the Contract method.
+     */
     name: TFunctionName;
+    /**
+     * The fragment of the Contract method. This will throw on ambiguous
+     * method names.
+     */
     fragment: TFragment;
+    /**
+     * Returns the fragment constrained by %%args%%. This can be used to
+     * resolve ambiguous method names.
+     */
     getFragment(...args: [...TInputArgs]): TFragment;
+    /**
+     * Returns a populated transaction that can be used to perform the
+     * contract method with %%args%%.
+     */
     populateTransaction(...args: [...TInputArgs, overrides?: Overrides]): Promise<ContractTransaction>;
+    /**
+     * Call the contract method with %%args%% and return the value.
+     *
+     * If the return value is a single type, it will be dereferenced and
+     * returned directly, otherwise the full Result will be returned.
+     */
     staticCall(...args: [...TInputArgs, overrides?: Overrides]): Promise<TResult>;
+    /**
+     * Send a transaction for the contract method with %%args%%.
+     */
     send(...args: [...TInputArgs, overrides?: Overrides]): Promise<ContractTransactionResponse>;
+    /**
+     * Estimate the gas to send the contract method with %%args%%.
+     */
     estimateGas(...args: [...TInputArgs, overrides?: Overrides]): Promise<bigint>;
+    /**
+     * Call the contract method with %%args%% and return the Result
+     * without any dereferencing.
+     */
     staticCallResult(...args: [...TInputArgs, overrides?: Overrides]): Promise<Result>;
 }
 export interface TypedContractEvent<TAbi extends Abi, TEventName extends string, TEvent extends ExtractAbiEvents<TAbi> = ExtractAbiEvent<TAbi, TEventName>, TEventArgs extends readonly unknown[] = AsArray<Partial<AbiParametersToPrimitiveTypes<TEvent['inputs']>>>> {
     (...args: [...TEventArgs]): DeferredTopicFilter;
+    /**
+     * The name of the Contract event.
+     */
     name: TEventName;
+    /**
+     * The fragment of the Contract event. This will throw on ambiguous
+     * method names.
+     */
     fragment: EventFragment;
+    /**
+     * Returns the fragment constrained by %%args%%. This can be used to
+     * resolve ambiguous event names.
+     */
     getFragment(...args: [...TEventArgs]): EventFragment;
 }
 export type TypedContract<TAbi extends Abi> = Omit<BaseContract, 'getFunction' | 'getEvent'> & {
     [Method in ExtractAbiFunctionNames<TAbi>]: TypedContractFunction<TAbi, Method>;
 } & {
+    /**
+     * Return the function for a given name. This is useful when a contract
+     * method name conflicts with a JavaScript name such as ``prototype`` or
+     * when using a Contract programatically.
+     */
     getFunction<T extends ExtractAbiFunctionNames<TAbi>>(key: T | TypedFragment<TAbi, T>): TypedContractFunction<TAbi, T>;
+    /**
+     * Return the event for a given name. This is useful when a contract
+     * event name conflicts with a JavaScript name such as ``prototype`` or
+     * when using a Contract programatically.
+     */
     getEvent<T extends ExtractAbiEventNames<TAbi>>(key: T | EventFragment): TypedContractEvent<TAbi, T>;
+    /**
+     * All the Events available on this contract.
+     */
     filters: {
         [EventName in ExtractAbiEventNames<TAbi>]: TypedContractEvent<TAbi, EventName>;
     };

package/lib/types/vaults.d.ts

@@ -1,5 +1,5 @@
-import { IAddress, INormalizedNumber, VaultAddress } from './web3';
-import { IDebankProtocolExposure, IDebankTokenExposure, IOTCPosition, IWSSubaccountCefi, IWSSubaccountLoan, IWSTokenEntry, ITokenizedVaultOperator, ITokenizedVaultEoaOperator, IHIstoricalSnapshot } from './webserver';
+import type { IAddress, INormalizedNumber, VaultAddress } from './web3';
+import type { IDebankProtocolExposure, IDebankTokenExposure, IOTCPosition, IWSSubaccountCefi, IWSSubaccountLoan, IWSTokenEntry, ITokenizedVaultOperator, ITokenizedVaultEoaOperator, IHIstoricalSnapshot, IApyOverride } from './webserver';
 import type { InterfaceAbi } from 'ethers';
 export interface IVaultLoan {
     vault: VaultAddress;
@@ -22,6 +22,13 @@ export interface IVaultLoan {
     isIdleCapital: boolean;
     allocation: number;
 }
+/**
+ * One row of borrower-health-factor data for a vault. `health_factor` is
+ * absent when the upstream August backend has no record for `borrower`
+ * (e.g. test loans whose borrower is not a registered subaccount), or when
+ * the per-borrower fetch failed — callers must handle the undefined case
+ * rather than assume a numeric value is present.
+ */
 export interface IVaultBorrowerHealthFactor {
     borrower: IAddress;
     loan: IAddress;
@@ -72,6 +79,22 @@ export type IExposurePerCategory = {
     walletBalance: number;
     loanBalance: number;
 };
+/**
+ * @todo clean up to minimize data transfer
+ * ```typescript
+ * {
+ *  defi: IOctavfiPortfolio[]
+ *  cefi: IWSSubaccountCefi[]
+ *  otc: Record<string, IOTCPosition>
+ *  breakdown: { // this will be total net values
+ *    defi: number;
+ *    cefi: number;
+ *    otc: number;
+ *    total: number;
+ *  }
+ * }
+ * ```
+ */
 export interface IVaultAllocations {
     defi: IDebankProtocolExposure[];
     tokens: IDebankTokenExposure[];
@@ -100,9 +123,13 @@ export interface IVaultStrategist {
     logo: string;
     name: string;
     type?: string;
+    website_url: string | null;
 }
 export type IVaultVersion = 'evm-0' | 'evm-1' | 'evm-2' | 'sol-0' | 'sui-0' | 'stellar-0';
 export type { ChainType } from './web3';
+/**
+ * Adapter configuration for vaults that support deposits with alternative tokens
+ */
 export interface IVaultAdapterConfig {
     lpTokenAddress?: IAddress;
     isNativeTokenDeposit: boolean;
@@ -118,9 +145,14 @@ export interface IVaultAdapterConfig {
 export interface IVault {
     max_drawdown?: number | null;
     historical_apy?: Record<number, number> | null;
+    /** @deprecated Use getVaultHistoricalTimeseries instead */
     historical_snapshots?: IHIstoricalSnapshot[];
     depositCap?: INormalizedNumber;
     maxDepositAmount?: INormalizedNumber;
+    /**
+     * Vault contract address. May be an EVM hex address, Solana base58 address,
+     * or Stellar base32 address depending on the vault's chain.
+     */
     address: VaultAddress;
     chainId: number;
     name: string;
@@ -194,7 +226,10 @@ export interface IVault {
     latest_reported_tvl?: number | null;
     cachedAt?: string | null;
     showCapFilled?: boolean | null;
+    /** Controls how the vault's APY is displayed; null when the backend has not set an override. */
+    apyOverride?: IApyOverride | null;
     programId?: string;
+    /** Instant redemption config, populated from backend instant_redeem_config */
     instant_redeem_config?: {
         subaccountAddress: IAddress;
         outputAssetSymbol: string;
@@ -263,15 +298,29 @@ export interface IVaultPnl {
     totalPnl: INormalizedNumber;
     pnlUsd: number;
 }
+/**
+ * Response for GET /tokenized_vault/annualized_apy/{vault_address}
+ *
+ * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+ *
+ * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` fields are deprecated.
+ * These fields will be removed on 2026-01-01.
+ * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+ */
 export interface IVaultAnnualizedApy {
     vaultAddress: IAddress;
     liquidityApy: number;
     annualizedApy: number;
+    /** @deprecated Use `liquidAPY7Day` instead. Will be removed on 2026-01-01. */
     hgETH7dLiquidAPY?: number;
+    /** @deprecated Use `liquidAPY30Day` instead. Will be removed on 2026-01-01. */
     hgETH30dLiquidAPY?: number;
     liquidAPY7Day?: number;
     liquidAPY30Day?: number;
 }
+/**
+ * Response for GET /tokenized_vault/vault_summary/{vault_address}
+ */
 export interface IVaultSummary {
     vaultAddress: IAddress;
     name: string;
@@ -283,6 +332,9 @@ export interface IVaultSummary {
         month: number;
     };
 }
+/**
+ * Response for GET /withdrawals/{chain}/{vault_address}
+ */
 export interface IVaultWithdrawals {
     vaultAddress: IAddress;
     chain: string;
@@ -295,6 +347,9 @@ export interface IVaultWithdrawals {
         receiver: IAddress;
     }>;
 }
+/**
+ * Response for GET /vaults/\{vault_addr\}/pending-redemptions
+ */
 export interface IVaultPendingRedemptions {
     vault: {
         address: string;
@@ -326,38 +381,120 @@ export interface IVaultPendingRedemptions {
         isOverdue: boolean;
     }>;
 }
+/**
+ * One unrealized-PnL snapshot for a vault, computed by the August backend
+ * from periodic vault state. `timestamp` is an ISO-8601 datetime; monetary
+ * fields are denominated in the vault's reference asset
+ * (`referenceAsset`) except `assetPrice`, which is the asset's USD price.
+ */
+export type IUnrealizedPnlSnapshot = {
+    timestamp: string;
+    vaultName: string;
+    vaultAddress: string;
+    strategistName: string | null;
+    referenceAsset: string;
+    assetPrice: number;
+    tvlOnVault: number;
+    currentRedeemRatio: number;
+    actualTvl: number;
+    adjustedRedeemRatio: number;
+    unrealizedPnl: number;
+    unrealizedPnlInAsset: number;
+};
+/**
+ * Vault metadata item from upshift API
+ */
 export interface IVaultMetadataItem {
     symbol: string;
     subgraph: string;
     address: string;
 }
+/**
+ * Response type for getVaultMetadata
+ * Keys are lowercase of the symbol value
+ */
 export type IVaultMetadata = Record<string, IVaultMetadataItem>;
+/**
+ * Numeric vault-type tag used by the on-chain `SwapRouter` to branch between
+ * the ERC-4626 (`deposit(uint256, address)`) and multi-asset
+ * (`deposit(address, uint256, address)`) deposit interfaces.
+ *
+ * Values match the contract's `VAULT_TYPE_ERC4626` / `VAULT_TYPE_TOKENIZED_VAULT_V2`
+ * constants exactly. Set by an admin per-vault via `enableVault` and looked
+ * up via `vaultInfo(vaultAddr).vaultType`. SDK callers normally do not pass
+ * this — the router resolves it internally.
+ */
 export declare enum SwapRouterVaultType {
     ERC4626 = 1,
     TokenizedVaultV2 = 2
 }
+/**
+ * One swap leg passed to `SwapRouter.swapAndDeposit`.
+ *
+ * The router pulls `amountIn` of `tokenIn` from the caller, approves the
+ * configured `tokenTransferProxies[router]` address, and calls `router` with
+ * `payload`. Output is measured by balance-diff and must clear `minAmountOut`
+ * or the call reverts with `SlippageError`.
+ *
+ * For a single-hop swap, `tokenOut` is typically the vault's reference asset.
+ * For multi-hop, intermediate legs use any whitelisted token.
+ */
 export interface ISwapParams {
+    /** ERC-20 address pulled from the caller. Must be whitelisted via `whitelistedTokens`. */
     tokenIn: IAddress;
+    /** ERC-20 address the router is expected to produce. */
     tokenOut: IAddress;
+    /** Input amount in `tokenIn`'s smallest unit (no decimals). */
     amountIn: bigint;
+    /** Minimum acceptable `tokenOut` output. Below this the call reverts. */
     minAmountOut: bigint;
+    /** Whitelisted DEX router target (enabled via `enableRouter`). */
     router: IAddress;
+    /** ABI-encoded calldata to invoke on `router`. */
     payload: `0x${string}`;
 }
+/**
+ * Common options shared by every public SwapRouter SDK method.
+ */
 export interface ISwapRouterBaseOptions {
+    /** EVM chain ID — must have an entry in `SWAP_ROUTER_ADDRESSES`. */
     chainId: number;
+    /** August vault address. Must be registered via `enableVault` on the router. */
     vault: IAddress;
+    /** Address that receives the minted vault shares. */
     receiver: IAddress;
+    /**
+     * 32-byte origin/referral code registered via `addOrigin`. Drives the
+     * origin-fee accrual. Defaults to {@link ORIGIN_CODES.default} when omitted.
+     */
     originCode?: `0x${string}`;
+    /** When `true`, the helper awaits a single confirmation before returning. */
     wait?: boolean;
 }
+/**
+ * Options for `swapAndDeposit` — ERC-20 in, vault reference asset out.
+ */
 export interface ISwapAndDepositOptions extends ISwapRouterBaseOptions {
+    /** One or more swap legs. Capped by the contract's `MAX_SWAPS`. */
     swaps: ISwapParams[];
 }
+/**
+ * Options for `depositViaSwapRouter` — direct deposit (no swap) of an
+ * already-held asset, routed through the SwapRouter so origin/swap-fee
+ * accounting still applies.
+ */
 export interface ISwapRouterDirectDepositOptions extends ISwapRouterBaseOptions {
+    /** Deposited ERC-20 asset. For ERC-4626 vaults this must equal the reference asset. */
     asset: IAddress;
+    /** Amount in `asset`'s smallest unit. */
     amount: bigint;
 }
+/**
+ * Options for `depositNativeViaSwapRouter` — wraps `msg.value` to the
+ * chain's wrapped-native token and deposits. Only valid when the vault's
+ * reference asset equals `wrappedNativeTokenAddress`.
+ */
 export interface ISwapRouterNativeDepositOptions extends ISwapRouterBaseOptions {
+    /** Native token amount in wei. Sent as `msg.value`. */
     amount: bigint;
 }

package/lib/types/vaults.js

@@ -6,6 +6,16 @@ var VaultRedemptionStatus;
     VaultRedemptionStatus["AWAITING_COOLDOWN"] = "awaiting_cooldown";
     VaultRedemptionStatus["READY_TO_CLAIM"] = "ready_to_claim";
 })(VaultRedemptionStatus || (exports.VaultRedemptionStatus = VaultRedemptionStatus = {}));
+/**
+ * Numeric vault-type tag used by the on-chain `SwapRouter` to branch between
+ * the ERC-4626 (`deposit(uint256, address)`) and multi-asset
+ * (`deposit(address, uint256, address)`) deposit interfaces.
+ *
+ * Values match the contract's `VAULT_TYPE_ERC4626` / `VAULT_TYPE_TOKENIZED_VAULT_V2`
+ * constants exactly. Set by an admin per-vault via `enableVault` and looked
+ * up via `vaultInfo(vaultAddr).vaultType`. SDK callers normally do not pass
+ * this — the router resolves it internally.
+ */
 var SwapRouterVaultType;
 (function (SwapRouterVaultType) {
     SwapRouterVaultType[SwapRouterVaultType["ERC4626"] = 1] = "ERC4626";

package/lib/types/web3.d.ts

@@ -1,8 +1,16 @@
 import { Signer, Provider } from 'ethers';
 export type IAddress = `0x${string}`;
+/**
+ * Address type for vault contracts across all supported chains.
+ * EVM vaults use `0x`-prefixed hex addresses, Solana vaults use base58,
+ * and Stellar vaults use 56-character base32 addresses (G/C prefix).
+ *
+ * Use this instead of `IAddress` when the address may belong to any chain.
+ */
 export type VaultAddress = string;
 export type IChainId = number;
 export type ChainType = 'evm' | 'solana' | 'sui' | 'stellar';
+/** Runtime type guard for ChainType values (e.g. at API deserialization boundaries). */
 export declare function isChainType(value: unknown): value is ChainType;
 export type IChainObj = {
     chainId: number;

package/lib/types/web3.js

@@ -7,6 +7,7 @@ const VALID_CHAIN_TYPES = new Set([
     'sui',
     'stellar',
 ]);
+/** Runtime type guard for ChainType values (e.g. at API deserialization boundaries). */
 function isChainType(value) {
     return typeof value === 'string' && VALID_CHAIN_TYPES.has(value);
 }

package/lib/types/webserver.d.ts

@@ -1,5 +1,15 @@
 import { IUserRoles } from './user';
 import { IAddress, type ChainType, type IStellarNetwork } from './web3';
+/**
+ * Table of Contents
+ * 1) Subaccounts
+ * 2) Metrics
+ * 3) Tokens
+ * 4) Users
+ * 5) Statuses
+ * 6) Integrations
+ * 7) Lending Pools
+ */
 export type IHIstoricalSnapshot = {
     total_assets: number;
     total_shares: number;
@@ -14,6 +24,9 @@ export interface IWSMonitorHeaders {
     'x-user-id'?: string;
     'x-environment'?: string;
 }
+/**
+ * Subaccounts
+ */
 export type IWSSubaccountPermission = {
     name: string;
     chain: number;
@@ -117,6 +130,9 @@ export interface IWSSubaccountLoan {
     payment_interval: number;
     lender_apr: number;
 }
+/**
+ * Metrics
+ */
 export type IWSMetricsPnlAttributes = {
     pnl: number;
     percent_return: number;
@@ -289,6 +305,9 @@ export type IWSMetricsTimeseries = {
     total_pnl_7d: number | null;
     total_pnl_30d: number | null;
 };
+/**
+ * Tokens
+ */
 export type IWSTokenEntry = {
     symbol: string;
     address: `0x${string}`;
@@ -306,6 +325,9 @@ export type IWSTokenPrice = {
     price: number;
     dt: string;
 };
+/**
+ * Users
+ */
 export type IWSUserSubaccount = {
     internal_name: string;
     friendly_name: string;
@@ -332,12 +354,21 @@ export type IWSUser = {
     disabled: boolean;
     id: string;
 };
+/**
+ * Statuses
+ */
 export type IWSFireblocksTxStatus = 'SUBMITTED' | 'PENDING_AML_SCREENING' | 'PENDING_AUTHORIZATION' | 'QUEUED' | 'PENDING_SIGNATURE' | 'PENDING_3RD_PARTY_MANUAL_APPROVAL' | 'PENDING_3RD_PARTY' | 'BROADCASTING' | 'CONFIRMING' | 'COMPLETED' | 'CANCELLING' | 'BLOCKED' | 'REJECTED' | 'FAILED';
+/**
+ * Integrations
+ */
 export interface IWSIntegrationMorphoApy {
     apy: number;
     vault_positions: any[];
     token: IWSTokenEntry;
 }
+/**
+ * Lending Pools
+ */
 export interface IWSVaultLoan {
     address: IAddress;
     lender: IAddress;
@@ -392,14 +423,23 @@ export interface ITokenizedVaultEoaOperator {
     id: string;
     name: string;
 }
+/**
+ * Controls how the vault's APY is displayed in the UI.
+ * When `is_show_target_apy` is true, the UI should show a target/projected APY.
+ * When `is_show_hardcoded_apy` is true, `hardcoded_apy` overrides the computed APY.
+ */
 export interface IApyOverride {
+    /** Whether to display a target APY rather than historical performance. */
     is_show_target_apy: boolean;
+    /** Whether to display `hardcoded_apy` in place of the computed APY. */
     is_show_hardcoded_apy: boolean;
+    /** The fixed APY value to display when `is_show_hardcoded_apy` is true, or null. */
     hardcoded_apy: number | null;
 }
 export interface ITokenizedVaultStrategist {
     strategist_name: string;
     strategist_logo: string;
+    /** URL of the strategist's website, or null if not provided. */
     website_url: string | null;
     id: string;
 }
@@ -534,6 +574,7 @@ export interface ITokenizedVault {
     stellar_vault_metadata?: IStellarVaultMetadata | null;
     lagDuration: number;
     historical_apy: Record<number, number> | null;
+    /** @deprecated Use getVaultHistoricalTimeseries instead */
     historical_snapshots?: IHIstoricalSnapshot[];
     max_drawdown: number | null;
     daily_pnl_per_share: Record<string, number>;
@@ -552,8 +593,12 @@ export interface ITokenizedVault {
         }>;
     };
     show_cap_filled: boolean | null;
+    /** Controls APY display behaviour in the UI; null when the server has not set an override. */
     apy_override: IApyOverride | null;
 }
+/**
+ * @deprecated
+ */
 export interface IWSVaultHistoricalApy {
     data: {
         labels: string[];

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.3.1",
+  "version": "8.5.0",
   "main": "lib/index.js",
+  "types": "lib/sdk.d.ts",
   "keywords": [
     "augustdigital",
     "sdk",
@@ -59,11 +60,11 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node ../../scripts/run-api-extractor.mjs --only sdk",
     "test": "pnpm build && cross-env node dist/test",
-    "test:jest": "jest",
-    "test:jest:watch": "jest --watch",
-    "test:jest:coverage": "jest --coverage",
+    "test:jest": "jest --config jest.config.unit.js",
+    "test:jest:watch": "jest --config jest.config.unit.js --watch",
+    "test:jest:coverage": "jest --config jest.config.unit.js --coverage",
     "test:forknet": "node tests/forknet/run.mjs",
     "clean": "rm -rf ./lib",
     "format": "biome check --write .",