@augustdigital/sdk 8.7.2 → 8.9.0

package/lib/modules/sub-accounts/main.js

@@ -7,8 +7,20 @@ exports.AugustSubAccounts = void 0;
  * @module AugustSubAccounts
  */
 const fetcher_1 = require("./fetcher");
+const ethers_1 = require("ethers");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+/**
+ * Validates that a subaccount address is a well-formed EVM address, throwing a
+ * typed {@link AugustValidationError} if not. August subaccounts are EVM
+ * smart-contract wallets, so an invalid value should fail fast in the SDK
+ * rather than reaching the backend.
+ */
+function assertSubaccountAddress(address, method) {
+    if (typeof address !== 'string' || !(0, ethers_1.isAddress)(address)) {
+        throw new core_1.AugustValidationError('INVALID_ADDRESS', `${method}: "${address}" is not a valid subaccount address — pass the subaccount's EVM (0x…) address.`);
+    }
+}
 /**
  * Subaccount operation class interacting with August Subaccounts
  * Subaccount is a smart contract wallet that serves as the fundamental infrastructure for August's platform.
@@ -24,6 +36,38 @@ class AugustSubAccounts extends core_1.AugustBase {
             'x-user-id': this.monitoring?.['x-user-id'],
         };
     }
+    /**
+     * Retrieves one page of the directory of all August subaccounts.
+     *
+     * Backed by the admin-only `GET /subaccount` backend endpoint, so the
+     * August API key configured on the SDK must belong to an admin user —
+     * non-admin keys are rejected with an auth error by the backend. Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param options - Pagination window over the subaccount directory
+     * @param options.offset - Number of records to skip. Defaults to 0; must be a non-negative integer.
+     * @param options.limit - Page size. Defaults to 100; must be an integer between 1 and 1000 (backend maximum).
+     * @returns The page of subaccount records (address, internal/friendly names, status, type, linked chains, risk metadata). An empty array means the offset is past the end of the directory.
+     * @throws AugustValidationError when `offset` or `limit` is out of range
+     * @throws AugustAuthError when the API key is missing or not admin-scoped
+     * @example
+     *   const page = await augustSdk.subAccountsModule.getAllSubaccounts({
+     *     offset: 0,
+     *     limit: 200,
+     *   });
+     *   console.log(page.map((s) => `${s.internal_name}: ${s.address}`));
+     */
+    async getAllSubaccounts(options = {}) {
+        const offset = options.offset ?? 0;
+        const limit = options.limit ?? 100;
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `getAllSubaccounts: offset must be a non-negative integer, got ${offset}`);
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+            throw new core_1.AugustValidationError('INVALID_INPUT', `getAllSubaccounts: limit must be an integer between 1 and 1000, got ${limit}`);
+        }
+        return (0, fetcher_1.fetchAllSubaccounts)({ offset, limit }, this.keys.august, this.headers);
+    }
     /**
      * Retrieves the health factor for a subaccount.
      * @param subaccountAddress - The address of the subaccount to query
@@ -77,6 +121,85 @@ class AugustSubAccounts extends core_1.AugustBase {
         const response = await (0, fetcher_1.fetchSubaccountSummary)(subaccountAddress, this.keys.august, this.headers);
         return (0, utils_1.transformSubaccountSummary)(response);
     }
+    /**
+     * Retrieves a subaccount's on-chain transaction history, newest first,
+     * optionally windowed by a time range.
+     *
+     * Backed by the authenticated `GET /transactions/v2` backend endpoint,
+     * which resolves and authorizes the subaccount, so the configured August
+     * API key must be authorized for it (an admin-scoped key always is). Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param subaccountAddress - The address of the subaccount to query
+     * @param options - Optional time window
+     * @param options.startTime - ISO-8601 datetime lower bound (inclusive); omit for no lower bound
+     * @param options.endTime - ISO-8601 datetime upper bound (inclusive); omit for no upper bound
+     * @returns The subaccount's transactions with decoded logs, transfers, and function names
+     * @throws AugustValidationError When `subaccountAddress` is not a valid EVM address
+     * @throws AugustAuthError When the API key is missing or not authorized for the subaccount
+     * @throws AugustServerError When the API responds with a non-2xx status
+     * @example
+     *   const txs = await augustSdk.subAccountsModule.getSubaccountTransactions(
+     *     '0xabc…',
+     *     { startTime: '2026-01-01T00:00:00Z' },
+     *   );
+     */
+    async getSubaccountTransactions(subaccountAddress, options = {}) {
+        assertSubaccountAddress(subaccountAddress, 'getSubaccountTransactions');
+        return (0, fetcher_1.fetchSubaccountTransactions)({
+            address: subaccountAddress,
+            startTime: options.startTime,
+            endTime: options.endTime,
+        }, this.keys.august, this.headers);
+    }
+    /**
+     * Retrieves the full loan-book detail for a single loan by its address and
+     * chain.
+     *
+     * Backed by the admin-only `GET /subaccount/loans/{loan_address}` backend
+     * endpoint (60-second server-side cache), so the configured August API key
+     * must belong to an admin user. Makes exactly one HTTP request and no RPC
+     * calls.
+     *
+     * @param loanAddress - The loan contract address
+     * @param chainId - Numeric August chain id the loan lives on (e.g. `1` for Ethereum mainnet)
+     * @returns The loan's {@link ILoanBookInfo} detail
+     * @throws AugustValidationError When `chainId` is not an integer
+     * @throws AugustAuthError When the API key is missing or not admin-scoped
+     * @throws AugustServerError When the loan or chain is not found, or the API otherwise responds non-2xx
+     * @example
+     *   const loan = await augustSdk.subAccountsModule.getSubaccountLoanByAddress(
+     *     '0xloan…',
+     *     1,
+     *   );
+     */
+    async getSubaccountLoanByAddress(loanAddress, chainId) {
+        if (!Number.isInteger(chainId)) {
+            throw new core_1.AugustValidationError('INVALID_CHAIN', `getSubaccountLoanByAddress: chainId must be an integer August chain id, got ${chainId}.`);
+        }
+        return (0, fetcher_1.fetchSubaccountLoanByAddress)(loanAddress, chainId, this.keys.august, this.headers);
+    }
+    /**
+     * Retrieves cross-chain DeBank protocol positions and token balances for a
+     * subaccount and its associated strategies.
+     *
+     * Backed by `GET /subaccount/{subaccount_address}/debank` (300-second
+     * server-side cache). This is a slow endpoint — it fans out to DeBank
+     * across every supported chain — so expect higher latency than other
+     * subaccount reads. Makes exactly one HTTP request and no RPC calls.
+     *
+     * @param subaccountAddress - The address of the subaccount to query
+     * @returns The subaccount's DeBank positions/tokens plus per-strategy breakdowns
+     * @throws AugustValidationError When `subaccountAddress` is not a valid EVM address
+     * @throws AugustServerError When the API responds with a non-2xx status
+     * @example
+     *   const debank = await augustSdk.subAccountsModule.getSubaccountDebank('0xabc…');
+     *   console.log(debank.subaccount.positions.length);
+     */
+    async getSubaccountDebank(subaccountAddress) {
+        assertSubaccountAddress(subaccountAddress, 'getSubaccountDebank');
+        return (0, fetcher_1.fetchSubaccountDebank)(subaccountAddress, this.keys.august, this.headers);
+    }
 }
 exports.AugustSubAccounts = AugustSubAccounts;
 //# sourceMappingURL=main.js.map