@kasufinance/kasu-sdk 2.4.2 → 2.6.0

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;
+}

package/src/domain/pools.test.ts

@@ -0,0 +1,260 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+
+import {
+    maxNetRateCeiling,
+    pickHighestYieldTranche,
+    poolMaxApy,
+    selectVisiblePools,
+} from './pools';
+import { netEffectiveApy } from './rates';
+
+/**
+ * Ported from kasu-ui `select-visible-pools.test.ts` and the
+ * `pickHighestYieldTranche` / `formatMaxNetRate` cases of
+ * `pick-best-tranche.test.ts`. The `formatMaxNetRate` assertions are on the
+ * ceiling NUMBER here; their rendered strings stay in kasu-ui.
+ */
+
+function tranche(
+    name: string,
+    apy: string,
+    poolCapacity: string,
+    maxApy?: string,
+): TrancheData {
+    return { id: name, name, apy, poolCapacity, maxApy } as unknown as TrancheData;
+}
+
+function pool(over: Partial<PoolOverview>): PoolOverview {
+    return {
+        id: 'p',
+        poolName: 'p',
+        isActive: true,
+        isOversubscribed: false,
+        tranches: [tranche('Senior', '0.09', '250000', '0.10')],
+        ...over,
+    } as unknown as PoolOverview;
+}
+
+const withCapacity = (): TrancheData[] => [
+    tranche('Senior', '0.09', '250000', '0.10'),
+];
+const noCapacity = (): TrancheData[] => [tranche('Senior', '0.09', '0', '0.10')];
+
+/** The live performance fee on all deployments. */
+const FEE = 10;
+
+describe('poolMaxApy', () => {
+    it('takes the highest usable maxApy across tranches', () => {
+        expect(
+            poolMaxApy(
+                pool({
+                    tranches: [
+                        tranche('Senior', '0.09', '1', '0.10'),
+                        tranche('Junior', '0.12', '1', '0.18'),
+                    ],
+                }),
+            ),
+        ).toBe(0.18);
+    });
+
+    it('is 0 when nothing is usable', () => {
+        expect(poolMaxApy(pool({ tranches: [] }))).toBe(0);
+        expect(
+            poolMaxApy(pool({ tranches: [tranche('Senior', '0.09', '1', 'x')] })),
+        ).toBe(0);
+    });
+});
+
+describe('selectVisiblePools', () => {
+    it('drops inactive pools', () => {
+        const pools = [
+            pool({ id: 'active', isActive: true }),
+            pool({ id: 'inactive', isActive: false }),
+        ];
+        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual(['active']);
+    });
+
+    it('drops oversubscribed pools', () => {
+        const pools = [
+            pool({ id: 'open', isOversubscribed: false }),
+            pool({ id: 'full', isOversubscribed: true }),
+        ];
+        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual(['open']);
+    });
+
+    it('sorts pools with capacity ahead of pools without', () => {
+        const pools = [
+            pool({ id: 'empty', tranches: noCapacity() }),
+            pool({ id: 'has-cap', tranches: withCapacity() }),
+        ];
+        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual([
+            'has-cap',
+            'empty',
+        ]);
+    });
+
+    it('sorts by highest max APY within the same capacity bucket', () => {
+        const pools = [
+            pool({
+                id: 'low',
+                tranches: [tranche('Senior', '0.08', '250000', '0.08')],
+            }),
+            pool({
+                id: 'high',
+                tranches: [tranche('Senior', '0.15', '250000', '0.15')],
+            }),
+        ];
+        expect(selectVisiblePools(pools).map((p) => p.id)).toEqual([
+            'high',
+            'low',
+        ]);
+    });
+
+    it('does not mutate the input array', () => {
+        const pools = [
+            pool({ id: 'a', tranches: noCapacity() }),
+            pool({ id: 'b', tranches: withCapacity() }),
+        ];
+        const before = pools.map((p) => p.id);
+        selectVisiblePools(pools);
+        expect(pools.map((p) => p.id)).toEqual(before);
+    });
+});
+
+describe('pickHighestYieldTranche', () => {
+    const named = (poolName: string, tranches: TrancheData[]): PoolOverview =>
+        pool({ id: poolName, poolName, tranches });
+
+    it('returns null for empty / nullish input', () => {
+        expect(pickHighestYieldTranche(undefined)).toBeNull();
+        expect(pickHighestYieldTranche(null)).toBeNull();
+        expect(pickHighestYieldTranche([])).toBeNull();
+    });
+
+    it('picks the highest base APY across all pools with capacity', () => {
+        const best = pickHighestYieldTranche([
+            named('A', [tranche('Junior', '0.12', '5000')]),
+            named('B', [
+                tranche('Senior', '0.18', '5000'),
+                tranche('Mezz', '0.15', '5000'),
+            ]),
+        ]);
+        expect(best?.pool.poolName).toBe('B');
+        expect(best?.tranche.name).toBe('Senior');
+        expect(best?.apy).toBeCloseTo(0.18);
+    });
+
+    it('skips tranches without capacity (< 1 unit)', () => {
+        const best = pickHighestYieldTranche([
+            named('Full', [tranche('Junior', '0.30', '0')]),
+            named('Live', [tranche('Senior', '0.10', '2000')]),
+        ]);
+        expect(best?.pool.poolName).toBe('Live');
+        expect(best?.apy).toBeCloseTo(0.1);
+    });
+
+    it('breaks APY ties toward more remaining capacity', () => {
+        const best = pickHighestYieldTranche([
+            named('Small', [tranche('Junior', '0.15', '1000')]),
+            named('Big', [tranche('Junior', '0.15', '9000')]),
+        ]);
+        expect(best?.pool.poolName).toBe('Big');
+    });
+
+    it('ignores zero / non-finite APY values', () => {
+        const best = pickHighestYieldTranche([
+            named('Zero', [tranche('Junior', '0', '5000')]),
+            named('NaN', [tranche('Junior', 'not-a-number', '5000')]),
+            named('Real', [tranche('Junior', '0.09', '5000')]),
+        ]);
+        expect(best?.pool.poolName).toBe('Real');
+    });
+
+    it('reads the BASE rate, not the FTD-widened maxApy', () => {
+        // A ceiling claim and a named tranche's rate are different statements.
+        const best = pickHighestYieldTranche([
+            named('A', [tranche('Junior', '0.12', '5000', '0.30')]),
+            named('B', [tranche('Senior', '0.18', '5000', '0.18')]),
+        ]);
+        expect(best?.pool.poolName).toBe('B');
+    });
+});
+
+describe('maxNetRateCeiling', () => {
+    const named = (poolName: string, tranches: TrancheData[]): PoolOverview =>
+        pool({ id: poolName, poolName, tranches });
+
+    it('returns the highest ceiling across all pools, net of the fee', () => {
+        const rate = maxNetRateCeiling(
+            [
+                named('A', [tranche('Junior', '0.12', '5000', '0.18')]),
+                named('B', [tranche('Senior', '0.10', '5000', '0.22')]),
+            ],
+            FEE,
+        );
+        // 0.22 gross → 19.60% net, the same arithmetic as everywhere else.
+        expect(rate).toBe(netEffectiveApy(0.22, FEE));
+        expect(rate).toBeCloseTo(0.196, 4);
+    });
+
+    it('prefers the FTD-inclusive maxApy over the base rate', () => {
+        // The strategies card's range tops out at maxApy; an "up to" claim
+        // quoting the base rate would contradict it on the same screen.
+        expect(
+            maxNetRateCeiling(
+                [named('A', [tranche('Junior', '0.10', '5000', '0.22')])],
+                FEE,
+            ),
+        ).toBe(netEffectiveApy(0.22, FEE));
+    });
+
+    it('falls back to the base rate when a tranche carries no maxApy', () => {
+        expect(
+            maxNetRateCeiling(
+                [named('A', [tranche('Junior', '0.22', '5000')])],
+                FEE,
+            ),
+        ).toBe(netEffectiveApy(0.22, FEE));
+    });
+
+    it('skips tranches without capacity — an unreachable rate is not a claim', () => {
+        const rate = maxNetRateCeiling(
+            [
+                named('Full', [tranche('Junior', '0.30', '0', '0.30')]),
+                named('Live', [tranche('Senior', '0.10', '5000', '0.10')]),
+            ],
+            FEE,
+        );
+        expect(rate).toBe(netEffectiveApy(0.1, FEE));
+        expect(rate).toBeCloseTo(0.0896, 4);
+    });
+
+    it('returns null rather than a gross figure when the fee is out of domain', () => {
+        const pools = [named('A', [tranche('Junior', '0.22', '5000', '0.22')])];
+        expect(maxNetRateCeiling(pools, 1000)).toBeNull();
+        expect(maxNetRateCeiling(pools, -1)).toBeNull();
+        expect(maxNetRateCeiling(pools, NaN)).toBeNull();
+        // A 100% fee leaves nothing to claim.
+        expect(maxNetRateCeiling(pools, 100)).toBeNull();
+    });
+
+    it('returns null for empty, nullish or rate-less input', () => {
+        expect(maxNetRateCeiling(undefined, FEE)).toBeNull();
+        expect(maxNetRateCeiling(null, FEE)).toBeNull();
+        expect(maxNetRateCeiling([], FEE)).toBeNull();
+        expect(
+            maxNetRateCeiling(
+                [named('Zero', [tranche('Junior', '0', '5000', '0')])],
+                FEE,
+            ),
+        ).toBeNull();
+    });
+
+    it('agrees with the top of the tranche range it must sit alongside', () => {
+        // Both read maxApy through netEffectiveApy; they must not disagree.
+        const tranches = [tranche('Senior', '0.14', '5000', '0.22')];
+        expect(maxNetRateCeiling([named('A', tranches)], FEE)).toBe(
+            netEffectiveApy(0.22, FEE),
+        );
+    });
+});

package/src/domain/pools.ts

@@ -0,0 +1,150 @@
+import { PoolOverview, TrancheData } from '../services/DataService/types';
+
+import { netEffectiveApy } from './rates';
+import { trancheHasCapacity } from './tranches';
+
+/**
+ * The highest FTD-inclusive upper bound across a pool's tranches, or `0` when
+ * none is usable. The sort key behind `selectVisiblePools`.
+ */
+export function poolMaxApy(pool: PoolOverview): number {
+    let hi = 0;
+    for (const t of pool.tranches) {
+        const v = parseFloat(t.maxApy);
+        if (Number.isFinite(v) && v > hi) hi = v;
+    }
+    return hi;
+}
+
+/**
+ * A lending grid's visible pool set: *active* and *not yet oversubscribed*
+ * pools, sorted with has-capacity strategies first, then by highest max APY.
+ *
+ * Shared so a server-rendered payload and a client re-fetch can never
+ * disagree — kasu-ui's SSR fetcher and client hook used to carry verbatim
+ * copies of this filter + sort, and any drift surfaced as an SSR→CSR content
+ * flip on the lending page.
+ *
+ * Pure: operates on a fresh array (`filter` output), so the in-place `sort`
+ * does not mutate the caller's input.
+ */
+export function selectVisiblePools(all: PoolOverview[]): PoolOverview[] {
+    const active = all.filter((p) => p.isActive && !p.isOversubscribed);
+    return active.sort((a, b) => {
+        const aHas = a.tranches.some(trancheHasCapacity) ? 1 : 0;
+        const bHas = b.tranches.some(trancheHasCapacity) ? 1 : 0;
+        if (aHas !== bHas) return bHas - aHas;
+        return poolMaxApy(b) - poolMaxApy(a);
+    });
+}
+
+// `tranches` is typed as a required array but arrives from the subgraph, so
+// both scanners below read it as possibly missing — a pool with no tranche
+// list contributes nothing instead of throwing. Mirrors the `?? []` the
+// kasu-ui originals carried.
+function tranchesOf(tranches: TrancheData[] | undefined): TrancheData[] {
+    return tranches ?? [];
+}
+
+export interface BestTranche {
+    pool: PoolOverview;
+    tranche: TrancheData;
+    /** Base variable-rate APY as a decimal fraction (e.g. `0.12`). */
+    apy: number;
+}
+
+/**
+ * The highest-yielding tranche that still has capacity, across all pools.
+ *
+ * Compares `tranche.apy` — the base variable rate — NOT `minApy`/`maxApy`,
+ * which the data service widens with fixed-term-deposit variants. A headline
+ * naming one tranche should advertise the rate every depositor gets, not an
+ * FTD-locked uplift.
+ *
+ * Capacity is gated by the shared `trancheHasCapacity` (≥ 1 stable unit), so
+ * full tranches never win. Ties on APY break toward more remaining capacity.
+ * Returns `null` when no tranche qualifies (empty list, all full, or all rates
+ * unset) — callers fall back to static copy.
+ */
+export function pickHighestYieldTranche(
+    pools?: PoolOverview[] | null,
+): BestTranche | null {
+    if (!pools?.length) return null;
+
+    let best: BestTranche | null = null;
+
+    for (const pool of pools) {
+        for (const tranche of tranchesOf(pool.tranches)) {
+            if (!trancheHasCapacity(tranche)) continue;
+
+            const apy = parseFloat(tranche.apy);
+            if (!Number.isFinite(apy) || apy <= 0) continue;
+
+            if (!best) {
+                best = { pool, tranche, apy };
+                continue;
+            }
+
+            const capacity = parseFloat(tranche.poolCapacity);
+            const bestCapacity = parseFloat(best.tranche.poolCapacity);
+            if (apy > best.apy || (apy === best.apy && capacity > bestCapacity)) {
+                best = { pool, tranche, apy };
+            }
+        }
+    }
+
+    return best;
+}
+
+/**
+ * The highest NET Effective Interest Rate on offer across the pools passed in
+ * — the ceiling behind an "up to …" claim. The numeric core of kasu-ui's
+ * `formatMaxNetRate`.
+ *
+ * `null` when there is nothing to quote, and callers must then DROP the claim
+ * rather than print a placeholder: this feeds text that gets posted publicly.
+ *
+ * Scope follows the caller's pool list, which is normally keyed to one chain —
+ * so a lender on XDC AUDD quotes the AUDD ceiling, not Base's. That is the
+ * intended reading: they are sharing the deployment they are on.
+ *
+ * Reads `maxApy` — the FTD-inclusive upper bound — unlike
+ * `pickHighestYieldTranche` above, which names one tranche's variable rate. A
+ * ceiling claim and a specific tranche's rate are different statements, and
+ * the ceiling must agree with the top of `netTrancheApyBounds`, which reads
+ * the same field. `apy` is taken into the comparison too: `maxApy` is derived
+ * from the base rate plus any fixed-term configs, so it can never be lower,
+ * and a tranche that carries no `maxApy` at all still contributes its base
+ * rate instead of dropping out.
+ *
+ * Capacity-gated by `trancheHasCapacity` — we never advertise a rate no lender
+ * could take up.
+ *
+ * FAIL CLOSED: an out-of-domain fee, or a net rate that is non-finite or ≤ 0,
+ * returns `null`. The gross figure is never a substitute, and a caller that
+ * does not yet know the fee must not pass `0`.
+ *
+ * @param feePercent the chain's performance fee, 0..100 — never a fraction.
+ */
+export function maxNetRateCeiling(
+    pools: PoolOverview[] | undefined | null,
+    feePercent: number,
+): number | null {
+    if (!pools?.length) return null;
+
+    let ceiling = 0;
+    for (const pool of pools) {
+        for (const tranche of tranchesOf(pool.tranches)) {
+            if (!trancheHasCapacity(tranche)) continue;
+            for (const raw of [tranche.maxApy, tranche.apy]) {
+                const apy = parseFloat(raw);
+                if (Number.isFinite(apy) && apy > ceiling) ceiling = apy;
+            }
+        }
+    }
+    if (ceiling <= 0) return null;
+
+    const rate = netEffectiveApy(ceiling, feePercent);
+    if (!Number.isFinite(rate) || rate <= 0) return null;
+    return rate;
+}