@augustdigital/sdk 8.7.2 → 8.9.0

package/lib/modules/api/fetcher.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchVaultOracleClassification = exports.fetchVaultPerformanceFees = exports.fetchTimelockRequests = exports.fetchCuratorVaultWhitelist = exports.fetchCuratorVaultSubaccounts = exports.fetchOtcMarginRequirements = exports.fetchOtcPositions = exports.fetchRevertReason = exports.fetchCollateralSimulation = exports.fetchCollateralExcessOrDeficit = exports.fetchDiscountFactors = exports.fetchDashboardLoans = void 0;
+const core_1 = require("../../core");
+/**
+ * Fetch the global loan-book aggregate (admin-only `GET /dashboard/loans`).
+ */
+const fetchDashboardLoans = async (augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.dashboard.loans, { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch dashboard loans: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchDashboardLoans = fetchDashboardLoans;
+/**
+ * Fetch every token discount-factor ladder (`GET /risk/discount_factors`).
+ */
+const fetchDiscountFactors = async (augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.risk.discountFactors, { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch discount factors: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchDiscountFactors = fetchDiscountFactors;
+/**
+ * Fetch a subaccount's collateral excess/deficit for one token
+ * (`GET /risk/collateral_excess_or_deficit`).
+ */
+const fetchCollateralExcessOrDeficit = async (params, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.risk.collateralExcessOrDeficit(params.subaccount, params.tokenAddress, params.tokenChain, params.targetHealthFactor), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch collateral excess or deficit: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchCollateralExcessOrDeficit = fetchCollateralExcessOrDeficit;
+/**
+ * Run a collateral simulation (`POST /risk/collateral_simulation`). This is a
+ * pure, read-only simulation — the backend computes required collateral for a
+ * hypothetical loan and changes no state.
+ */
+const fetchCollateralSimulation = async (body, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.risk.collateralSimulation, { method: 'post', data: body, headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to run collateral simulation: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchCollateralSimulation = fetchCollateralSimulation;
+/**
+ * Fetch the decoded revert reason(s) for a transaction from the public
+ * `GET /revert_reason` endpoint. No API key required.
+ */
+const fetchRevertReason = async (txHash, chain, headers) => {
+    const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.revertReason(txHash, chain), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch revert reason: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchRevertReason = fetchRevertReason;
+/**
+ * Fetch all OTC positions (admin-only `GET /otc/position`).
+ */
+const fetchOtcPositions = async (augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.otc.positions, { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch OTC positions: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchOtcPositions = fetchOtcPositions;
+/**
+ * Fetch OTC margin requirements (admin-only `GET /otc/margin_requirement`),
+ * optionally filtered by counterparty id and/or payer.
+ */
+const fetchOtcMarginRequirements = async (filters, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.otc.marginRequirements(filters.otcCounterpartyId, filters.payer), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch OTC margin requirements: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchOtcMarginRequirements = fetchOtcMarginRequirements;
+/**
+ * Fetch the subaccounts linked to a vault (curator-or-admin
+ * `GET /curator/vaults/{vault_address}/subaccounts`).
+ */
+const fetchCuratorVaultSubaccounts = async (vaultAddress, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.curator.vaultSubaccounts(vaultAddress), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch curator vault subaccounts: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchCuratorVaultSubaccounts = fetchCuratorVaultSubaccounts;
+/**
+ * Fetch on-chain whitelist status for a vault's subaccounts (curator-or-admin
+ * `GET /curator/vaults/{vault_address}/whitelist`). EVM vaults only — the
+ * backend 400s for non-EVM vaults.
+ */
+const fetchCuratorVaultWhitelist = async (vaultAddress, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.curator.vaultWhitelist(vaultAddress), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch curator vault whitelist: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchCuratorVaultWhitelist = fetchCuratorVaultWhitelist;
+/**
+ * Fetch timelock requests for a vault on a chain (`GET /timelock-requests`),
+ * optionally filtered by status.
+ */
+const fetchTimelockRequests = async (params, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.timelockRequests(params.vaultAddress, params.chainId, params.status), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch timelock requests: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchTimelockRequests = fetchTimelockRequests;
+/**
+ * Fetch a vault's performance-fee computation
+ * (`GET /metrics/vault_performance_fees`). Slow first call (pandas over full
+ * snapshot history); 20-minute server-side cache.
+ */
+const fetchVaultPerformanceFees = async (params, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.metrics.vaultPerformanceFees(params), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch vault performance fees: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchVaultPerformanceFees = fetchVaultPerformanceFees;
+/**
+ * Fetch a vault's NAV-oracle classification table from the public
+ * `GET /upshift/oracle_classification/{vault_address}` endpoint. No API key
+ * required.
+ */
+const fetchVaultOracleClassification = async (vaultAddress, chainId, headers) => {
+    const response = await (0, core_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.oracleClassification(vaultAddress, chainId), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch vault oracle classification: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchVaultOracleClassification = fetchVaultOracleClassification;
+//# sourceMappingURL=fetcher.js.map

package/lib/modules/api/main.d.ts

@@ -1,4 +1,5 @@
-import type { IUnrealizedPnlSnapshot } from '../../types';
+import { AugustBase, type IAugustBase } from '../../core/base.class';
+import type { ICollateralExcessOrDeficit, ICollateralSimulationInput, ICollateralSimulationResults, ICuratorWhitelistStatus, IDiscountFactorLadder, ILoanBookInfo, IOracleClassification, IOtcMarginRequirement, IOtcPositionRead, IRevertReason, ITimelockRequest, IUnrealizedPnlSnapshot, IVaultPerformanceFees, IWSSubaccountListItem } from '../../types';
 /**
  * Read-only client for August backend REST endpoints that have no on-chain
  * equivalent — currently the unrealized-PnL series the backend computes
@@ -11,8 +12,268 @@ import type { IUnrealizedPnlSnapshot } from '../../types';
  *
  * Accessible as `apiModule` on the SDK instance; the same methods are also
  * exposed directly on the SDK class.
+ *
+ * A subset of methods (loan book, risk) hit authenticated admin-only backend
+ * endpoints and require an admin-scoped August API key on the SDK
+ * constructor; each such method documents the requirement.
  */
-export declare class AugustApi {
+export declare class AugustApi extends AugustBase {
+    private headers;
+    constructor(baseConfig: IAugustBase);
+    /**
+     * Retrieve the global loan-book aggregate across every active client
+     * subaccount — one {@link ILoanBookInfo} entry per loan, with principal /
+     * interest amounts, APRs, state, and the next upcoming payment.
+     *
+     * Backed by the admin-only `GET /dashboard/loans` backend endpoint (60-second
+     * server-side cache), so the August API key configured on the SDK must
+     * belong to an admin user. Makes exactly one HTTP request and no RPC calls.
+     *
+     * @returns Array of loan-book entries; empty when there are no active loans.
+     * @throws AugustAuthError When the API key is missing or not admin-scoped.
+     * @throws AugustServerError When the API responds with a non-2xx status.
+     * @example
+     *   const loans = await sdk.apiModule.getDashboardLoans();
+     *   const active = loans.filter((l) => l.state === 'ACTIVE');
+     */
+    getDashboardLoans(): Promise<ILoanBookInfo[]>;
+    /**
+     * Retrieve every token discount-factor ladder the risk engine applies when
+     * valuing collateral.
+     *
+     * Backed by `GET /risk/discount_factors` (60-second server-side cache),
+     * which requires an authenticated August user; an admin-scoped API key
+     * works. Makes exactly one HTTP request and no RPC calls.
+     *
+     * @returns Array of {@link IDiscountFactorLadder}, one per whitelisted token that has a configured ladder.
+     * @throws AugustAuthError When the API key is missing or not authorized.
+     * @throws AugustServerError When the API responds with a non-2xx status.
+     * @example
+     *   const ladders = await sdk.apiModule.getDiscountFactors();
+     *   console.log(ladders.map((d) => `${d.address}@${d.chain}`));
+     */
+    getDiscountFactors(): Promise<IDiscountFactorLadder[]>;
+    /**
+     * Compute how much collateral a subaccount has in excess of — or is short
+     * of — what it needs to hold a target health factor, for one collateral
+     * token.
+     *
+     * Backed by `GET /risk/collateral_excess_or_deficit` (60-second server-side
+     * cache), which resolves the subaccount and reads its current health factor,
+     * so an authenticated (admin-scoped) August API key is required. Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param params.subaccount Subaccount (smart-contract wallet) address.
+     * @param params.tokenAddress Collateral token address to evaluate.
+     * @param params.tokenChain Numeric August chain id of the token (e.g. `1` for Ethereum mainnet).
+     * @param params.targetHealthFactor Health factor to solve for. Defaults server-side to the minimum healthy factor (1.2); when supplied must be a finite number greater than 0.
+     * @returns The signed excess (positive) or deficit (negative) in USD and token units. Zeroes when the subaccount has no debt.
+     * @throws AugustValidationError When an address is invalid, `tokenChain` is not an integer, or `targetHealthFactor` is out of range.
+     * @throws AugustServerError When the token has no discount factor (backend 404) or the API otherwise responds non-2xx.
+     * @example
+     *   const r = await sdk.apiModule.getCollateralExcessOrDeficit({
+     *     subaccount: '0xabc…',
+     *     tokenAddress: '0xdef…',
+     *     tokenChain: 1,
+     *   });
+     *   console.log(r.amount_usd > 0 ? 'excess' : 'deficit');
+     */
+    getCollateralExcessOrDeficit(params: {
+        subaccount: string;
+        tokenAddress: string;
+        tokenChain: number;
+        targetHealthFactor?: number;
+    }): Promise<ICollateralExcessOrDeficit>;
+    /**
+     * Simulate the collateral required to open a hypothetical loan against a
+     * chosen basket of collateral tokens.
+     *
+     * This is a pure, read-only simulation: the backend `POST
+     * /risk/collateral_simulation` endpoint (60-second server-side cache)
+     * computes required collateral and effective discount factors and changes
+     * no state. It runs against the authenticated backend, so an
+     * (admin-scoped) August API key is required. Makes exactly one HTTP request
+     * and no RPC calls.
+     *
+     * @param input Simulation parameters — see {@link ICollateralSimulationInput}. `collateral_tokens` and `collateral_token_allocation` must be non-empty and equal length; when `on_platform` is `true`, both `loan_redeployed_token_*` fields are required.
+     * @returns The simulated {@link ICollateralSimulationResults}: total debt, required collateral, resulting health factor, and a per-token breakdown.
+     * @throws AugustValidationError When addresses are invalid, `loan_amount` is not a finite non-negative number, the collateral arrays are empty / mismatched, or `on_platform` is set without redeployed-token details.
+     * @throws AugustServerError When the API responds with a non-2xx status (e.g. a token missing a discount factor).
+     * @example
+     *   const sim = await sdk.apiModule.simulateCollateral({
+     *     loan_token_chain: 1,
+     *     loan_token_address: '0xloan…',
+     *     loan_amount: 1_000_000,
+     *     collateral_tokens: [[1, '0xcol…']],
+     *     collateral_token_allocation: [1],
+     *   });
+     *   console.log(sim.total_required_collateral_usd);
+     */
+    simulateCollateral(input: ICollateralSimulationInput): Promise<ICollateralSimulationResults>;
+    /**
+     * Fetch the decoded revert reason(s) for a transaction — error messages,
+     * revert strings, and recognized universal-subaccount errors extracted from
+     * a `debug_traceTransaction` call tree.
+     *
+     * Backed by the public (unauthenticated) `GET /revert_reason` endpoint; no
+     * API key required. The backend relies on the target chain's RPC supporting
+     * `debug_trace*`; on chains/RPCs without it the backend returns a 5xx whose
+     * detail explains why, surfaced here as an {@link AugustServerError}. Makes
+     * exactly one HTTP request and no RPC calls from the SDK itself.
+     *
+     * @param txHash Transaction hash to trace.
+     * @param chain Numeric August chain id the transaction is on (e.g. `1` for Ethereum mainnet).
+     * @returns The decoded {@link IRevertReason}; all arrays empty when the trace yielded no matching signal.
+     * @throws AugustValidationError When `txHash` is empty or `chain` is not an integer.
+     * @throws AugustServerError When the chain/RPC does not support tracing, or the API otherwise responds non-2xx.
+     * @example
+     *   const r = await sdk.apiModule.getRevertReason('0xabc…', 1);
+     *   console.log(r.revert_reasons);
+     */
+    getRevertReason(txHash: string, chain: number): Promise<IRevertReason>;
+    /**
+     * Retrieve every tracked OTC position.
+     *
+     * Backed by the admin-only `GET /otc/position` backend endpoint, so the
+     * configured August API key must belong to an admin user. Makes exactly one
+     * HTTP request and no RPC calls.
+     *
+     * @returns Array of {@link IOtcPositionRead}; empty when there are no OTC positions.
+     * @throws AugustAuthError When the API key is missing or not admin-scoped.
+     * @throws AugustServerError When the API responds with a non-2xx status.
+     * @example
+     *   const positions = await sdk.apiModule.getOtcPositions();
+     */
+    getOtcPositions(): Promise<IOtcPositionRead[]>;
+    /**
+     * Retrieve OTC margin requirements, optionally filtered by counterparty
+     * and/or payer.
+     *
+     * Backed by the admin-only `GET /otc/margin_requirement` backend endpoint,
+     * so the configured August API key must belong to an admin user. Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param options - Optional filters
+     * @param options.otcCounterpartyId - Restrict to a single counterparty (UUID)
+     * @param options.payer - Restrict to a single payer address
+     * @returns Array of {@link IOtcMarginRequirement} matching the filters (all when none given).
+     * @throws AugustAuthError When the API key is missing or not admin-scoped.
+     * @throws AugustServerError When the API responds with a non-2xx status.
+     * @example
+     *   const reqs = await sdk.apiModule.getOtcMarginRequirements({ payer: '0xabc…' });
+     */
+    getOtcMarginRequirements(options?: {
+        otcCounterpartyId?: string;
+        payer?: string;
+    }): Promise<IOtcMarginRequirement[]>;
+    /**
+     * List the subaccounts linked to a vault (curator surface).
+     *
+     * Backed by the curator-or-admin `GET
+     * /curator/vaults/{vault_address}/subaccounts` backend endpoint, so the
+     * configured August API key must belong to the vault's curator or an admin.
+     * Makes exactly one HTTP request and no RPC calls.
+     *
+     * @param vaultAddress - The vault address (EVM `0x…`, Solana, or Stellar)
+     * @returns Array of subaccount records linked to the vault (same shape as the subaccount directory); empty when none are linked.
+     * @throws AugustValidationError When `vaultAddress` is not a valid address.
+     * @throws AugustAuthError When the API key is missing or not curator/admin for the vault.
+     * @throws AugustServerError When the API responds with a non-2xx status.
+     * @example
+     *   const subs = await sdk.apiModule.getCuratorVaultSubaccounts('0xvault…');
+     */
+    getCuratorVaultSubaccounts(vaultAddress: string): Promise<IWSSubaccountListItem[]>;
+    /**
+     * Get on-chain whitelist status for every subaccount linked to a vault
+     * (curator surface).
+     *
+     * Backed by the curator-or-admin `GET
+     * /curator/vaults/{vault_address}/whitelist` backend endpoint. EVM vaults
+     * only — non-EVM vaults manage access internally and the backend returns a
+     * 400 (surfaced as {@link AugustServerError}). Makes exactly one HTTP
+     * request and no RPC calls from the SDK.
+     *
+     * @param vaultAddress - The EVM vault address (`0x…`)
+     * @returns Array of {@link ICuratorWhitelistStatus}, one per linked subaccount; empty when the vault has no subaccounts.
+     * @throws AugustValidationError When `vaultAddress` is not a valid address.
+     * @throws AugustAuthError When the API key is missing or not curator/admin for the vault.
+     * @throws AugustServerError When the vault is non-EVM (backend 400) or the API otherwise responds non-2xx.
+     * @example
+     *   const status = await sdk.apiModule.getCuratorVaultWhitelist('0xvault…');
+     *   console.log(status.filter((s) => !s.is_whitelisted));
+     */
+    getCuratorVaultWhitelist(vaultAddress: string): Promise<ICuratorWhitelistStatus[]>;
+    /**
+     * List timelock (governance) requests for a vault on a chain, optionally
+     * filtered by status.
+     *
+     * Backed by the `GET /timelock-requests` backend endpoint. Makes exactly one
+     * HTTP request and no RPC calls.
+     *
+     * @param params.vaultAddress The vault address the requests target.
+     * @param params.chainId Numeric August chain id (must be a positive integer).
+     * @param params.status Status filter: `"scheduled"` (backend default), `"executed"`, `"cancelled"`, or `"all"`. Omit to use the backend default.
+     * @returns Array of {@link ITimelockRequest}; empty when the vault has no matching requests.
+     * @throws AugustValidationError When `vaultAddress` is invalid or `chainId` is not a positive integer.
+     * @throws AugustServerError When the API responds with a non-2xx status (e.g. an invalid status filter).
+     * @example
+     *   const reqs = await sdk.apiModule.getTimelockRequests({ vaultAddress: '0xvault…', chainId: 1 });
+     */
+    getTimelockRequests(params: {
+        vaultAddress: string;
+        chainId: number;
+        status?: string;
+    }): Promise<ITimelockRequest[]>;
+    /**
+     * Compute a vault's performance fees over a period (backend-computed from
+     * its snapshot history).
+     *
+     * Backed by `GET /metrics/vault_performance_fees`. The backend runs pandas
+     * over the vault's full snapshot history, so the first call is slow; results
+     * are cached server-side for 20 minutes. Makes exactly one HTTP request and
+     * no RPC calls.
+     *
+     * @param params.vault The vault address (EVM `0x…`, Solana, or Stellar).
+     * @param params.annualizedFeesPct Annualized performance-fee percentage. Defaults to 20.
+     * @param params.nativeDenominated Whether to denominate in the vault's native token. Defaults to `true`.
+     * @param params.calculationPeriod Period preset — `"YearToDate"` (default) or `"MonthToDate"`. Ignored by the backend when a custom `startDate`/`endDate` range is supplied.
+     * @param params.startDate ISO-8601 datetime range start. Must be supplied together with `endDate`.
+     * @param params.endDate ISO-8601 datetime range end. Must be supplied together with `startDate`.
+     * @returns The vault's {@link IVaultPerformanceFees} computation.
+     * @throws AugustValidationError When `vault` is invalid, or exactly one of `startDate`/`endDate` is supplied.
+     * @throws AugustServerError When there is insufficient snapshot data for the period, or the API otherwise responds non-2xx.
+     * @example
+     *   const fees = await sdk.apiModule.getVaultPerformanceFees({ vault: '0xvault…' });
+     *   console.log(fees.total_perf_fees_asset);
+     */
+    getVaultPerformanceFees(params: {
+        vault: string;
+        annualizedFeesPct?: number;
+        nativeDenominated?: boolean;
+        calculationPeriod?: string;
+        startDate?: string;
+        endDate?: string;
+    }): Promise<IVaultPerformanceFees>;
+    /**
+     * Fetch a vault's NAV-oracle classification table — how each position/token
+     * is priced (Primary / Secondary Market / CeFi) and its USD value, plus
+     * warnings for tokens that could not be resolved.
+     *
+     * Backed by the public (unauthenticated) `GET
+     * /upshift/oracle_classification/{vault_address}` endpoint; no API key
+     * required. Reads the newest daily snapshot. Makes exactly one HTTP request
+     * and no RPC calls from the SDK.
+     *
+     * @param vault The vault address (EVM `0x…`, Solana, or Stellar).
+     * @param chainId Numeric August chain id the vault lives on.
+     * @returns The vault's {@link IOracleClassification}.
+     * @throws AugustValidationError When `vault` is invalid or `chainId` is not an integer.
+     * @throws AugustServerError When the vault or its snapshot is not found, or the API otherwise responds non-2xx.
+     * @example
+     *   const cls = await sdk.apiModule.getVaultOracleClassification('0xvault…', 1);
+     *   console.log(cls.warnings);
+     */
+    getVaultOracleClassification(vault: string, chainId: number): Promise<IOracleClassification>;
     /**
      * Fetch the historical unrealized-PnL series for a vault, newest first,
      * as computed by the August backend from periodic vault snapshots.