@gvnrdao/dh-sdk 0.0.338 → 0.0.339

package/dist/modules/loan/loan-query.module.d.ts

@@ -13,7 +13,7 @@ import { Result } from "../../types/result";
 import { SDKError } from "../../utils/error-handler";
 import type { BitcoinOperations } from "../bitcoin/bitcoin-operations.module";
 import type { Cache } from "../cache/cache-manager.module";
-import type { LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
+import type { BorrowerUcdDebtSummary, LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
 import type { LoanEvents, LoanEventsFilter } from "../../types/event-types";
 import { DiamondHandsGraphClient } from "@graphs/diamond-hands";
 import { type Provider } from "ethers";
@@ -141,6 +141,17 @@ export declare class LoanQuery {
      * @returns Paginated loans for borrower
      */
     getLoansByBorrower(borrower: string, pagination?: PaginationParams, orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt", orderDirection?: "asc" | "desc"): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    /**
+     * Combined UCD debt + by-status counts for a borrower from ONE pass over the
+     * subgraph's raw rows (`graphClient.getBorrowerDebtRows`): BigInt wei sum, strict
+     * status labels, `source: "subgraph"`.
+     *
+     * INDEXED figure, not a transaction input — the subgraph lags writes. Anything that
+     * sizes a repayment reads the chain (`getPositionDetailsView`). Fails loud: a page
+     * failure or the page cap is a SUBGRAPH-category failure carrying the cause; there
+     * is no partial total.
+     */
+    getBorrowerUcdDebtSummary(borrower: string): Promise<Result<BorrowerUcdDebtSummary, SDKError>>;
     /**
      * Get active loans (status = ACTIVE)
      *

package/dist/utils/borrower-ucd-debt-summary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure helpers behind `getBorrowerUcdDebtSummary`.
+ *
+ * Kept free of the graph client so the arithmetic and the pagination loop are
+ * unit-testable without a subgraph: the loop takes a page fetcher, the builder
+ * takes rows. Nothing here reads the chain — every figure is the INDEXED view
+ * (the subgraph lags writes), which is why the summary carries `source: "subgraph"`
+ * and must never size a transaction.
+ */
+import { LoanStatus } from "../types/loanStatus";
+import type { BorrowerUcdDebtSummary } from "../interfaces/chunks/loan-operations.i";
+/** The subgraph fields a debt summary needs, exactly as the indexer serialises them. */
+export interface BorrowerDebtRow {
+    id: string;
+    /** Subgraph enum label, e.g. "ACTIVE" — NOT the numeric LoanStatus. */
+    status: string;
+    /** Wei (18 decimals) as the subgraph's BigInt decimal string. */
+    ucdDebt: string;
+}
+/** One page per round trip at The Graph's ceiling; nothing to tune. */
+export declare const BORROWER_DEBT_ROWS_PAGE_SIZE = 1000;
+/** 10 × 1000 = 10_000 positions. Past this the loop THROWS — never a partial total. */
+export declare const BORROWER_DEBT_ROWS_MAX_PAGES = 10;
+export type BorrowerDebtPageFetcher = (skip: number, first: number) => Promise<BorrowerDebtRow[]>;
+/**
+ * Page `fetchPage` from skip 0 in `BORROWER_DEBT_ROWS_PAGE_SIZE` steps until a
+ * short page. A page failure propagates untouched (the caller wraps it with the
+ * cause); the page cap throws rather than returning what was collected so far.
+ */
+export declare function collectBorrowerDebtRows(fetchPage: BorrowerDebtPageFetcher): Promise<BorrowerDebtRow[]>;
+/**
+ * Subgraph `Position.status` is the enum LABEL ("ACTIVE"). Convert it explicitly
+ * and throw on anything else — the `as LoanStatus` cast elsewhere in the SDK only
+ * pretends the string is a number.
+ */
+export declare function parseSubgraphLoanStatus(label: unknown): LoanStatus;
+/** Exact 18-decimal rendering with trailing zeros trimmed: "5", "21.93", "0". */
+export declare function weiToHumanUcdString(wei: bigint): string;
+/**
+ * Sum every row regardless of status (terminal rows are expected to carry 0; a
+ * non-zero terminal row is an indexer defect that should show up in the total,
+ * not be filtered away) and histogram the statuses.
+ */
+export declare function buildBorrowerUcdDebtSummary(borrower: string, rows: ReadonlyArray<BorrowerDebtRow>, fetchedAt?: number): BorrowerUcdDebtSummary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.338",
+  "version": "0.0.339",
   "description": "TypeScript SDK for Diamond Hands Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -94,7 +94,7 @@
   "sideEffects": false,
   "dependencies": {
     "@gvnrdao/dh-lit-actions": "^0.0.322",
-    "@gvnrdao/dh-lit-ops": "^0.0.315",
+    "@gvnrdao/dh-lit-ops": "^0.0.316",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",