@kasufinance/kasu-sdk 2.4.2 → 2.5.0

package/src/domain/deposit-bounds.test.ts

@@ -0,0 +1,200 @@
+import * as fc from 'fast-check';
+
+import { TrancheData } from '../services/DataService/types';
+
+import {
+    ceilToCents,
+    floorToCents,
+    isBelowMinimumCapacity,
+    MAX_LENDING_AMOUNT_FALLBACK,
+    MIN_LENDING_AMOUNT_FALLBACK,
+    parseTrancheBound,
+    resolveBoundShortcuts,
+    resolveDepositBounds,
+} from './deposit-bounds';
+
+/**
+ * Ported from kasu-ui `src/features/lending/lib/tranche-bounds.property.test.ts`,
+ * with the `resolveDepositBounds` / `parseTrancheBound` cases the property file
+ * did not cover.
+ *
+ * The Min/Max shortcuts (clickable bound labels on a lend form) must never
+ * write an amount the form rejects, so the snapping is checked as invariants
+ * over the whole input domain rather than at a few hand-picked values.
+ */
+
+function tranche(over: Partial<TrancheData>): TrancheData {
+    return {
+        minimumDeposit: '500',
+        maximumDeposit: '500000',
+        poolCapacity: '250000',
+        ...over,
+    } as unknown as TrancheData;
+}
+
+const amountArb = fc.double({
+    min: 0,
+    max: 1e12,
+    noNaN: true,
+    noDefaultInfinity: true,
+});
+/** `String(k / 100)` prints at most two decimals for any integer `k` in range. */
+const AT_MOST_TWO_DP = /^\d+(\.\d{1,2})?$/;
+
+describe('parseTrancheBound', () => {
+    it('accepts a positive finite bound from a string or a number', () => {
+        expect(parseTrancheBound('500')).toBe(500);
+        expect(parseTrancheBound(500)).toBe(500);
+    });
+
+    it('rejects anything that is not a usable bound', () => {
+        expect(parseTrancheBound(null)).toBeNull();
+        expect(parseTrancheBound(undefined)).toBeNull();
+        expect(parseTrancheBound('')).toBeNull();
+        expect(parseTrancheBound('0')).toBeNull();
+        expect(parseTrancheBound('-1')).toBeNull();
+        expect(parseTrancheBound('not-a-number')).toBeNull();
+        expect(parseTrancheBound(Infinity)).toBeNull();
+    });
+});
+
+describe('resolveDepositBounds', () => {
+    it('clamps the max by the tranche’s REMAINING capacity', () => {
+        // A tranche can fill mid-epoch while `maximumDeposit` stays put.
+        expect(
+            resolveDepositBounds(
+                tranche({ maximumDeposit: '500000', poolCapacity: '25285.86' }),
+            ),
+        ).toEqual({ minDeposit: 500, maxDeposit: 25285.86 });
+    });
+
+    it('keeps the configured max when capacity is larger', () => {
+        expect(
+            resolveDepositBounds(
+                tranche({ maximumDeposit: '500000', poolCapacity: '900000' }),
+            ),
+        ).toEqual({ minDeposit: 500, maxDeposit: 500000 });
+    });
+
+    it('falls back when a "coming soon" pool has no bounds configured', () => {
+        expect(
+            resolveDepositBounds(
+                tranche({
+                    minimumDeposit: '0',
+                    maximumDeposit: '0',
+                    poolCapacity: '900000',
+                }),
+            ),
+        ).toEqual({
+            minDeposit: MIN_LENDING_AMOUNT_FALLBACK,
+            maxDeposit: MAX_LENDING_AMOUNT_FALLBACK,
+        });
+    });
+
+    it('uses both fallbacks and skips the capacity clamp with no tranche at all', () => {
+        expect(resolveDepositBounds(undefined)).toEqual({
+            minDeposit: MIN_LENDING_AMOUNT_FALLBACK,
+            maxDeposit: MAX_LENDING_AMOUNT_FALLBACK,
+        });
+    });
+
+    it('treats unparseable or negative capacity as zero', () => {
+        expect(
+            resolveDepositBounds(tranche({ poolCapacity: 'not-a-number' }))
+                .maxDeposit,
+        ).toBe(0);
+        expect(
+            resolveDepositBounds(tranche({ poolCapacity: '-5' })).maxDeposit,
+        ).toBe(0);
+    });
+});
+
+describe('cent snapping', () => {
+    it('floorToCents never exceeds its input, stays within a cent of it, and has ≤ 2dp', () => {
+        fc.assert(
+            fc.property(amountArb, (n) => {
+                const snapped = floorToCents(n);
+                expect(snapped).toBeLessThanOrEqual(n);
+                expect(n - snapped).toBeLessThan(0.02);
+                expect(String(snapped)).toMatch(AT_MOST_TWO_DP);
+            }),
+        );
+    });
+
+    it('ceilToCents never undershoots its input, stays within a cent of it, and has ≤ 2dp', () => {
+        fc.assert(
+            fc.property(amountArb, (n) => {
+                const snapped = ceilToCents(n);
+                expect(snapped).toBeGreaterThanOrEqual(n);
+                expect(snapped - n).toBeLessThan(0.02);
+                expect(String(snapped)).toMatch(AT_MOST_TWO_DP);
+            }),
+        );
+    });
+});
+
+describe('resolveBoundShortcuts', () => {
+    it('keeps both shortcuts inside the validated range whenever they are enabled', () => {
+        fc.assert(
+            fc.property(amountArb, amountArb, (minDeposit, maxDeposit) => {
+                const { min, max, enabled } = resolveBoundShortcuts(
+                    minDeposit,
+                    maxDeposit,
+                );
+                if (!enabled) return;
+                expect(min).toBeGreaterThanOrEqual(minDeposit);
+                expect(max).toBeLessThanOrEqual(maxDeposit);
+                expect(max).toBeGreaterThanOrEqual(min);
+                expect(max).toBeGreaterThan(0);
+            }),
+        );
+    });
+
+    it('disables the pair whenever the snapped range is empty', () => {
+        // Tranche at capacity (max clamps to 0), sub-cent dust the SDK's float
+        // subtraction leaves behind, remaining capacity below the tranche
+        // minimum, and an AU floor above the capacity.
+        expect(resolveBoundShortcuts(500, 0).enabled).toBe(false);
+        expect(
+            resolveBoundShortcuts(500, 1.4551915228366852e-11).enabled,
+        ).toBe(false);
+        expect(resolveBoundShortcuts(500, 137).enabled).toBe(false);
+        expect(resolveBoundShortcuts(240_000, 100_000).enabled).toBe(false);
+    });
+
+    it('snaps SDK float noise onto cents without crossing the bound', () => {
+        expect(resolveBoundShortcuts(500, 249999.99999999997)).toEqual({
+            min: 500,
+            max: 249999.99,
+            enabled: true,
+        });
+        expect(resolveBoundShortcuts(500, 25285.86)).toEqual({
+            min: 500,
+            max: 25285.86,
+            enabled: true,
+        });
+        // An AU remainder with more precision than the field shows rounds UP.
+        expect(resolveBoundShortcuts(358765.432109, 500_000).min).toBe(
+            358765.44,
+        );
+    });
+});
+
+describe('isBelowMinimumCapacity', () => {
+    it('is exactly the negation of the shortcuts being enabled', () => {
+        fc.assert(
+            fc.property(amountArb, amountArb, (minDeposit, maxDeposit) => {
+                // The "nothing to click" and "nothing to type" states must
+                // never be able to disagree.
+                expect(isBelowMinimumCapacity(minDeposit, maxDeposit)).toBe(
+                    !resolveBoundShortcuts(minDeposit, maxDeposit).enabled,
+                );
+            }),
+        );
+    });
+
+    it('flags a capacity that has fallen under the tranche minimum', () => {
+        expect(isBelowMinimumCapacity(500, 137)).toBe(true);
+        expect(isBelowMinimumCapacity(500, 25285.86)).toBe(false);
+    });
+});

package/src/domain/deposit-bounds.ts

@@ -0,0 +1,118 @@
+import { TrancheData } from '../services/DataService/types';
+
+// Fallbacks if the selected tranche's on-chain min/max are 0 / NaN (some
+// "coming soon" pools haven't been configured yet).
+export const MIN_LENDING_AMOUNT_FALLBACK = 500;
+export const MAX_LENDING_AMOUNT_FALLBACK = 500_000;
+
+export function parseTrancheBound(
+    raw: string | number | null | undefined,
+): number | null {
+    if (raw == null) return null;
+    const n = typeof raw === 'string' ? parseFloat(raw) : raw;
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export interface DepositBounds {
+    minDeposit: number;
+    maxDeposit: number;
+}
+
+/**
+ * Min + max lending amount (in whole stable units) for a tranche. The max is
+ * clamped by the tranche's *remaining* capacity: a tranche can fill mid-epoch
+ * while `maximumDeposit` stays at its configured value, so without the clamp
+ * a form would accept an amount the contract will reject. Mirrors
+ * kasu-fe-next's `calculateDepositMinMax` (`trancheMax = min(max, capacity)`).
+ */
+export function resolveDepositBounds(
+    tranche: TrancheData | undefined,
+): DepositBounds {
+    const minDeposit =
+        parseTrancheBound(tranche?.minimumDeposit) ??
+        MIN_LENDING_AMOUNT_FALLBACK;
+    const configuredMax =
+        parseTrancheBound(tranche?.maximumDeposit) ??
+        MAX_LENDING_AMOUNT_FALLBACK;
+    if (!tranche) return { minDeposit, maxDeposit: configuredMax };
+    const remainingCapacity = Math.max(
+        0,
+        parseFloat(tranche.poolCapacity) || 0,
+    );
+    return { minDeposit, maxDeposit: Math.min(configuredMax, remainingCapacity) };
+}
+
+export interface BoundShortcuts {
+    min: number;
+    max: number;
+    enabled: boolean;
+}
+
+/**
+ * The values a lend form's clickable Min/Max labels write into the amount
+ * field. Derived from the validated bounds but snapped to whole cents
+ * CONSERVATIVELY — the min rounds UP, the max rounds DOWN — so a shortcut can
+ * never fill an amount the form's own `min ≤ amount ≤ max` check rejects, and
+ * never carries the SDK's float noise into the field (`targetDrawAmount -
+ * pendingDeposits` routinely yields `249999.99999999997`, which would make the
+ * label, the field's 2dp display and the signed request label all disagree).
+ *
+ * `enabled` is false when the snapped range is empty: a tranche at capacity
+ * (max clamps to 0 or to sub-cent dust), a remaining capacity below the
+ * tranche minimum, or a jurisdiction floor above the capacity. Nothing either
+ * shortcut could write would validate, so both render inert.
+ */
+export function resolveBoundShortcuts(
+    minDeposit: number,
+    maxDeposit: number,
+): BoundShortcuts {
+    const min = ceilToCents(minDeposit);
+    const max = floorToCents(maxDeposit);
+    const enabled =
+        Number.isFinite(min) && Number.isFinite(max) && max > 0 && max >= min;
+    return { min, max, enabled };
+}
+
+/**
+ * True when no amount exists that satisfies both bounds — the minimum sits
+ * ABOVE the maximum, so the range a form would otherwise print ("Min 360,000 ·
+ * Max 25,285") is a contradiction, not an instruction. Happens when a
+ * tranche's remaining capacity falls under its own configured minimum, when it
+ * is at capacity (max 0 / sub-cent dust), or when the AU wholesale cumulative
+ * floor lands above the capacity that is left.
+ *
+ * Defined as the negation of `resolveBoundShortcuts().enabled` on purpose: the
+ * "there is nothing to click" and "there is nothing to type" states must never
+ * be able to disagree.
+ *
+ * This is UX only. The binding minimum is enforced by kasu-backend (403
+ * `AU_WHOLESALE_MINIMUM_NOT_MET`) and by the contract's own bounds; nothing
+ * here may be used to relax either.
+ */
+export function isBelowMinimumCapacity(
+    minDeposit: number,
+    maxDeposit: number,
+): boolean {
+    return !resolveBoundShortcuts(minDeposit, maxDeposit).enabled;
+}
+
+const CENTS = 100;
+
+/**
+ * Largest whole-cent value ≤ `n`. Float multiplication can round `n * 100` UP
+ * onto an integer (`1.15 * 100 === 114.99999999999999` is the usual direction,
+ * but the other happens too), so the result is re-checked against `n` and
+ * stepped down a cent if it overshot — the contract is "never above `n`".
+ */
+export function floorToCents(n: number): number {
+    const k = Math.floor(n * CENTS);
+    const snapped = k / CENTS;
+    return snapped > n ? (k - 1) / CENTS : snapped;
+}
+
+/** Smallest whole-cent value ≥ `n`. Mirror of `floorToCents`: never below `n`. */
+export function ceilToCents(n: number): number {
+    const k = Math.ceil(n * CENTS);
+    const snapped = k / CENTS;
+    return snapped < n ? (k + 1) / CENTS : snapped;
+}

package/src/domain/index.ts

@@ -0,0 +1,70 @@
+/**
+ * The shared domain layer: the rules every Kasu frontend needs to agree on,
+ * in one place instead of three.
+ *
+ * Two rules govern what may live here.
+ *
+ * 1. **Numbers and codes only.** No copy, no locale, no `Intl`, no string a
+ *    user reads — `netEffectiveApy` returns `0.196`, never `'19.60% p.a.'`,
+ *    and `derivePoolStatus` returns the code `'Full'`, not a sentence. The
+ *    formatters that turn these into text stay in each app, where the design
+ *    system and the visitor's locale are. The one exception is
+ *    `getTrancheDisplayName`, which exists precisely because that rename must
+ *    NOT drift between apps.
+ * 2. **Pure.** No network, no clock, no environment. Anything with I/O belongs
+ *    in `facade/` (see `fetchUnusedPoolIds`).
+ */
+export {
+    apyToEpochRate,
+    epochRateToApy,
+    EPOCHS_IN_YEAR,
+    netEffectiveApy,
+} from './rates';
+
+export {
+    ceilToCents,
+    floorToCents,
+    isBelowMinimumCapacity,
+    MAX_LENDING_AMOUNT_FALLBACK,
+    MIN_LENDING_AMOUNT_FALLBACK,
+    parseTrancheBound,
+    resolveBoundShortcuts,
+    resolveDepositBounds,
+} from './deposit-bounds';
+export type { BoundShortcuts, DepositBounds } from './deposit-bounds';
+
+export {
+    APXIUM,
+    getCreditOriginator,
+    getInstitutionalLender,
+    INVOICEMATE,
+    RIXON_CAPITAL,
+} from './partners';
+export type { PoolNameSignal, StrategyPartner } from './partners';
+
+export {
+    maxNetRateCeiling,
+    pickHighestYieldTranche,
+    poolMaxApy,
+    selectVisiblePools,
+} from './pools';
+export type { BestTranche } from './pools';
+
+export { getTrancheDisplayName, UPPER_MEZZANINE } from './tranche-display-name';
+
+export {
+    compareTrancheSeniority,
+    derivePoolStatus,
+    MIN_TRANCHE_CAPACITY,
+    netTrancheApyBounds,
+    pickDefaultTrancheId,
+    poolAllTranchesFull,
+    trancheApyBounds,
+    trancheHasCapacity,
+    trancheRiskRank,
+} from './tranches';
+export type {
+    ApyBounds,
+    PoolStatus,
+    TrancheCapacitySignal,
+} from './tranches';

package/src/domain/partners.test.ts

@@ -0,0 +1,83 @@
+import {
+    APXIUM,
+    getCreditOriginator,
+    getInstitutionalLender,
+    INVOICEMATE,
+    RIXON_CAPITAL,
+} from './partners';
+
+// Ported from kasu-ui `src/features/lending/lib/strategy-partners.test.ts`.
+
+describe('getCreditOriginator', () => {
+    it('maps "Payment Finance (PayFi)" to InvoiceMate', () => {
+        expect(getCreditOriginator({ poolName: 'Payment Finance (PayFi)' })).toBe(
+            INVOICEMATE,
+        );
+    });
+
+    it('keeps Apxium receivables pools as Apxium (regression: do not match "invoice")', () => {
+        // The bug: matching the asset class ("invoice financing") wrongly
+        // classified Apxium receivables pools as InvoiceMate. Name-only
+        // matching fixes it — none of these names contain payfi/payment
+        // finance.
+        expect(getCreditOriginator({ poolName: 'Professional Fee Funding' })).toBe(
+            APXIUM,
+        );
+        expect(getCreditOriginator({ poolName: 'Whole Ledger Funding' })).toBe(
+            APXIUM,
+        );
+        expect(
+            getCreditOriginator({ poolName: 'Taxation Funding (Tax Pay)' }),
+        ).toBe(APXIUM);
+    });
+
+    it('is case-insensitive and matches the "payfi" / "payment finance" name', () => {
+        expect(getCreditOriginator({ poolName: 'payment finance' })).toBe(
+            INVOICEMATE,
+        );
+        expect(getCreditOriginator({ poolName: 'PAYFI Strategy' })).toBe(
+            INVOICEMATE,
+        );
+    });
+
+    it('defaults to Apxium for empty / missing names', () => {
+        expect(getCreditOriginator({ poolName: '' })).toBe(APXIUM);
+        expect(getCreditOriginator({})).toBe(APXIUM);
+    });
+});
+
+describe('getCreditOriginator — the widened PoolNameSignal', () => {
+    it('reads the facade Strategy shape (`name`)', () => {
+        expect(getCreditOriginator({ name: 'Payment Finance (PayFi)' })).toBe(
+            INVOICEMATE,
+        );
+        expect(getCreditOriginator({ name: 'Taxation Funding' })).toBe(APXIUM);
+        expect(getCreditOriginator({ name: null })).toBe(APXIUM);
+    });
+
+    it('reads a bare string', () => {
+        expect(getCreditOriginator('Payment Finance (PayFi)')).toBe(INVOICEMATE);
+        expect(getCreditOriginator('Whole Ledger Funding')).toBe(APXIUM);
+        expect(getCreditOriginator('')).toBe(APXIUM);
+    });
+
+    it('prefers poolName when an object carries both', () => {
+        const both = { poolName: 'Taxation Funding', name: 'Payment Finance' };
+        expect(getCreditOriginator(both)).toBe(APXIUM);
+    });
+
+    it('treats an explicitly null poolName as missing, not as a match', () => {
+        expect(getCreditOriginator({ poolName: null })).toBe(APXIUM);
+        expect(getCreditOriginator({ poolName: undefined })).toBe(APXIUM);
+    });
+});
+
+describe('getInstitutionalLender', () => {
+    it('gives Apxium pools Rixon Capital', () => {
+        expect(getInstitutionalLender(APXIUM)).toBe(RIXON_CAPITAL);
+    });
+
+    it('gives InvoiceMate pools no senior lender', () => {
+        expect(getInstitutionalLender(INVOICEMATE)).toBeNull();
+    });
+});

package/src/domain/partners.ts

@@ -0,0 +1,66 @@
+// Credit Originator + Institutional (senior) Lender are not exposed as Directus
+// or subgraph pool fields, so we derive them from the pool name. Confirmed
+// mapping (2026-06): the only InvoiceMate strategy is "Payment Finance
+// (PayFi)"; every other pool — Whole Ledger / Taxation / Professional Fee
+// Funding — is Apxium. Apxium → Rixon Capital (senior lender); InvoiceMate →
+// none. Replace this with a real Directus field if/when one ships.
+export interface StrategyPartner {
+    name: string;
+    url: string;
+}
+
+export const APXIUM: StrategyPartner = {
+    name: 'Apxium',
+    url: 'https://www.apxium.com/',
+};
+export const INVOICEMATE: StrategyPartner = {
+    name: 'InvoiceMate',
+    url: 'https://invoicemate.net/',
+};
+export const RIXON_CAPITAL: StrategyPartner = {
+    name: 'Rixon Capital',
+    url: 'https://rixon.capital/',
+};
+
+/**
+ * Anything a pool name can arrive as. The raw `PoolOverview` carries
+ * `poolName`, the facade's `Strategy` carries `name`, and a caller who already
+ * has the string can pass it directly — one rule, whichever shape reaches it.
+ * `poolName` wins when an object carries both and it is set.
+ */
+export type PoolNameSignal =
+    | string
+    | { poolName?: string | null }
+    | { name?: string | null };
+
+function poolNameOf(pool: PoolNameSignal): string {
+    if (typeof pool === 'string') return pool;
+    const signal: { poolName?: string | null; name?: string | null } = pool;
+    return signal.poolName ?? signal.name ?? '';
+}
+
+/**
+ * Credit-originator inference by pool NAME only. The sole InvoiceMate
+ * strategy is "Payment Finance (PayFi)" (matched by "payfi" / "payment
+ * finance"); every other pool — Whole Ledger / Taxation / Professional Fee
+ * Funding — is Apxium.
+ *
+ * We deliberately do NOT match on asset class / subheading: Apxium's pools
+ * are receivables/invoice financing, so their asset class contains
+ * "invoice" and would be misclassified as InvoiceMate.
+ */
+export function getCreditOriginator(pool: PoolNameSignal): StrategyPartner {
+    const name = poolNameOf(pool).toLowerCase();
+    if (/payfi|payment finance/.test(name)) return INVOICEMATE;
+    return APXIUM;
+}
+
+/**
+ * Apxium pools carry an institutional senior lender (Rixon Capital);
+ * InvoiceMate pools have none.
+ */
+export function getInstitutionalLender(
+    originator: StrategyPartner,
+): StrategyPartner | null {
+    return originator.name === APXIUM.name ? RIXON_CAPITAL : null;
+}