@kasufinance/kasu-sdk 2.4.2 → 2.6.0

package/dist/domain/settlement.js

@@ -0,0 +1,117 @@
+/**
+ * Cycles and the clearing window — the protocol's weekly clock, as numbers.
+ *
+ * Lifted verbatim from kasu-ui's `features/portfolio/lib/settlement-window.ts`
+ * and `features/lending/lib/cycle-dates.ts`. The two formatters that live
+ * beside `deriveCycleDates` there (`formatCycleDate`, `formatCycleCloseUtc`)
+ * print words and stay in the applications; everything here is unix seconds in
+ * and unix seconds out.
+ *
+ * The clearing window is the fixed 48 hours immediately preceding an epoch
+ * end. Inside it, pending requests are being processed and cannot be modified,
+ * and the countdown runs to the epoch end. Outside it, the countdown runs to
+ * the next clearing-window start.
+ *
+ * The epoch end comes straight from the chain (`nextEpochStartTimestamp`, i.e.
+ * the SDK's `getNextEpochDate`) — the same value the protocol's own
+ * `getNextClearingPeriodDate` derives from — so the window always lines up
+ * with the real weekly schedule (Tue 06:00 → Thu 06:00 UTC on Base) instead of
+ * a projected subgraph timestamp that can drift off the grid.
+ */
+/**
+ * Clearing-window length — a fixed 48h protocol constant. Exported so every
+ * consumer derives the window from the same number this module runs on.
+ */
+export const CLEARING_WINDOW_SECONDS = 48 * 60 * 60;
+/**
+ * Weekly cadence — the epoch schedule is fixed weekly (Tue → Thu UTC on Base).
+ * Used only to roll a cycle forward when a request lands inside a window that
+ * has already closed.
+ */
+const WEEK_SECONDS = 7 * 24 * 60 * 60;
+/**
+ * Which phase of the weekly cycle `nowSeconds` falls in, and how long is left
+ * of it.
+ *
+ * `'unknown'` when no epoch boundary has been loaded yet, or when the one on
+ * hand is stale (it has already elapsed — the on-chain value refetches to the
+ * next boundary shortly after rollover). A caller must render its "no cycle
+ * loaded" state there, never a zeroed countdown.
+ */
+export function computeSettlementWindow({ nowSeconds, nextEpochStart, clearingWindowSeconds = CLEARING_WINDOW_SECONDS, }) {
+    // No epoch boundary loaded yet, or a stale one that already elapsed.
+    if (nextEpochStart <= 0 || nextEpochStart <= nowSeconds) {
+        return { phase: 'unknown' };
+    }
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+    if (nowSeconds < clearingStart) {
+        return {
+            phase: 'awaiting',
+            secondsUntilClearing: clearingStart - nowSeconds,
+            nextClearingStart: clearingStart,
+        };
+    }
+    // nowSeconds is in [clearingStart, nextEpochStart) — inside the window.
+    return {
+        phase: 'clearing',
+        secondsUntilEpochEnd: nextEpochStart - nowSeconds,
+        epochEnd: nextEpochStart,
+    };
+}
+/**
+ * The next cycle boundary strictly after `nowSeconds`, in unix seconds — the
+ * cycle close (`nextEpochStart − 48h`) while the window is still open, the
+ * epoch end once we are inside it.
+ *
+ * `undefined` when there is no boundary left to wait for: no epoch boundary
+ * loaded, or a cached one that has already elapsed — the same staleness rule
+ * `computeSettlementWindow` applies before it reports `'unknown'`.
+ *
+ * Split out of the state machine because some consumers need the INSTANT
+ * rather than the phase: one to flush the cycle-dependent caches when the
+ * clock crosses it, one to move a pre-commit screen's snapshot clock at the
+ * same moment.
+ */
+export function nextCycleBoundary(nextEpochStart, nowSeconds, clearingWindowSeconds = CLEARING_WINDOW_SECONDS) {
+    if (!nextEpochStart || nextEpochStart <= 0)
+        return undefined;
+    const clearingStart = nextEpochStart - clearingWindowSeconds;
+    if (nowSeconds < clearingStart)
+        return clearingStart;
+    if (nowSeconds < nextEpochStart)
+        return nextEpochStart;
+    return undefined;
+}
+/**
+ * The cycle-close and outcome dates for a request submitted `now`.
+ *
+ * - The cycle "closes" (stops accepting requests, starts processing) at the
+ *   start of the 48h clearing window, i.e. 48h before the epoch end.
+ * - Processing takes up to 48h, so the outcome is confirmed by the epoch end
+ *   (close + 48h).
+ *
+ * Returns `null` when the epoch boundary is not available or is stale — a
+ * caller then omits the dates entirely (omit, don't stub).
+ *
+ * The common case is a request submitted OUTSIDE the clearing window: the
+ * close is `nextEpochStart − 48h` and the outcome is `nextEpochStart`. When
+ * the request lands INSIDE the current clearing window (that close is already
+ * in the past), it queues for the NEXT weekly cycle, so the close is advanced
+ * by whole weeks until it is in the future.
+ */
+export function deriveCycleDates(nextEpochStart, nowSeconds) {
+    // No boundary loaded, or a stale one that already elapsed — the same
+    // staleness rule as `computeSettlementWindow`.
+    if (!nextEpochStart || nextEpochStart <= nowSeconds)
+        return null;
+    let close = nextEpochStart - CLEARING_WINDOW_SECONDS;
+    let outcome = nextEpochStart;
+    // Inside the current clearing window the close already passed; a request
+    // now is queued for the next weekly cycle.
+    while (close <= nowSeconds) {
+        close += WEEK_SECONDS;
+        outcome += WEEK_SECONDS;
+    }
+    return { close, outcome };
+}
+//# sourceMappingURL=settlement.js.map

package/dist/domain/settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.js","sourceRoot":"","sources":["../../src/domain/settlement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAEpD;;;;GAIG;AACH,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAwBtC;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACpC,UAAU,EACV,cAAc,EACd,qBAAqB,GAAG,uBAAuB,GAC3B;IACpB,qEAAqE;IACrE,IAAI,cAAc,IAAI,CAAC,IAAI,cAAc,IAAI,UAAU,EAAE,CAAC;QACtD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,aAAa,GAAG,cAAc,GAAG,qBAAqB,CAAC;IAE7D,IAAI,UAAU,GAAG,aAAa,EAAE,CAAC;QAC7B,OAAO;YACH,KAAK,EAAE,UAAU;YACjB,oBAAoB,EAAE,aAAa,GAAG,UAAU;YAChD,iBAAiB,EAAE,aAAa;SACnC,CAAC;IACN,CAAC;IAED,wEAAwE;IACxE,OAAO;QACH,KAAK,EAAE,UAAU;QACjB,oBAAoB,EAAE,cAAc,GAAG,UAAU;QACjD,QAAQ,EAAE,cAAc;KAC3B,CAAC;AACN,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC7B,cAAkC,EAClC,UAAkB,EAClB,wBAAgC,uBAAuB;IAEvD,IAAI,CAAC,cAAc,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7D,MAAM,aAAa,GAAG,cAAc,GAAG,qBAAqB,CAAC;IAC7D,IAAI,UAAU,GAAG,aAAa;QAAE,OAAO,aAAa,CAAC;IACrD,IAAI,UAAU,GAAG,cAAc;QAAE,OAAO,cAAc,CAAC;IACvD,OAAO,SAAS,CAAC;AACrB,CAAC;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAC5B,cAAkC,EAClC,UAAkB;IAElB,qEAAqE;IACrE,+CAA+C;IAC/C,IAAI,CAAC,cAAc,IAAI,cAAc,IAAI,UAAU;QAAE,OAAO,IAAI,CAAC;IAEjE,IAAI,KAAK,GAAG,cAAc,GAAG,uBAAuB,CAAC;IACrD,IAAI,OAAO,GAAG,cAAc,CAAC;IAC7B,yEAAyE;IACzE,2CAA2C;IAC3C,OAAO,KAAK,IAAI,UAAU,EAAE,CAAC;QACzB,KAAK,IAAI,YAAY,CAAC;QACtB,OAAO,IAAI,YAAY,CAAC;IAC5B,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/domain/settlement.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/settlement.test.js

@@ -0,0 +1,152 @@
+import { CLEARING_WINDOW_SECONDS, computeSettlementWindow, deriveCycleDates, nextCycleBoundary, } from './settlement';
+/**
+ * Ported from kasu-ui `src/features/portfolio/lib/settlement-window.test.ts`
+ * and the non-format half of
+ * `src/features/lending/lib/cycle-dates.test.ts`. The `formatCycleDate` /
+ * `formatCycleCloseUtc` cases stay there — they assert printed words.
+ */
+const HOUR = 60 * 60;
+const DAY = 24 * HOUR;
+const CLEARING = 48 * HOUR;
+const WEEK = 7 * DAY;
+describe('computeSettlementWindow', () => {
+    it('returns "unknown" when the epoch boundary is missing', () => {
+        expect(computeSettlementWindow({
+            nowSeconds: 1000000,
+            nextEpochStart: 0,
+        })).toEqual({ phase: 'unknown' });
+    });
+    it('returns "unknown" when the epoch boundary is stale (already elapsed)', () => {
+        expect(computeSettlementWindow({
+            nowSeconds: 1000000,
+            nextEpochStart: 999000,
+        })).toEqual({ phase: 'unknown' });
+    });
+    it('counts down to the clearing window when more than 48h from epoch end', () => {
+        const epochEnd = 1700000000; // Thu 06:00 UTC
+        const now = epochEnd - 3 * DAY; // 24h before the window opens
+        const result = computeSettlementWindow({
+            nowSeconds: now,
+            nextEpochStart: epochEnd,
+        });
+        expect(result.phase).toBe('awaiting');
+        if (result.phase !== 'awaiting')
+            return;
+        expect(result.nextClearingStart).toBe(epochEnd - CLEARING); // Tue 06:00
+        expect(result.secondsUntilClearing).toBe(DAY);
+    });
+    it('reports "clearing" only inside the 48h window before epoch end', () => {
+        const epochEnd = 1700000000;
+        const now = epochEnd - 24 * HOUR; // 24h into the window
+        const result = computeSettlementWindow({
+            nowSeconds: now,
+            nextEpochStart: epochEnd,
+        });
+        expect(result.phase).toBe('clearing');
+        if (result.phase !== 'clearing')
+            return;
+        expect(result.epochEnd).toBe(epochEnd);
+        expect(result.secondsUntilEpochEnd).toBe(24 * HOUR);
+    });
+    it('flips awaiting → clearing exactly at the window boundary (T-48h)', () => {
+        const epochEnd = 1700000000;
+        expect(computeSettlementWindow({
+            nowSeconds: epochEnd - CLEARING - 1,
+            nextEpochStart: epochEnd,
+        }).phase).toBe('awaiting');
+        expect(computeSettlementWindow({
+            nowSeconds: epochEnd - CLEARING,
+            nextEpochStart: epochEnd,
+        }).phase).toBe('clearing');
+    });
+    it('respects a non-default clearing window length', () => {
+        const epochEnd = 1700000000;
+        const now = epochEnd - 36 * HOUR;
+        // 36h out is "clearing" under the default 48h window but "awaiting"
+        // under a 24h one.
+        expect(computeSettlementWindow({
+            nowSeconds: now,
+            nextEpochStart: epochEnd,
+        }).phase).toBe('clearing');
+        expect(computeSettlementWindow({
+            nowSeconds: now,
+            nextEpochStart: epochEnd,
+            clearingWindowSeconds: 24 * HOUR,
+        }).phase).toBe('awaiting');
+    });
+});
+describe('nextCycleBoundary', () => {
+    const epochEnd = 1700000000;
+    const clearingStart = epochEnd - CLEARING;
+    it('returns the cycle close while the window is still ahead', () => {
+        expect(nextCycleBoundary(epochEnd, epochEnd - 3 * DAY)).toBe(clearingStart);
+    });
+    it('returns the epoch end once inside the clearing window', () => {
+        expect(nextCycleBoundary(epochEnd, clearingStart + 1)).toBe(epochEnd);
+    });
+    it('hands over from close to epoch end exactly at the boundary instant', () => {
+        // At T-48h the close has just been reached, so the next thing to wait
+        // for is the epoch end — not the instant we are standing on.
+        expect(nextCycleBoundary(epochEnd, clearingStart - 1)).toBe(clearingStart);
+        expect(nextCycleBoundary(epochEnd, clearingStart)).toBe(epochEnd);
+    });
+    it('returns undefined when there is nothing left to wait for', () => {
+        expect(nextCycleBoundary(epochEnd, epochEnd)).toBeUndefined(); // elapsed
+        expect(nextCycleBoundary(epochEnd, epochEnd + DAY)).toBeUndefined(); // stale
+        expect(nextCycleBoundary(undefined, epochEnd - DAY)).toBeUndefined(); // not loaded
+        expect(nextCycleBoundary(0, epochEnd - DAY)).toBeUndefined(); // sentinel zero
+    });
+    it('agrees with computeSettlementWindow about where the window opens', () => {
+        // One number, two consumers: the phase machine and the timer helper
+        // must never disagree about when the cycle turns.
+        expect(CLEARING_WINDOW_SECONDS).toBe(CLEARING);
+        const justInside = nextCycleBoundary(epochEnd, clearingStart);
+        expect(computeSettlementWindow({
+            nowSeconds: clearingStart,
+            nextEpochStart: epochEnd,
+        }).phase).toBe('clearing');
+        expect(justInside).toBe(epochEnd);
+    });
+    it('respects a non-default clearing window length', () => {
+        const now = epochEnd - 36 * HOUR;
+        // 36h out: inside a 48h window (next stop is the epoch end), still
+        // ahead of a 24h one (next stop is that window opening).
+        expect(nextCycleBoundary(epochEnd, now)).toBe(epochEnd);
+        expect(nextCycleBoundary(epochEnd, now, 24 * HOUR)).toBe(epochEnd - 24 * HOUR);
+    });
+});
+describe('deriveCycleDates', () => {
+    // Fixture: epoch end = Thu 6 Aug 2026, 06:00 UTC.
+    const EPOCH_END = Date.UTC(2026, 7, 6, 6, 0, 0) / 1000; // 1785996000
+    const CLOSE = EPOCH_END - CLEARING; // Tue 4 Aug 06:00 UTC
+    it('returns close = epochEnd − 48h and outcome = epochEnd before the window opens', () => {
+        const now = Date.UTC(2026, 7, 1, 12, 0, 0) / 1000; // Sat 1 Aug
+        expect(deriveCycleDates(EPOCH_END, now)).toEqual({
+            close: CLOSE,
+            outcome: EPOCH_END,
+        });
+    });
+    it('advances to the next weekly cycle when the request lands inside the clearing window', () => {
+        // now is Wed 5 Aug 00:00 — inside [close, epochEnd): this cycle has
+        // already closed, so the request queues for next week.
+        const now = Date.UTC(2026, 7, 5, 0, 0, 0) / 1000;
+        expect(deriveCycleDates(EPOCH_END, now)).toEqual({
+            close: CLOSE + WEEK,
+            outcome: EPOCH_END + WEEK,
+        });
+    });
+    it('returns null when the epoch boundary is missing', () => {
+        expect(deriveCycleDates(undefined, EPOCH_END - WEEK)).toBeNull();
+        expect(deriveCycleDates(0, EPOCH_END - WEEK)).toBeNull();
+    });
+    it('returns null when the epoch boundary is stale (already elapsed)', () => {
+        expect(deriveCycleDates(EPOCH_END, EPOCH_END + 60)).toBeNull();
+    });
+    it('runs on the same window constant as the phase machine', () => {
+        var _a;
+        const now = Date.UTC(2026, 7, 1, 12, 0, 0) / 1000;
+        const dates = deriveCycleDates(EPOCH_END, now);
+        expect(dates === null || dates === void 0 ? void 0 : dates.outcome).toBe(((_a = dates === null || dates === void 0 ? void 0 : dates.close) !== null && _a !== void 0 ? _a : 0) + CLEARING_WINDOW_SECONDS);
+    });
+});
+//# sourceMappingURL=settlement.test.js.map

package/dist/domain/settlement.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.test.js","sourceRoot":"","sources":["../../src/domain/settlement.test.ts"],"names":[],"mappings":"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"}

package/dist/domain/tranche-display-name.d.ts

@@ -0,0 +1,17 @@
+import { PoolNameSignal } from './partners';
+export declare const UPPER_MEZZANINE = "Upper Mezzanine";
+/**
+ * User-facing display name for a tranche. Maps `Senior` → `Upper Mezzanine`
+ * on Apxium pools (identified by pool name, see `partners.ts`); every other
+ * tranche/pool combination passes through unchanged.
+ *
+ * Call this at the view-model boundary (options, cards, transaction views),
+ * NEVER in matching/sorting logic — `compareTrancheSeniority` and
+ * `pickDefaultTrancheId` rank by the raw subgraph name and must keep doing so.
+ * This is the one function in `domain/` that returns a user-visible string,
+ * and it is here rather than in each frontend so all three cannot drift.
+ *
+ * `pool` accepts the raw `PoolOverview` (`poolName`), the facade `Strategy`
+ * (`name`), or the name itself.
+ */
+export declare function getTrancheDisplayName(trancheName: string, pool: PoolNameSignal): string;

package/dist/domain/tranche-display-name.js

@@ -0,0 +1,30 @@
+import { APXIUM, getCreditOriginator } from './partners';
+// Business rename (2026-07): Apxium strategies market their top retail tranche
+// as "Upper Mezzanine" — the true senior position is held by the institutional
+// lender (Rixon Capital), so retail lenders are never actually senior in the
+// waterfall. Display-only: subgraph/SDK tranche names, ids and any
+// seniority-ranking logic keep the on-chain "Senior" name.
+export const UPPER_MEZZANINE = 'Upper Mezzanine';
+const SENIOR = 'senior';
+/**
+ * User-facing display name for a tranche. Maps `Senior` → `Upper Mezzanine`
+ * on Apxium pools (identified by pool name, see `partners.ts`); every other
+ * tranche/pool combination passes through unchanged.
+ *
+ * Call this at the view-model boundary (options, cards, transaction views),
+ * NEVER in matching/sorting logic — `compareTrancheSeniority` and
+ * `pickDefaultTrancheId` rank by the raw subgraph name and must keep doing so.
+ * This is the one function in `domain/` that returns a user-visible string,
+ * and it is here rather than in each frontend so all three cannot drift.
+ *
+ * `pool` accepts the raw `PoolOverview` (`poolName`), the facade `Strategy`
+ * (`name`), or the name itself.
+ */
+export function getTrancheDisplayName(trancheName, pool) {
+    if (trancheName.trim().toLowerCase() !== SENIOR)
+        return trancheName;
+    return getCreditOriginator(pool).name === APXIUM.name
+        ? UPPER_MEZZANINE
+        : trancheName;
+}
+//# sourceMappingURL=tranche-display-name.js.map

package/dist/domain/tranche-display-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tranche-display-name.js","sourceRoot":"","sources":["../../src/domain/tranche-display-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAkB,MAAM,YAAY,CAAC;AAEzE,+EAA+E;AAC/E,+EAA+E;AAC/E,6EAA6E;AAC7E,mEAAmE;AACnE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CACjC,WAAmB,EACnB,IAAoB;IAEpB,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM;QAAE,OAAO,WAAW,CAAC;IACpE,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QACjD,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,WAAW,CAAC;AACtB,CAAC"}

package/dist/domain/tranche-display-name.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/tranche-display-name.test.js

@@ -0,0 +1,58 @@
+import { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
+// Ported from kasu-ui `src/features/lending/lib/tranche-display-name.test.ts`.
+describe('getTrancheDisplayName', () => {
+    it('renames Senior to Upper Mezzanine on Apxium pools', () => {
+        expect(getTrancheDisplayName('Senior', {
+            poolName: 'Taxation Funding (Tax Pay)',
+        })).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior', {
+            poolName: 'Professional Fee Funding',
+        })).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior', { poolName: 'Whole Ledger Funding' })).toBe(UPPER_MEZZANINE);
+    });
+    it('keeps Senior on non-Apxium (InvoiceMate) pools', () => {
+        expect(getTrancheDisplayName('Senior', {
+            poolName: 'Payment Finance (PayFi) - Clearing Houses',
+        })).toBe('Senior');
+    });
+    it('never touches other tranche names, on any pool', () => {
+        expect(getTrancheDisplayName('Mezzanine', { poolName: 'Taxation Funding' })).toBe('Mezzanine');
+        expect(getTrancheDisplayName('Junior', { poolName: 'Taxation Funding' })).toBe('Junior');
+        expect(getTrancheDisplayName('Mezzanine', {
+            poolName: 'Payment Finance (PayFi)',
+        })).toBe('Mezzanine');
+    });
+    it('matches the Senior name case-insensitively but preserves unknown names verbatim', () => {
+        expect(getTrancheDisplayName('SENIOR', { poolName: 'Taxation Funding' })).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior Plus', { poolName: 'Taxation Funding' })).toBe('Senior Plus');
+    });
+    it('treats missing pool names as Apxium (matches getCreditOriginator default)', () => {
+        // getCreditOriginator defaults unknown pools to Apxium; the display
+        // name must follow the same rule or the two surfaces would disagree.
+        expect(getTrancheDisplayName('Senior', { poolName: '' })).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior', {})).toBe(UPPER_MEZZANINE);
+    });
+});
+describe('getTrancheDisplayName — the widened PoolNameSignal', () => {
+    it('accepts the facade Strategy shape (`name`)', () => {
+        expect(getTrancheDisplayName('Senior', { name: 'Taxation Funding' })).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior', {
+            name: 'Payment Finance (PayFi)',
+        })).toBe('Senior');
+    });
+    it('accepts a bare pool name', () => {
+        expect(getTrancheDisplayName('Senior', 'Whole Ledger Funding')).toBe(UPPER_MEZZANINE);
+        expect(getTrancheDisplayName('Senior', 'Payment Finance (PayFi)')).toBe('Senior');
+    });
+    it('gives the same answer for the raw and facade shapes of one pool', () => {
+        for (const poolName of [
+            'Taxation Funding (Tax Pay)',
+            'Payment Finance (PayFi)',
+            'Whole Ledger Funding',
+            '',
+        ]) {
+            expect(getTrancheDisplayName('Senior', { poolName })).toBe(getTrancheDisplayName('Senior', { name: poolName }));
+        }
+    });
+});
+//# sourceMappingURL=tranche-display-name.test.js.map

package/dist/domain/tranche-display-name.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tranche-display-name.test.js","sourceRoot":"","sources":["../../src/domain/tranche-display-name.test.ts"],"names":[],"mappings":"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"}

package/dist/domain/tranches.d.ts

@@ -0,0 +1,89 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+/**
+ * Minimum remaining capacity (in stable-asset units) for a tranche to be
+ * selectable. Mirrors `MIN_CAPACITY = toBigNumber('1')` in kasu-fe-next's
+ * lending modal after its `formatEther`. Anything below this is rounding
+ * noise — the SDK's own capacity arithmetic routinely leaves sub-cent dust
+ * behind.
+ */
+export declare const MIN_TRANCHE_CAPACITY = 1;
+/**
+ * Remaining capacity as it reaches this layer. `TrancheData` (raw, from the
+ * data service) calls it `poolCapacity`; the facade's `StrategyTranche` calls
+ * the same number `availableCapacity`. Accepting both keeps ONE capacity gate
+ * for the whole SDK rather than a duplicate per shape.
+ */
+export type TrancheCapacitySignal = {
+    poolCapacity: string;
+} | {
+    availableCapacity: string;
+};
+export declare function trancheHasCapacity(tranche: TrancheCapacitySignal): boolean;
+/**
+ * Whole-strategy capacity gate: true when the pool has tranches but none of
+ * them has remaining capacity. Drives a lend form's full-capacity message and
+ * its step-counter suppression.
+ */
+export declare function poolAllTranchesFull(pool: PoolOverview): boolean;
+export type PoolStatus = 'Live' | 'Full' | 'Coming soon';
+/**
+ * The status CODE for a pool. A code, not copy: consumers map it to their own
+ * wording and locale.
+ */
+export declare function derivePoolStatus(pool: PoolOverview): PoolStatus;
+export declare function trancheRiskRank(tranche: TrancheData): number;
+/**
+ * Comparator that orders tranches SAFEST-FIRST (Senior → Mezzanine → Junior)
+ * by the same name-based risk rank the default-pick uses. Ranks by the RAW
+ * subgraph name, so the Apxium "Upper Mezzanine" display rename never reaches
+ * here. Ties (incl. unrecognised names, which both rank last) keep their input
+ * order under a stable sort. Used by a lend dropdown to list the least-risky
+ * option first.
+ */
+export declare function compareTrancheSeniority(a: TrancheData, b: TrancheData): number;
+/**
+ * Capacity-aware default tranche pick: the LOWEST-risk tranche that still has
+ * capacity, so a new lender lands on the safest available option. Riskier
+ * tranches remain a deliberate opt-in — we must never pre-select the
+ * highest-risk Junior (audit 3.2). When every tranche is full we fall back to
+ * the lowest-risk one regardless, so a form still mounts in a known state
+ * (the dropdown marks it full and the submit gate blocks progress).
+ */
+export declare function pickDefaultTrancheId(pool: PoolOverview): string;
+/** A closed APY range, both bounds as 0..1 fractions. */
+export interface ApyBounds {
+    min: number;
+    max: number;
+}
+/**
+ * GROSS APY range across a pool's tranches — the numeric core of kasu-ui's
+ * `formatTrancheApyRange`. Each `TrancheData` carries `minApy`/`maxApy`
+ * derived from the base rate plus any fixed-term configs (`data-service.ts`).
+ *
+ * Zero and negative values are skipped — an unset/missing rate (e.g. a tranche
+ * with no fixed-term config) must not drag the range down to `0–10.5%`.
+ * `null` when nothing usable remains, which is the caller's cue to render its
+ * "no rate" state rather than a confident zero.
+ *
+ * The min is taken over `minApy` and the max over `maxApy`, so a single
+ * unusable side collapses the whole range to `null` rather than half a range.
+ *
+ * Formatting is NOT here. The rule that two bounds printing the same figure
+ * collapse to one is decided on the rendered digits, so it belongs with the
+ * formatter that produces them (kasu-ui `format-tranche-apy.ts`).
+ */
+export declare function trancheApyBounds(tranches: TrancheData[]): ApyBounds | null;
+/**
+ * The same range as NET Effective Interest Rates — each bound through
+ * `netEffectiveApy`.
+ *
+ * FAIL CLOSED: `null` when either bound comes back non-finite or ≤ 0, so an
+ * out-of-domain fee or a rate-less pool can never be rendered as a confident
+ * figure. A caller that does not yet know the fee must not substitute `0` —
+ * a fee-less rate overstates the figure by up to 3.4pp with nothing on screen
+ * saying so; it should skip the call and render its unavailable state.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ *   See `netEffectiveApy` for why the units matter.
+ */
+export declare function netTrancheApyBounds(tranches: TrancheData[], feePercent: number): ApyBounds | null;

package/dist/domain/tranches.js

@@ -0,0 +1,150 @@
+import { netEffectiveApy } from './rates';
+/**
+ * Minimum remaining capacity (in stable-asset units) for a tranche to be
+ * selectable. Mirrors `MIN_CAPACITY = toBigNumber('1')` in kasu-fe-next's
+ * lending modal after its `formatEther`. Anything below this is rounding
+ * noise — the SDK's own capacity arithmetic routinely leaves sub-cent dust
+ * behind.
+ */
+export const MIN_TRANCHE_CAPACITY = 1;
+export function trancheHasCapacity(tranche) {
+    const raw = 'poolCapacity' in tranche
+        ? tranche.poolCapacity
+        : tranche.availableCapacity;
+    const remaining = parseFloat(raw);
+    return Number.isFinite(remaining) && remaining >= MIN_TRANCHE_CAPACITY;
+}
+/**
+ * Whole-strategy capacity gate: true when the pool has tranches but none of
+ * them has remaining capacity. Drives a lend form's full-capacity message and
+ * its step-counter suppression.
+ */
+export function poolAllTranchesFull(pool) {
+    return pool.tranches.length > 0 && !pool.tranches.some(trancheHasCapacity);
+}
+/**
+ * The status CODE for a pool. A code, not copy: consumers map it to their own
+ * wording and locale.
+ */
+export function derivePoolStatus(pool) {
+    if (!pool.enabled)
+        return 'Coming soon';
+    if (poolAllTranchesFull(pool))
+        return 'Full';
+    return 'Live';
+}
+/**
+ * Seniority rank of a tranche by name — LOWER is less risky. The credit
+ * waterfall is Senior (repaid first, lowest risk) → Mezzanine → Junior
+ * (repaid last, highest risk). APY is NOT a reliable proxy (a pool can price
+ * its Senior tranche above its Mezzanine), so risk is ranked by name.
+ * Unrecognised names sort last, so a known-safe tranche always wins the
+ * default. Ranks by the RAW subgraph name — the Apxium "Upper Mezzanine"
+ * rename is display-only and must never reach here (see
+ * `tranche-display-name.ts`).
+ */
+const TRANCHE_RISK_RANK = {
+    senior: 0,
+    mezzanine: 1,
+    junior: 2,
+};
+// `name` is typed `string` on `TrancheData` but arrives from the subgraph, so
+// it is taken as possibly missing here: an unnamed tranche ranks last rather
+// than throwing on `.trim()`.
+function riskRankOfName(name) {
+    var _a, _b;
+    return ((_b = TRANCHE_RISK_RANK[(_a = name === null || name === void 0 ? void 0 : name.trim().toLowerCase()) !== null && _a !== void 0 ? _a : '']) !== null && _b !== void 0 ? _b : Number.POSITIVE_INFINITY);
+}
+export function trancheRiskRank(tranche) {
+    return riskRankOfName(tranche.name);
+}
+/**
+ * Comparator that orders tranches SAFEST-FIRST (Senior → Mezzanine → Junior)
+ * by the same name-based risk rank the default-pick uses. Ranks by the RAW
+ * subgraph name, so the Apxium "Upper Mezzanine" display rename never reaches
+ * here. Ties (incl. unrecognised names, which both rank last) keep their input
+ * order under a stable sort. Used by a lend dropdown to list the least-risky
+ * option first.
+ */
+export function compareTrancheSeniority(a, b) {
+    const ra = trancheRiskRank(a);
+    const rb = trancheRiskRank(b);
+    if (ra === rb)
+        return 0;
+    return ra < rb ? -1 : 1;
+}
+/**
+ * Capacity-aware default tranche pick: the LOWEST-risk tranche that still has
+ * capacity, so a new lender lands on the safest available option. Riskier
+ * tranches remain a deliberate opt-in — we must never pre-select the
+ * highest-risk Junior (audit 3.2). When every tranche is full we fall back to
+ * the lowest-risk one regardless, so a form still mounts in a known state
+ * (the dropdown marks it full and the submit gate blocks progress).
+ */
+export function pickDefaultTrancheId(pool) {
+    const withCapacity = pool.tranches.filter(trancheHasCapacity);
+    const candidates = withCapacity.length > 0 ? withCapacity : pool.tranches;
+    if (candidates.length === 0)
+        return '';
+    return candidates.reduce((best, t) => trancheRiskRank(t) < trancheRiskRank(best) ? t : best).id;
+}
+/**
+ * GROSS APY range across a pool's tranches — the numeric core of kasu-ui's
+ * `formatTrancheApyRange`. Each `TrancheData` carries `minApy`/`maxApy`
+ * derived from the base rate plus any fixed-term configs (`data-service.ts`).
+ *
+ * Zero and negative values are skipped — an unset/missing rate (e.g. a tranche
+ * with no fixed-term config) must not drag the range down to `0–10.5%`.
+ * `null` when nothing usable remains, which is the caller's cue to render its
+ * "no rate" state rather than a confident zero.
+ *
+ * The min is taken over `minApy` and the max over `maxApy`, so a single
+ * unusable side collapses the whole range to `null` rather than half a range.
+ *
+ * Formatting is NOT here. The rule that two bounds printing the same figure
+ * collapse to one is decided on the rendered digits, so it belongs with the
+ * formatter that produces them (kasu-ui `format-tranche-apy.ts`).
+ */
+export function trancheApyBounds(tranches) {
+    if (tranches.length === 0)
+        return null;
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    for (const t of tranches) {
+        const min = parseFloat(t.minApy);
+        const max = parseFloat(t.maxApy);
+        if (Number.isFinite(min) && min > 0)
+            lo = Math.min(lo, min);
+        if (Number.isFinite(max) && max > 0)
+            hi = Math.max(hi, max);
+    }
+    if (!Number.isFinite(lo) || !Number.isFinite(hi))
+        return null;
+    return { min: lo, max: hi };
+}
+/**
+ * The same range as NET Effective Interest Rates — each bound through
+ * `netEffectiveApy`.
+ *
+ * FAIL CLOSED: `null` when either bound comes back non-finite or ≤ 0, so an
+ * out-of-domain fee or a rate-less pool can never be rendered as a confident
+ * figure. A caller that does not yet know the fee must not substitute `0` —
+ * a fee-less rate overstates the figure by up to 3.4pp with nothing on screen
+ * saying so; it should skip the call and render its unavailable state.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ *   See `netEffectiveApy` for why the units matter.
+ */
+export function netTrancheApyBounds(tranches, feePercent) {
+    const gross = trancheApyBounds(tranches);
+    if (!gross)
+        return null;
+    const min = netEffectiveApy(gross.min, feePercent);
+    const max = netEffectiveApy(gross.max, feePercent);
+    if (!Number.isFinite(min) || min <= 0)
+        return null;
+    if (!Number.isFinite(max) || max <= 0)
+        return null;
+    return { min, max };
+}
+//# sourceMappingURL=tranches.js.map