@augustdigital/sdk 8.8.0 → 8.9.0

package/lib/modules/sub-accounts/fetcher.d.ts

@@ -1,5 +1,32 @@
 import { type IFetchAugustOptions } from '../../core';
-import type { IAddress, IOTCPosition, IWSSubaccountCefi, IWSSubAccountHealthFactor, IWSSubaccountLoan, IWSSubaccountSummary } from '../../types';
+import type { IAddress, ILoanBookInfo, IOTCPosition, ISubaccountDebank, ISubaccountTransaction, IWSSubaccountCefi, IWSSubAccountHealthFactor, IWSSubaccountListItem, IWSSubaccountLoan, IWSSubaccountSummary } from '../../types';
+/**
+ * Fetch one page of the subaccount directory (admin-only backend endpoint)
+ */
+export declare const fetchAllSubaccounts: (pagination: {
+    offset?: number;
+    limit?: number;
+}, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IWSSubaccountListItem[]>;
+/**
+ * Fetch a subaccount's transaction history (authenticated `GET
+ * /transactions/v2`), optionally windowed by ISO-8601 start/end datetimes.
+ */
+export declare const fetchSubaccountTransactions: (payload: {
+    address: IAddress;
+    startTime?: string;
+    endTime?: string;
+}, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<ISubaccountTransaction[]>;
+/**
+ * Fetch a single loan's loan-book detail by loan address + chain
+ * (admin-only `GET /subaccount/loans/{loan_address}`).
+ */
+export declare const fetchSubaccountLoanByAddress: (loanAddress: string, chainId: number, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<ILoanBookInfo>;
+/**
+ * Fetch cross-chain DeBank positions for a subaccount (`GET
+ * /subaccount/{subaccount_address}/debank`). Slow endpoint (300-second
+ * server-side cache) — it fans out across every supported chain.
+ */
+export declare const fetchSubaccountDebank: (address: IAddress, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<ISubaccountDebank>;
 /**
  * Fetch subaccount health factor for a given subaccount address
  */

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

@@ -1,7 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchSubaccountSummary = exports.fetchSubaccountOtcPositions = exports.fetchSubaccountCefiPositions = exports.fetchSubaccountLoans = exports.fetchSubaccountHeathFactor = void 0;
+exports.fetchSubaccountSummary = exports.fetchSubaccountOtcPositions = exports.fetchSubaccountCefiPositions = exports.fetchSubaccountLoans = exports.fetchSubaccountHeathFactor = exports.fetchSubaccountDebank = exports.fetchSubaccountLoanByAddress = exports.fetchSubaccountTransactions = exports.fetchAllSubaccounts = void 0;
 const core_1 = require("../../core");
+/**
+ * Fetch one page of the subaccount directory (admin-only backend endpoint)
+ */
+const fetchAllSubaccounts = async (pagination, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.list(pagination.offset, pagination.limit), {
+        headers,
+    });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch subaccounts: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchAllSubaccounts = fetchAllSubaccounts;
+/**
+ * Fetch a subaccount's transaction history (authenticated `GET
+ * /transactions/v2`), optionally windowed by ISO-8601 start/end datetimes.
+ */
+const fetchSubaccountTransactions = async (payload, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.transactions.v2(payload.address, payload.startTime, payload.endTime), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch subaccount transactions: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchSubaccountTransactions = fetchSubaccountTransactions;
+/**
+ * Fetch a single loan's loan-book detail by loan address + chain
+ * (admin-only `GET /subaccount/loans/{loan_address}`).
+ */
+const fetchSubaccountLoanByAddress = async (loanAddress, chainId, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.loanByAddress(loanAddress, chainId), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch loan by address: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchSubaccountLoanByAddress = fetchSubaccountLoanByAddress;
+/**
+ * Fetch cross-chain DeBank positions for a subaccount (`GET
+ * /subaccount/{subaccount_address}/debank`). Slow endpoint (300-second
+ * server-side cache) — it fans out across every supported chain.
+ */
+const fetchSubaccountDebank = async (address, augustKey, headers) => {
+    const response = await (0, core_1.fetchAugustWithKey)(augustKey, core_1.WEBSERVER_ENDPOINTS.subaccount.debank(address), { headers });
+    if (!response.ok || typeof response.json !== 'function') {
+        throw new Error(`Failed to fetch subaccount debank: ${response.statusText || 'Unknown error'}`);
+    }
+    return response.json();
+};
+exports.fetchSubaccountDebank = fetchSubaccountDebank;
 /**
  * Fetch subaccount health factor for a given subaccount address
  */

package/lib/modules/sub-accounts/main.d.ts

@@ -1,5 +1,5 @@
 import { AugustBase, type IAugustBase } from '../../core';
-import type { IAddress } from '../../types';
+import type { IAddress, ILoanBookInfo, ISubaccountDebank, ISubaccountTransaction, IWSSubaccountListItem } from '../../types';
 /**
  * Subaccount operation class interacting with August Subaccounts
  * Subaccount is a smart contract wallet that serves as the fundamental infrastructure for August's platform.
@@ -9,6 +9,31 @@ import type { IAddress } from '../../types';
 export declare class AugustSubAccounts extends AugustBase {
     private headers;
     constructor(baseConfig: IAugustBase);
+    /**
+     * 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}`));
+     */
+    getAllSubaccounts(options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<IWSSubaccountListItem[]>;
     /**
      * Retrieves the health factor for a subaccount.
      * @param subaccountAddress - The address of the subaccount to query
@@ -148,4 +173,71 @@ export declare class AugustSubAccounts extends AugustBase {
         netAccountValue: number;
         totalEquityValue: number;
     }>;
+    /**
+     * 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' },
+     *   );
+     */
+    getSubaccountTransactions(subaccountAddress: IAddress, options?: {
+        startTime?: string;
+        endTime?: string;
+    }): Promise<ISubaccountTransaction[]>;
+    /**
+     * 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,
+     *   );
+     */
+    getSubaccountLoanByAddress(loanAddress: string, chainId: number): Promise<ILoanBookInfo>;
+    /**
+     * 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);
+     */
+    getSubaccountDebank(subaccountAddress: IAddress): Promise<ISubaccountDebank>;
 }

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