@kasufinance/kasu-sdk 2.14.0 → 2.15.0

package/src/facade/strategies.ts

@@ -1,5 +1,14 @@
 import { PoolTvlHistoryEntry } from '../domain/pool-tvl';
 import { selectVisiblePools } from '../domain/pools';
+import {
+    finiteOrUndefined,
+    groupRiskManagementItems,
+    parseFacility,
+    readCmsStartDate,
+    securityStructureOf,
+    splitBusinessTypes,
+    StrategyRiskGroup,
+} from '../domain/strategy-details';
 import { pickShortDescription } from '../domain/strategy-summary';
 import { DataService } from '../services/DataService/data-service';
 import {
@@ -15,8 +24,11 @@ import { UserLending } from '../services/UserLending/user-lending';
 import {
     DepositLimits,
     FixedTermOption,
+    OriginatorHistory,
     PlatformStats,
     Strategy,
+    StrategyEndBorrowers,
+    StrategyHistory,
     StrategyRiskPerformance,
     StrategyTranche,
 } from './types';
@@ -35,8 +47,65 @@ export class StrategiesFacade {
          * share their Base counterpart's editorial record). Lowercase keys.
          */
         private _poolMetadataMapping: Record<string, string> = {},
+        /**
+         * The clock the CMS start dates are checked against (a date after it
+         * is refused). Injected for tests; the current time otherwise.
+         */
+        private _now: () => Date = (): Date => new Date(),
+        /**
+         * Milliseconds on a clock that only moves forward, for the shared
+         * CMS reads' 30-second lifetime — separate from `_now`, so a pinned
+         * date clock cannot keep a read alive for ever. Injected for tests;
+         * `Date.now` otherwise.
+         */
+        private _memoClockMs: () => number = (): number => Date.now(),
     ) {}
 
+    /**
+     * Short-lived, per-instance memo of the two CMS-wide reads the pool
+     * getters share, so a Details screen asking for the loss rate, the risk
+     * groups and the originator together reads each collection once. Keyed
+     * by read; holds the in-flight promise, so concurrent callers share it.
+     * A REJECTED read is dropped at once, never served again — the next call
+     * retries.
+     */
+    private _cmsReads = new Map<
+        string,
+        { promise: Promise<unknown>; expiresAt: number }
+    >();
+
+    private _memoCmsRead<T>(key: string, read: () => Promise<T>): Promise<T> {
+        const nowMs = this._memoClockMs();
+        const cached = this._cmsReads.get(key);
+        if (cached && cached.expiresAt > nowMs) {
+            return cached.promise as Promise<T>;
+        }
+        const promise = read();
+        const entry = { promise, expiresAt: nowMs + CMS_READ_TTL_MS };
+        this._cmsReads.set(key, entry);
+        promise.catch(() => {
+            // Only our own entry: a newer read may have replaced it.
+            if (this._cmsReads.get(key) === entry) this._cmsReads.delete(key);
+        });
+        return promise;
+    }
+
+    private _riskManagementRecords(): ReturnType<
+        DataService['getRiskManagement']
+    > {
+        return this._memoCmsRead('riskManagement', () =>
+            this._dataService.getRiskManagement(),
+        );
+    }
+
+    private _originatorProfiles(): ReturnType<
+        DataService['getPoolDelegateProfileAndHistory']
+    > {
+        return this._memoCmsRead('originatorProfiles', () =>
+            this._dataService.getPoolDelegateProfileAndHistory(),
+        );
+    }
+
     /**
      * The pool's loss rate and first-loss capital, from its CMS
      * risk-management record. `null` when the pool has no record.
@@ -48,13 +117,15 @@ export class StrategiesFacade {
      * 0..1 fraction.
      *
      * Requires `directusUrl`; without it the call rejects with
-     * `NO_DIRECTUS_URL_MESSAGE`, like every CMS-only read.
+     * `NO_DIRECTUS_URL_MESSAGE`, like every CMS-only read. Shares its CMS
+     * read with `getRiskManagementGroups` for 30 seconds per instance; a
+     * failed read is never reused.
      */
     async getRiskPerformance(
         poolId: string,
     ): Promise<StrategyRiskPerformance | null> {
         const metadataId = this._metadataIdOf(poolId);
-        const records = await this._dataService.getRiskManagement();
+        const records = await this._riskManagementRecords();
         const record = records.find(
             (r) => String(r.poolIdFK).toLowerCase() === metadataId,
         );
@@ -82,6 +153,10 @@ export class StrategiesFacade {
      * deployment every profile lists no pools and this resolves `null` —
      * the same answer kasu-ui's own lookup gives there today. The metadata
      * candidate becomes live once the service resolves the mapping.
+     *
+     * Shares its reads with `getOriginatorHistory` for 30 seconds per
+     * instance; a failed read is never reused. Each call returns its own
+     * copy of the profile, so mutating it changes nothing shared.
      */
     async getOriginator(
         poolId: string,
@@ -90,15 +165,102 @@ export class StrategiesFacade {
             poolId.toLowerCase(),
             this._metadataIdOf(poolId),
         ]);
-        const profiles =
-            await this._dataService.getPoolDelegateProfileAndHistory();
-        return (
-            profiles.find((profile) =>
-                profile.otherKASUPools.some((pool) =>
-                    candidates.has(String(pool.id).toLowerCase()),
-                ),
-            ) ?? null
+        const profiles = await this._originatorProfiles();
+        const profile = profiles.find((candidate) =>
+            candidate.otherKASUPools.some((pool) =>
+                candidates.has(String(pool.id).toLowerCase()),
+            ),
+        );
+        // A copy: the profiles are shared between calls (see
+        // `_memoCmsRead`), so a caller sorting or editing its result must
+        // not change what the next call returns.
+        return profile
+            ? {
+                  ...profile,
+                  otherKASUPools: profile.otherKASUPools.map((pool) => ({
+                      ...pool,
+                  })),
+              }
+            : null;
+    }
+
+    /**
+     * The credit originator's ENTIRE lending history for a pool — since when,
+     * total originated, loans outstanding, loss rate — read from the profile
+     * `getOriginator` finds, each figure validated. `null` when no profile
+     * lists the pool, or the profile authors none of the four.
+     *
+     * kasu-ui's Details tab shows these as its Credit Originator strip, and
+     * hides the strip when there is no profile. The money figures are
+     * editorial USD on every deployment: never FX-convert them. An XDC pool
+     * resolves `null` today, as it does in kasu-ui (see `getOriginator`).
+     *
+     * Requires `directusUrl`, like every CMS-only read; rejects when the
+     * read fails. Shares its reads with `getOriginator` for 30 seconds per
+     * instance; a failed read is never reused.
+     */
+    async getOriginatorHistory(
+        poolId: string,
+    ): Promise<OriginatorHistory | null> {
+        const profile = await this.getOriginator(poolId);
+        if (!profile) return null;
+        const history: OriginatorHistory = {};
+        const since = readCmsStartDate(
+            profile.delegateLendingHistory,
+            this._now(),
+            { unixSeconds: true },
+        );
+        if (since !== undefined) history.since = since;
+        const totalOriginated = finiteOrUndefined(
+            profile.totalLoanFundsOriginated,
+        );
+        if (totalOriginated !== undefined) {
+            history.totalOriginated = totalOriginated;
+        }
+        const loansOutstanding = finiteOrUndefined(
+            profile.loansUnderManagement,
+        );
+        if (loansOutstanding !== undefined) {
+            history.loansOutstanding = loansOutstanding;
+        }
+        const lossRate = finiteOrUndefined(profile.historicLossRate);
+        if (lossRate !== undefined) history.lossRate = lossRate;
+        return Object.keys(history).length > 0 ? history : null;
+    }
+
+    /**
+     * The pool's Risk Management groups, from its CMS risk-management record:
+     * each group with its items (name, the pool's description of it split
+     * into lines, the shared tooltip), the groups in `RISK_GROUP_ORDER`
+     * (Security & Recourse, Structural Controls, Financial Covenants,
+     * Reporting Covenants, Key Eligibility Criteria, then any other in CMS
+     * order). See `groupRiskManagementItems`.
+     *
+     * `null` when the pool has no record, or the record has no usable item —
+     * then kasu-ui falls back to `Strategy.securityStructure`. XDC pools
+     * resolve through the metadata mapping to their Base record, like
+     * `getRiskPerformance`.
+     *
+     * REJECTS when the CMS read fails (an outage, or no `directusUrl` —
+     * `NO_DIRECTUS_URL_MESSAGE`), so a failure stays visible rather than
+     * reading as "no items". For what to SHOW, treat a rejection like `null`:
+     * fall back to `Strategy.securityStructure`, which arrives with the
+     * strategy and needs no second read.
+     *
+     * Shares its CMS read with `getRiskPerformance` for 30 seconds per
+     * instance; a failed read is never reused.
+     */
+    async getRiskManagementGroups(
+        poolId: string,
+    ): Promise<StrategyRiskGroup[] | null> {
+        const metadataId = this._metadataIdOf(poolId);
+        const records = await this._riskManagementRecords();
+        const record = records.find(
+            (r) => String(r.poolIdFK).toLowerCase() === metadataId,
         );
+        if (!record || !Array.isArray(record.items)) return null;
+        const groups = groupRiskManagementItems(record.items);
+        return groups.length > 0 ? groups : null;
     }
 
     private _metadataIdOf(poolId: string): string {
@@ -281,11 +443,44 @@ export class StrategiesFacade {
             apyStructure: pool.poolApyStructure,
             thumbnailUrl: pool.thumbnailImageUrl,
             bannerUrl: pool.bannerImageUrl,
+            strategyHistory: strategyHistoryOf(pool, this._now()),
+            endBorrowers: endBorrowersOf(pool),
+            securityStructure: securityStructureOf(pool.security),
             _raw: pool,
         };
     }
 }
 
+/**
+ * How long a CMS-wide read is shared between the pool getters. Long enough
+ * for one screen's worth of calls, short enough that a CMS edit shows on the
+ * next visit; apps cache further on their own terms.
+ */
+const CMS_READ_TTL_MS = 30_000;
+
+/** `Strategy.strategyHistory`: an absent figure is an absent key. */
+function strategyHistoryOf(pool: PoolOverview, now: Date): StrategyHistory {
+    const history: StrategyHistory = {};
+    const since = readCmsStartDate(pool.operatingSince, now);
+    if (since !== undefined) history.since = since;
+    const lenderInterestEarned = finiteOrUndefined(pool.yieldEarned);
+    if (lenderInterestEarned !== undefined) {
+        history.lenderInterestEarned = lenderInterestEarned;
+    }
+    return history;
+}
+
+/** Business Types and Facility Type, or `undefined` when neither is authored. */
+function endBorrowersOf(pool: PoolOverview): StrategyEndBorrowers | undefined {
+    const businessTypes = splitBusinessTypes(pool.industryExposure);
+    const facility = parseFacility(pool.loanStructure);
+    if (!businessTypes && !facility) return undefined;
+    return {
+        ...(businessTypes ? { businessTypes } : {}),
+        ...(facility ? { facility } : {}),
+    };
+}
+
 /**
  * A CMS text field as a string, or `undefined` when it is absent, not a
  * string, or empty (blank included) — the CMS stores an emptied field as `''`, and an empty

package/src/facade/types.ts

@@ -1,5 +1,6 @@
 import { BigNumberish, BytesLike } from 'ethers';
 
+import { CmsTwoLineValue, StrategyFacility } from '../domain/strategy-details';
 import { ContractAddresses, SdkConfigOptions } from '../sdk-config';
 import {
     LendingTotals,
@@ -175,10 +176,94 @@ export interface Strategy {
     thumbnailUrl: string;
     /** Banner image URL (empty string when Directus unavailable). */
     bannerUrl: string;
+    /**
+     * The strategy's own lending history, as kasu-ui's Details tab states it
+     * beside Total Active Lending (`tvl.total`). Each figure is absent when
+     * unauthored or unreadable — omit its row, never print a stub.
+     *
+     * Always set by `getAll` / `getVisible` / `getById` (both figures inside
+     * may still be absent). Optional in the type only so that a `Strategy`
+     * built by hand against an earlier version still compiles.
+     */
+    strategyHistory?: StrategyHistory;
+    /**
+     * Who the credit originator lends to, and on what facility. Absent when
+     * the CMS authors neither.
+     */
+    endBorrowers?: StrategyEndBorrowers;
+    /**
+     * The CMS security tags (`security`), trimmed, blanks dropped. Absent when
+     * none are authored.
+     *
+     * kasu-ui shows these, under "Security Structure over End Borrowers", ONLY
+     * when `getRiskManagementGroups` resolves `null` — they are the fallback
+     * for a pool with no risk-management items, not a section of their own.
+     * Treat a REJECTED `getRiskManagementGroups` (a CMS outage) the same way
+     * for display: show these, and report the failure as you see fit.
+     */
+    securityStructure?: string[];
     /** Raw `PoolOverview` for power-users who need all fields. */
     _raw: PoolOverview;
 }
 
+/** `Strategy.strategyHistory`. */
+export interface StrategyHistory {
+    /**
+     * The date this strategy started lending (CMS `operatingSince`), as
+     * `YYYY-MM-DD`. Absent when unauthored, not an ISO date, before 2000 or
+     * in the future (see `readCmsStartDate`). Render it as elapsed time
+     * ("Strategy Lending History").
+     */
+    since?: string;
+    /**
+     * Interest earned by this pool's lenders since inception (the subgraph's
+     * `totalUserInterestAmount`, `PoolOverview.yieldEarned`), in display
+     * units of the deployment's OWN stable token — like `tvl.total`. For the
+     * strategy-wide figure across deployments in USD, see
+     * `strategyTotalsUsd`. Absent when the value is not a finite number.
+     */
+    lenderInterestEarned?: number;
+}
+
+/** `Strategy.endBorrowers`: at least one of the two is present. */
+export interface StrategyEndBorrowers {
+    /**
+     * Business Types (CMS `industryExposure`): the value and its supporting
+     * clause. Absent when unauthored. See `splitBusinessTypes`.
+     */
+    businessTypes?: CmsTwoLineValue;
+    /**
+     * Facility Type (CMS `loanStructure`): the label, its clause, and whether
+     * it revolves. Absent when unauthored. See `parseFacility`.
+     */
+    facility?: StrategyFacility;
+}
+
+/**
+ * The credit originator's ENTIRE lending history — every loan it has made,
+ * not only this strategy's — from its CMS profile
+ * (`kasu.strategies.getOriginatorHistory`). Each figure is absent when
+ * unauthored or not a valid value; omit its tile, never print a stub.
+ *
+ * The money figures are editorial and already in USD, on every deployment:
+ * never convert them by the deployment's FX rate, and never sum them across
+ * a strategy's deployments.
+ */
+export interface OriginatorHistory {
+    /**
+     * The date the originator started lending (CMS
+     * `delegateLendingHistory`), as `YYYY-MM-DD`. Render it as elapsed time
+     * ("Entire Lending History").
+     */
+    since?: string;
+    /** Total loan funds originated, USD (CMS `totalLoanFundsOriginated`). */
+    totalOriginated?: number;
+    /** Loans outstanding, USD (CMS `loansUnderManagement` on the profile). */
+    loansOutstanding?: number;
+    /** Historic loss rate, a 0..1 fraction (CMS `historicLossRate`). */
+    lossRate?: number;
+}
+
 export interface StrategyTranche {
     id: string;
     name: string;

package/src/flows/deposit-flow.ts

@@ -45,8 +45,9 @@ import { WaitableTransaction } from './observable';
  *    lender is not in. A failed read assumes an approve IS needed: the safe
  *    default is a redundant approval, never a reverted deposit.
  * 2. **`generating-sign`** — the lender signs the auth message
- *    (`buildLoanAgreementSignMessage`, or the legacy builder). kasu-backend
- *    reconstructs that string byte-for-byte to verify the signature.
+ *    (`buildLoanAgreementSignMessage`, or the deprecated legacy builder).
+ *    kasu-backend reconstructs that string byte-for-byte to verify the
+ *    signature.
  * 3. **`generating-fetch`** — the agreements service returns the contract.
  * 4. **`awaiting-accept`** — the run PARKS on a promise the consumer settles
  *    with `acceptContract()` or `declineContract()`. This is the only point at
@@ -266,10 +267,19 @@ export interface LoanAgreementRequest {
 
 /**
  * The legacy `I request contract content for {address} at {timestamp}.`
- * format, which kasu-backend still accepts and `/contract/resolve` has no
- * alternative to.
+ * format, which kasu-backend still accepts on `/contract/generate`. It is not
+ * the `/contract/resolve` message: resolve has its own, which the backend
+ * rebuilds and verifies.
+ *
+ * @deprecated Use `{ format: 'loan-agreement', … }` (`LoanAgreementRequest`).
+ *   Only the retired kasu-fe-next app (retired 2026-11-05) and kasu-mobile
+ *   builds from before 2026-09-06 used `format: 'legacy'`; it will be removed
+ *   in the next major version. Behaviour is unchanged until then.
  */
 export interface LegacyContractRequest {
+    /**
+     * @deprecated Use `'loan-agreement'`. Removed in the next major version.
+     */
     format: 'legacy';
 }
 
@@ -378,7 +388,11 @@ export interface DepositFlowInput {
      * contract and then a revert diagnosed as `insufficient-balance`.
      */
     spender?: string;
-    /** Which signed-message format to use, and its fields. */
+    /**
+     * Which signed-message format to use, and its fields. Pass
+     * `format: 'loan-agreement'`; `format: 'legacy'` is deprecated and will be
+     * removed in the next major version.
+     */
     contractMessage: ContractMessageRequest;
     /**
      * The deposit in DISPLAY units, for the generate request only.