@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/core/constants/swap-router.js

@@ -1,17 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SWAP_ROUTER_WRAPPED_NATIVE = exports.SWAP_ROUTER_MAX_SWAPS = exports.ORIGIN_CODES = exports.VAULTS_USING_SWAP_ROUTER = exports.SWAP_ROUTER_ADDRESSES = void 0;
+/**
+ * Address of the `SwapRouter` periphery contract on each supported chain.
+ *
+ * Missing keys mean no SwapRouter is deployed on that chain — callers
+ * should fall back to legacy adapter paths.
+ *
+ * @see {@link getSwapRouterAddress} for the typed lookup helper.
+ */
 exports.SWAP_ROUTER_ADDRESSES = {
     1: '0xAC771209FF2b71EECfF6E85a9AD01db8Ff2618B0',
 };
+/**
+ * Vault addresses registered on a `SwapRouter` via `enableVault`. The
+ * presence of a vault here is the signal to route its deposits through the
+ * SwapRouter rather than the legacy adapter path.
+ *
+ * Entries mirror the on-chain `vaultInfo[addr].referenceAsset != 0` state of
+ * the `SwapRouter` deployment. Verify against the deployed contract before
+ * adding a new entry — a vault that is not registered on-chain will revert
+ * with `InvalidVault` at deposit time.
+ *
+ * Lowercase comparison is required when checking — use
+ * {@link vaultUsesSwapRouter} rather than reading this set directly.
+ */
 exports.VAULTS_USING_SWAP_ROUTER = new Set([
+    // Upshift Core USDC — ERC-4626 vault, reference asset USDC. Enabled on
+    // the mainnet SwapRouter at vaultType=1 (VAULT_TYPE_ERC4626).
     '0xe9b725010a9e419412ed67d0fa5f3a5f40159d32',
+    // Sentora USD — Tokenized Vault V2, reference asset USDC. Enabled on the
+    // mainnet SwapRouter at vaultType=2 (VAULT_TYPE_TOKENIZED_VAULT_V2).
     '0x74ad2f789ed583dbd141bbdafc673fe1f033718b',
 ]);
+/**
+ * 32-byte origin codes registered on the `SwapRouter` via `addOrigin`.
+ * Drives origin/referral-fee accrual. The on-chain admin must register a
+ * code before it can be used — calls with an unknown code revert with
+ * `InvalidOrigin`.
+ *
+ * `default` is the all-zero sentinel — the SwapRouter treats it as "no
+ * origin fee" and skips the origin-fee transfer.
+ */
 exports.ORIGIN_CODES = {
+    /** All-zero sentinel — no origin fee. */
     default: '0x0000000000000000000000000000000000000000000000000000000000000000',
 };
+/**
+ * Maximum number of swap legs the contract accepts in a single
+ * `swapAndDeposit` call. Mirrors the on-chain `MAX_SWAPS` constant; reading
+ * the on-chain value at call time would add an RPC for no gain.
+ *
+ * Kept here so the SDK can reject oversize inputs at the boundary rather
+ * than wait for the on-chain `TooManySwaps` revert.
+ */
 exports.SWAP_ROUTER_MAX_SWAPS = 9;
+/**
+ * Wrapped-native ERC-20 per chain that has a SwapRouter deployment. Mirrors
+ * the on-chain `wrappedNativeTokenAddress()` view to avoid an extra RPC on
+ * every dispatch. Used to validate that native-token deposits target a
+ * vault whose reference asset is the wrapped native — the only configuration
+ * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ */
 exports.SWAP_ROUTER_WRAPPED_NATIVE = {
     1: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
 };

package/lib/core/constants/vaults.d.ts

@@ -1,4 +1,14 @@
 import { IAddress, IPoolFunctions } from '../../types';
+/**
+ * Table of Contents
+ * - Hardcoded Addresses
+ * - Vault Functions to Call
+ * - Subgraph URLs
+ * - Vault Receipt Symbol Mapping
+ */
+/**
+ * Hardcoded subaccount addresses for specific vaults allocations
+ */
 export declare const VAULT_ALLOCATION_SUBACCOUNTS: {
     AgoraAUSD: {
         address: IAddress;
@@ -11,22 +21,68 @@ export declare const VAULT_ALLOCATION_SUBACCOUNTS: {
         useDebank: boolean;
     };
 };
+/**
+ * @deprecated use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ * @todo use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ */
 export declare const MULTI_ASSET_VAULTS: `0x${string}`[];
 export declare const WRAPPER_ADAPTOR: {
     43114: IAddress;
     1: IAddress;
 };
+/**
+ * @deprecated use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ * @todo use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ */
 export declare const OLD_LENDING_POOLS: `0x${string}`[];
 export declare const IDLE_CAPITAL_BORROWER_ADDRESS: `0x${string}`[];
+/**
+ * Vault addresses to exclude from `getTotalDeposited` TVL aggregation.
+ * Addresses are lowercased so EVM, Solana, Sui and Stellar vaults can be
+ * checked uniformly (don't wrap them with `getAddress` — non-EVM addresses
+ * would throw). Add an address here to drop its `latest_reported_tvl` from
+ * the headline number — e.g. closed pre-deposit vaults, test vaults, or
+ * migrated v1 pools that are double-counted by a v2 successor.
+ */
 export declare const TVL_EXCLUDED_VAULTS: ReadonlySet<string>;
+/**
+ * Vault Functions to Call
+ */
+/**
+ * The functions to call on the vault contract
+ * @returns The functions to call
+ */
 export declare const VAULT_FUNCTIONS_V1: IPoolFunctions[];
 export declare const VAULT_FUNCTIONS_V2: IPoolFunctions[];
 export declare const VAULT_FUNCTIONS_V2_RECEIPT: IPoolFunctions[];
 export declare const VAULT_FUNCTIONS_V2_WHITELISTED_ASSETS: IPoolFunctions[];
+/**
+ * NEMO ETH Yield vault address (lowercase for comparisons)
+ */
 export declare const NEMO_VAULT_ADDRESS = "0xa422c3018c46ba90a14acd14f96cb60616f5c91b";
+/**
+ * Subgraph base URL
+ * @deprecated use getVaultMetadata to fetch subgraph URLs from the backend
+ */
 export declare const GOLDSKY_BASE_URL = "https://api.goldsky.com/api/private/project_cm9g0xy3o4j6v01vd34r3hvv9/subgraphs";
+/**
+ * Subgraph URLs
+ * @deprecated use getVaultMetadata to fetch subgraph URLs from the backend
+ */
 export declare const SUBGRAPH_VAULT_URLS: Record<VaultSymbols, string>;
+/**
+ * Vault Receipt Symbol Mapping
+ * @deprecated use getVaultMetadata to fetch vault symbols from the backend
+ */
 type VaultSymbols = 'predlp' | 'sentusd' | 'pregrid' | 'repouscc' | 'earnxrp' | 'tivkbtc' | 'tivusdt0' | 'supermon' | 'earnmon' | 'k3europ' | 'wmon/ausd' | 'wbtc/ausd' | 'earnausd_monad' | 'sausd' | 'farmbold' | 'sentuscc' | 'sentbtc' | 'svusdc' | 'apusdc' | 'testwethtsa' | 'tacusr' | 'upinjusdt' | 'tac-teth' | 'upausd' | 'taccbbtc' | 'xupusdc' | 'uptbtc' | 'gteth' | 'ageth' | 'upusdc' | 'hgeth' | 'upssylva' | 'hbbtc' | 'hbhype' | 'upazt' | 'susdt' | 'upedge' | 'coreusdc' | 'upcusdo' | 'shifteth' | 'upsusde' | 'uplbtc' | 'upavax' | 'tacrseth' | 'musd' | 'earnausd' | 'alpineusdcflagship' | 'alpinecoinshiftusdc' | 'upbtc' | 'upstrbtc' | 'maxiusr' | 'upgammausdc' | 'xhype' | 'wildusd' | 'alpinebtc' | 'prenusd' | 'upyzusd' | 'upnusd' | 'hlpe' | 'nemo eth yield';
+/**
+ * Vault Symbols Mapping
+ * @deprecated use getVaultMetadata to fetch vault symbols from the backend
+ */
 export declare const VAULT_SYMBOLS: Record<IAddress, string>;
+/**
+ * Vault Symbols Reverse Mapping
+ * @deprecated use getVaultMetadata to fetch vault symbols from the backend
+ */
 export declare const VAULT_SYMBOLS_REVERSE: Record<VaultSymbols, IAddress>;
 export {};

package/lib/core/constants/vaults.js

@@ -2,33 +2,63 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VAULT_SYMBOLS_REVERSE = exports.VAULT_SYMBOLS = exports.SUBGRAPH_VAULT_URLS = exports.GOLDSKY_BASE_URL = exports.NEMO_VAULT_ADDRESS = exports.VAULT_FUNCTIONS_V2_WHITELISTED_ASSETS = exports.VAULT_FUNCTIONS_V2_RECEIPT = exports.VAULT_FUNCTIONS_V2 = exports.VAULT_FUNCTIONS_V1 = exports.TVL_EXCLUDED_VAULTS = exports.IDLE_CAPITAL_BORROWER_ADDRESS = exports.OLD_LENDING_POOLS = exports.WRAPPER_ADAPTOR = exports.MULTI_ASSET_VAULTS = exports.VAULT_ALLOCATION_SUBACCOUNTS = void 0;
 const ethers_1 = require("ethers");
+/**
+ * Table of Contents
+ * - Hardcoded Addresses
+ * - Vault Functions to Call
+ * - Subgraph URLs
+ * - Vault Receipt Symbol Mapping
+ */
+/**
+ * Hardcoded subaccount addresses for specific vaults allocations
+ */
 exports.VAULT_ALLOCATION_SUBACCOUNTS = {
+    // For the Agora AUSD vault, fetch the vault allocations from the Caleb subaccount
     AgoraAUSD: {
         address: (0, ethers_1.getAddress)('0x828BC5895b78b2fb591018Ca5bDC2064742D6D0f'),
         subaccount: (0, ethers_1.getAddress)('0xFff71B0b66f076C60Fa2f176a34a6EA709ccF21B'),
         useDebank: false,
     },
+    // For the Earn AUSD (Monad) vault, fetch the vault loans from the RockawayX subaccount
+    // fetch the rest of the exposures from Debank
     earnAUSD: {
         address: (0, ethers_1.getAddress)('0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA'),
         subaccount: (0, ethers_1.getAddress)('0xC8c0Ffb8Ff3BDA26321224e800B3B38AEaB48799'),
         useDebank: true,
     },
 };
+/**
+ * @deprecated use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ * @todo use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ */
 exports.MULTI_ASSET_VAULTS = [
+    //Wild
     (0, ethers_1.getAddress)('0x18EE038C114a07f4B08b420fb1E4149a4F357249'),
+    //Yuzu
     (0, ethers_1.getAddress)('0x517677A19D8ae6FF600FB86C3C7bFCCD651e3eec'),
+    //HyENA
     (0, ethers_1.getAddress)('0x8fFDcd8A96d293f45aA044d10b899F9D71897E8a'),
+    //SingularV
     (0, ethers_1.getAddress)('0xd411aCaE2Bc7019322277A21ff005d94705661C5'),
+    //Neutrl
     (0, ethers_1.getAddress)('0xAEEb2fB279a5aA837367B9D2582F898a63b06ca1'),
+    // HCL Stroom
     (0, ethers_1.getAddress)('0x0C949AAf28bF0318bAa5f2cbF2F2D970f57879aB'),
+    //Aptos Aave
     (0, ethers_1.getAddress)('0xA38d92eC538e9aa3edb980b89701A9d38a1FE015'),
+    // Sentora USCC
     (0, ethers_1.getAddress)('0x63C5d615e937697a80606788965E209414738820'),
+    // Sentora wBTC
     (0, ethers_1.getAddress)('0x3cC0D33B1AEac3d23eA89214b3AC5B4607032167'),
 ];
 exports.WRAPPER_ADAPTOR = {
     43114: (0, ethers_1.getAddress)('0xb2C57614B93c41A7Ec3B91980C0Bb7453904c6e8'),
     1: (0, ethers_1.getAddress)('0x044155804b2ef8fc53C69E3661ceA9b905EDE7Bc'),
 };
+/**
+ * @deprecated use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ * @todo use the backend responses /tokenized_vault internal_type field to determine if the vault is an old lending pool
+ */
 exports.OLD_LENDING_POOLS = [
     (0, ethers_1.getAddress)('0xe1B4d34E8754600962Cd944B535180Bd758E6c2e'),
     (0, ethers_1.getAddress)('0xEBac5e50003d4B17Be422ff9775043cD61002f7f'),
@@ -38,9 +68,25 @@ exports.IDLE_CAPITAL_BORROWER_ADDRESS = [
     (0, ethers_1.getAddress)('0x2151C90C93F52bE82186f162c86DaEABc8911188'),
     (0, ethers_1.getAddress)('0xb74c137E5f976dbdCC638Ec9fd3e05d6D9124E55'),
 ];
+/**
+ * Vault addresses to exclude from `getTotalDeposited` TVL aggregation.
+ * Addresses are lowercased so EVM, Solana, Sui and Stellar vaults can be
+ * checked uniformly (don't wrap them with `getAddress` — non-EVM addresses
+ * would throw). Add an address here to drop its `latest_reported_tvl` from
+ * the headline number — e.g. closed pre-deposit vaults, test vaults, or
+ * migrated v1 pools that are double-counted by a v2 successor.
+ */
 exports.TVL_EXCLUDED_VAULTS = new Set([
-    '0x3299A525986D2e94B3FC6c641C158f5e12dB912d',
+    '0x3299A525986D2e94B3FC6c641C158f5e12dB912d', // Fluent Pre Deposit Vault (migrated to fluent mainnet)
+    // '0x866C6c6627303Be103814150fC0e886BE5D9ea83', // Neutrl Pre Deposit Vault (migrated to Neutrl mainnet)
 ].map((a) => a.toLowerCase()));
+/**
+ * Vault Functions to Call
+ */
+/**
+ * The functions to call on the vault contract
+ * @returns The functions to call
+ */
 exports.VAULT_FUNCTIONS_V1 = [
     'decimals',
     'asset',
@@ -70,8 +116,19 @@ exports.VAULT_FUNCTIONS_V2_RECEIPT = [
 exports.VAULT_FUNCTIONS_V2_WHITELISTED_ASSETS = [
     'getWhitelistedAssets',
 ];
+/**
+ * NEMO ETH Yield vault address (lowercase for comparisons)
+ */
 exports.NEMO_VAULT_ADDRESS = '0xa422c3018c46ba90a14acd14f96cb60616f5c91b';
+/**
+ * Subgraph base URL
+ * @deprecated use getVaultMetadata to fetch subgraph URLs from the backend
+ */
 exports.GOLDSKY_BASE_URL = 'https://api.goldsky.com/api/private/project_cm9g0xy3o4j6v01vd34r3hvv9/subgraphs';
+/**
+ * Subgraph URLs
+ * @deprecated use getVaultMetadata to fetch subgraph URLs from the backend
+ */
 exports.SUBGRAPH_VAULT_URLS = {
     testwethtsa: ``,
     tacusr: `${exports.GOLDSKY_BASE_URL}/august-eth-tacUSR/1.0.0/gn`,
@@ -134,6 +191,10 @@ exports.SUBGRAPH_VAULT_URLS = {
     predlp: `${exports.GOLDSKY_BASE_URL}/august-eth-preDLP/1.0.0/gn`,
     'nemo eth yield': `${exports.GOLDSKY_BASE_URL}/august-mainnet-nemo-eth-yield/1.0.0/gn`,
 };
+/**
+ * Vault Symbols Mapping
+ * @deprecated use getVaultMetadata to fetch vault symbols from the backend
+ */
 exports.VAULT_SYMBOLS = {
     '0xaBC578B79892FC0Dc2906Ab5749862622aD38695': 'preDLP',
     '0x74aD2F789Ed583DBd141bbdafC673fE1F033718b': 'sentUSD',
@@ -197,5 +258,9 @@ exports.VAULT_SYMBOLS = {
     '0xb2FdA773822E5a04c8A70348d66257DD5Cf442DB': 'farmBOLD',
     '0xA422C3018C46ba90a14AcD14f96CB60616F5c91B': 'NEMO ETH Yield',
 };
+/**
+ * Vault Symbols Reverse Mapping
+ * @deprecated use getVaultMetadata to fetch vault symbols from the backend
+ */
 exports.VAULT_SYMBOLS_REVERSE = Object.fromEntries(Object.entries(exports.VAULT_SYMBOLS).map(([key, value]) => [value, key]));
 //# sourceMappingURL=vaults.js.map

package/lib/core/constants/web3.d.ts

@@ -30,6 +30,9 @@ export declare const ORACLE_CONTRACTS: {
 };
 export declare const NETWORKS: Record<IChainId, IChainObj>;
 export declare const AVAILABLE_CHAINS: IChainId[];
+/**
+ * Fallbacks
+ */
 export declare const FALLBACK_DECIMALS = 18;
 export declare const FALLBACK_CHAINID = 42161;
 export declare const FALLBACK_RPC_URLS: Record<number, string[]>;

package/lib/core/constants/web3.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FALLBACK_RPC_URLS = exports.FALLBACK_CHAINID = exports.FALLBACK_DECIMALS = exports.AVAILABLE_CHAINS = exports.NETWORKS = exports.ORACLE_CONTRACTS = exports.MIN_ABIS = exports.NATIVE_ADDRESS = exports.SPECIAL_CHAINS = void 0;
+// Special Chains
 exports.SPECIAL_CHAINS = {
     solana: {
         name: 'Solana',
@@ -13,6 +14,7 @@ exports.SPECIAL_CHAINS = {
         explorer: 'https://stellar.expert',
     },
 };
+// General
 exports.NATIVE_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
 exports.MIN_ABIS = {
     name: 'function name() view returns (string)',
@@ -23,13 +25,17 @@ exports.MIN_ABIS = {
     allowance: 'function allowance(address owner, address spender) external view returns (uint256)',
     managementFeePercent: 'function managementFeePercent() view returns (uint256)',
 };
+// Search: New Chain
 exports.ORACLE_CONTRACTS = {
-    1: '0xA4E24C498D5B28517787D8407eFdcB157A4FbF50',
-    43114: '0x755537Cb5C76E06Bb492CF7c73567e252769c5f5',
-    42161: '0x24F7BC5CA6E4b53cF7311dE1f5bF8Ba528400E1e',
-    8453: '0x07858dF2D8D9aB1DCAAA8b743eb80C6250DFA947',
-    10: '0xe0049eBCCB23Cb81c3d4C9Fa175b32876b70C2AB',
+    1: '0xA4E24C498D5B28517787D8407eFdcB157A4FbF50', // mainnet
+    43114: '0x755537Cb5C76E06Bb492CF7c73567e252769c5f5', // avax
+    42161: '0x24F7BC5CA6E4b53cF7311dE1f5bF8Ba528400E1e', // arbitrum
+    8453: '0x07858dF2D8D9aB1DCAAA8b743eb80C6250DFA947', // base
+    10: '0xe0049eBCCB23Cb81c3d4C9Fa175b32876b70C2AB', // OP
 };
+// Networks
+// Search: New Chain
+// @todo: this should be used for wagmi configs
 exports.NETWORKS = {
     1: {
         name: 'Ethereum',
@@ -113,9 +119,13 @@ exports.NETWORKS = {
     },
 };
 exports.AVAILABLE_CHAINS = Object.keys(exports.NETWORKS).map((c) => Number(c));
+/**
+ * Fallbacks
+ */
 exports.FALLBACK_DECIMALS = 18;
 exports.FALLBACK_CHAINID = 42161;
 exports.FALLBACK_RPC_URLS = {
+    // Ethereum Mainnet
     1: ['https://ethereum-rpc.publicnode.com'],
     42161: ['https://arbitrum-one-rpc.publicnode.com'],
     8453: ['https://base-rpc.publicnode.com'],
@@ -135,5 +145,8 @@ exports.FALLBACK_RPC_URLS = {
     747474: ['https://rpc.katana.network'],
     4114: ['https://rpc.mainnet.citrea.xyz'],
     25363: ['https://rpc.fluent.xyz'],
+    // [-1]: [
+    //   "https://devnet.helius-rpc.com/?api-key=5f652958-74ed-42e4-a874-0ac8056ac02c"
+    // ]
 };
 //# sourceMappingURL=web3.js.map

package/lib/core/errors/index.d.ts

@@ -1,40 +1,76 @@
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `AugustSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { AugustAuthError, AugustTimeoutError } from '@augustdigital/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof AugustAuthError) refreshKey();
+ *   else if (err instanceof AugustTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
+/** Stable error codes attached to SDK errors. */
 export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+/** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
+    /** Original error preserved for stack-trace chaining. */
     cause?: unknown;
+    /** Set from the response `x-correlation-id` header when available. */
     correlationId?: string;
+    /** Structured context attached to the error for logging. */
     context?: Record<string, unknown>;
 }
+/** Base class for all SDK errors. */
 export declare class AugustSDKError extends Error {
     readonly code: AugustErrorCode;
     readonly correlationId?: string;
     readonly context?: Record<string, unknown>;
     constructor(code: AugustErrorCode, message: string, options?: AugustErrorOptions);
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
     toJSON(): Record<string, unknown>;
 }
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
 export declare class AugustAuthError extends AugustSDKError {
     constructor(code: Extract<AugustErrorCode, 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED'>, message: string, options?: AugustErrorOptions);
 }
+/** Network-level failure: connection refused, DNS, fetch failed. */
 export declare class AugustNetworkError extends AugustSDKError {
     constructor(message: string, options?: AugustErrorOptions);
 }
+/** Request exceeded its deadline. */
 export declare class AugustTimeoutError extends AugustSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
     readonly timeoutMs: number;
     constructor(message: string, timeoutMs: number, options?: AugustErrorOptions);
     toJSON(): Record<string, unknown>;
 }
+/** Caller-side input failed validation. */
 export declare class AugustValidationError extends AugustSDKError {
     constructor(code: Extract<AugustErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS'>, message: string, options?: AugustErrorOptions);
 }
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
 export declare class AugustRateLimitError extends AugustSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
     readonly retryAfterMs?: number;
     constructor(message: string, options?: AugustErrorOptions & {
         retryAfterMs?: number;
     });
     toJSON(): Record<string, unknown>;
 }
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
 export declare class AugustServerError extends AugustSDKError {
+    /** HTTP status code returned by the backend. */
     readonly status: number;
     constructor(status: number, message: string, options?: AugustErrorOptions);
     toJSON(): Record<string, unknown>;
 }
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -1,7 +1,24 @@
 "use strict";
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `AugustSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { AugustAuthError, AugustTimeoutError } from '@augustdigital/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof AugustAuthError) refreshKey();
+ *   else if (err instanceof AugustTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
 exports.isAugustSDKError = isAugustSDKError;
+/** Base class for all SDK errors. */
 class AugustSDKError extends Error {
     constructor(code, message, options = {}) {
         super(message);
@@ -12,8 +29,13 @@ class AugustSDKError extends Error {
         if (options.cause !== undefined) {
             this.cause = options.cause;
         }
+        // Restore prototype chain for transpilation targets that downlevel `extends Error`.
         Object.setPrototypeOf(this, new.target.prototype);
     }
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
     toJSON() {
         const out = {
             name: this.name,
@@ -37,6 +59,7 @@ class AugustSDKError extends Error {
     }
 }
 exports.AugustSDKError = AugustSDKError;
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
 class AugustAuthError extends AugustSDKError {
     constructor(code, message, options) {
         super(code, message, options);
@@ -44,6 +67,7 @@ class AugustAuthError extends AugustSDKError {
     }
 }
 exports.AugustAuthError = AugustAuthError;
+/** Network-level failure: connection refused, DNS, fetch failed. */
 class AugustNetworkError extends AugustSDKError {
     constructor(message, options) {
         super('NETWORK_ERROR', message, options);
@@ -51,6 +75,7 @@ class AugustNetworkError extends AugustSDKError {
     }
 }
 exports.AugustNetworkError = AugustNetworkError;
+/** Request exceeded its deadline. */
 class AugustTimeoutError extends AugustSDKError {
     constructor(message, timeoutMs, options) {
         super('TIMEOUT', message, options);
@@ -62,6 +87,7 @@ class AugustTimeoutError extends AugustSDKError {
     }
 }
 exports.AugustTimeoutError = AugustTimeoutError;
+/** Caller-side input failed validation. */
 class AugustValidationError extends AugustSDKError {
     constructor(code, message, options) {
         super(code, message, options);
@@ -69,6 +95,7 @@ class AugustValidationError extends AugustSDKError {
     }
 }
 exports.AugustValidationError = AugustValidationError;
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
 class AugustRateLimitError extends AugustSDKError {
     constructor(message, options) {
         super('RATE_LIMITED', message, options);
@@ -83,6 +110,7 @@ class AugustRateLimitError extends AugustSDKError {
     }
 }
 exports.AugustRateLimitError = AugustRateLimitError;
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
 class AugustServerError extends AugustSDKError {
     constructor(status, message, options) {
         super('SERVER_ERROR', message, options);
@@ -94,6 +122,7 @@ class AugustServerError extends AugustSDKError {
     }
 }
 exports.AugustServerError = AugustServerError;
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isAugustSDKError(err) {
     return (err instanceof AugustSDKError ||
         (err instanceof Error &&