@kasufinance/kasu-sdk 1.0.4 → 2.1.0

package/src/facade/types.ts

@@ -0,0 +1,168 @@
+import { BigNumberish, BytesLike } from 'ethers';
+
+import { ContractAddresses, SdkConfigOptions } from '../sdk-config';
+import { LendingTotals, PoolOverview, TrancheData } from '../services/DataService/types';
+import {
+    PortfolioLendingPool,
+    PortfolioSummary,
+} from '../services/Portfolio/types';
+
+// ---------------------------------------------------------------------------
+// Chain & SDK Configuration
+// ---------------------------------------------------------------------------
+
+export type SupportedChain = 'base' | 'xdc' | 'plume';
+
+export interface ChainConfigEntry {
+    chainId: number;
+    name: string;
+    isLiteDeployment: boolean;
+    contracts: ContractAddresses;
+    subgraphUrl: string;
+    directusUrl: string;
+    unusedPoolIds: string[];
+    poolMetadataMapping?: Record<string, string>;
+}
+
+/** Options passed to `Kasu.create()`. */
+export interface KasuOptions {
+    /** A supported chain name or a custom `ChainConfigEntry`. */
+    chain: SupportedChain | ChainConfigEntry;
+    /** ethers Signer (for transactions) or Provider (read-only). */
+    signerOrProvider: import('ethers').Signer | import('@ethersproject/providers').Provider;
+    /** Override any default config value. */
+    configOverrides?: Partial<SdkConfigOptions>;
+}
+
+// ---------------------------------------------------------------------------
+// Strategy (pool) types – integrator-friendly view of PoolOverview
+// ---------------------------------------------------------------------------
+
+export interface Strategy {
+    id: string;
+    name: string;
+    description: string;
+    isActive: boolean;
+    /** Weighted-average APY across tranches (decimal, e.g. 0.08 = 8 %). */
+    apy: number;
+    tvl: {
+        /** On-chain + off-chain total. */
+        total: string;
+        offchain: string;
+    };
+    /** Remaining capacity across all tranches. */
+    availableCapacity: string;
+    /** 0-1 utilisation ratio. */
+    capacityUtilisation: string;
+    tranches: StrategyTranche[];
+    /** Asset class label (e.g. "Tax Receivables"). */
+    assetClass: string;
+    /** Fixed or Variable. */
+    apyStructure: 'Variable' | 'Fixed';
+    /** Thumbnail image URL (empty string when Directus unavailable). */
+    thumbnailUrl: string;
+    /** Banner image URL (empty string when Directus unavailable). */
+    bannerUrl: string;
+    /** Raw `PoolOverview` for power-users who need all fields. */
+    _raw: PoolOverview;
+}
+
+export interface StrategyTranche {
+    id: string;
+    name: string;
+    /** Current base APY (decimal). */
+    apy: number;
+    minApy: number;
+    maxApy: number;
+    /** Minimum deposit in USDC (ether-formatted string). */
+    minimumDeposit: string;
+    /** Maximum deposit in USDC (ether-formatted string). */
+    maximumDeposit: string;
+    /** Remaining tranche capacity (ether-formatted string). */
+    availableCapacity: string;
+    /** Fixed-term deposit options on this tranche. */
+    fixedTermOptions: FixedTermOption[];
+    /** Raw `TrancheData` for power-users. */
+    _raw: TrancheData;
+}
+
+export interface FixedTermOption {
+    configId: string;
+    /** Annual APY (decimal). */
+    apy: number;
+    /** Lock duration in epochs (1 epoch ≈ 1 week). */
+    epochLockDuration: string;
+}
+
+// ---------------------------------------------------------------------------
+// Deposit / Withdraw
+// ---------------------------------------------------------------------------
+
+export interface DepositParams {
+    poolId: string;
+    trancheId: string;
+    /** Amount in USDC base units (BigNumberish). */
+    amount: BigNumberish;
+    /** KYC signature obtained from the Nexera flow. */
+    kycSignature: {
+        blockExpiration: BigNumberish;
+        signature: BytesLike;
+    };
+    /** ABI-encoded deposit data (contract acceptance). Pass `'0x'` when not needed. */
+    depositData?: BytesLike;
+    /** Fixed-term config ID. Pass `0` for variable deposits. */
+    fixedTermConfigId?: BigNumberish;
+    /** Swap calldata. Pass `'0x'` when depositing USDC directly. */
+    swapData?: BytesLike;
+    /** Native token value to send (e.g. for gas on some chains). Defaults to `'0'`. */
+    ethValue?: string;
+}
+
+export interface WithdrawParams {
+    poolId: string;
+    trancheId: string;
+    /** USDC amount to withdraw, or `'max'` to withdraw entire balance. */
+    amount: BigNumberish;
+    /** Required when `amount` is `'max'`. */
+    userAddress?: string;
+}
+
+export interface DepositLimits {
+    /** Minimum deposit (ether-formatted USDC). */
+    min: string;
+    /** Maximum deposit (ether-formatted USDC). */
+    max: string;
+    /** Remaining tranche capacity (ether-formatted USDC). */
+    availableCapacity: string;
+}
+
+// ---------------------------------------------------------------------------
+// KYC helpers
+// ---------------------------------------------------------------------------
+
+export interface KycParams {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    contractAbi: any;
+    contractAddress: string;
+    functionName: string;
+    args: BytesLike[];
+    userAddress: string;
+    chainId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Portfolio
+// ---------------------------------------------------------------------------
+
+export interface UserPositions {
+    /** Per-pool breakdown. */
+    pools: PortfolioLendingPool[];
+    /** Aggregate summary (invested, yields, APY). */
+    summary: PortfolioSummary;
+}
+
+// ---------------------------------------------------------------------------
+// Platform stats
+// ---------------------------------------------------------------------------
+
+export type PlatformStats = LendingTotals;

package/src/facade/user-portfolio.ts

@@ -0,0 +1,73 @@
+import { Provider } from '@ethersproject/providers';
+
+import { DataService } from '../services/DataService/data-service';
+import { Portfolio } from '../services/Portfolio/portfolio';
+import { UserRequest } from '../services/UserLending/types';
+import { UserLending } from '../services/UserLending/user-lending';
+
+import { UserPositions } from './types';
+
+/**
+ * High-level facade for querying a user's portfolio, positions, and history.
+ *
+ * Orchestrates DataService, UserLending, and Portfolio services so the caller
+ * only needs to provide a wallet address.
+ */
+export class PortfolioFacade {
+    constructor(
+        private _dataService: DataService,
+        private _userLending: UserLending,
+        private _portfolio: Portfolio,
+    ) {}
+
+    /**
+     * Fetch a user's complete portfolio: per-pool positions and aggregate summary.
+     *
+     * ```ts
+     * const positions = await kasu.portfolio.getPositions('0xUser...');
+     * console.log(positions.summary.current.totalLendingPoolInvestments);
+     * ```
+     *
+     * @param userAddress - Wallet address.
+     * @param provider    - Optional separate provider for balance queries (useful when the
+     *                      SDK was initialised with a Signer but you need a read-only provider).
+     */
+    async getPositions(
+        userAddress: string,
+        provider?: Provider,
+    ): Promise<UserPositions> {
+        const currentEpoch = await this._userLending.getCurrentEpoch();
+
+        const poolOverviews = await this._dataService.getPoolOverview(
+            currentEpoch,
+        );
+
+        const pools = await this._portfolio.getPortfolioLendingData(
+            userAddress,
+            poolOverviews,
+            currentEpoch,
+            provider,
+        );
+
+        const summary = await this._portfolio.getPortfolioSummary(
+            userAddress,
+            pools,
+            currentEpoch,
+        );
+
+        return { pools, summary };
+    }
+
+    /**
+     * Fetch a user's full transaction history (deposits, withdrawals, cancellations).
+     */
+    async getTransactionHistory(
+        userAddress: `0x${string}`,
+    ): Promise<UserRequest[]> {
+        const currentEpoch = await this._userLending.getCurrentEpoch();
+        return await this._userLending.getUserRequests(
+            userAddress,
+            currentEpoch,
+        );
+    }
+}

package/src/index.ts

@@ -1,27 +1,61 @@
-import { Provider } from '@ethersproject/providers';
-import { ethers, Signer } from 'ethers';
-import { GraphQLClient } from 'graphql-request';
+// ---------------------------------------------------------------------------
+// Core SDK class (low-level service access)
+// ---------------------------------------------------------------------------
+export { KasuSdk } from './kasu-sdk';
 
-import { SdkConfig } from './sdk-config';
-import { DataService } from './services/DataService/data-service';
-import { KSULocking } from './services/Locking/locking';
-import { Portfolio } from './services/Portfolio/portfolio';
-import { Swapper } from './services/Swapper/swapper';
-import { UserLending } from './services/UserLending/user-lending';
+// ---------------------------------------------------------------------------
+// Re-export config types
+// ---------------------------------------------------------------------------
+export type { ContractAddresses, SdkConfigOptions } from './sdk-config';
+export { SdkConfig } from './sdk-config';
 
-export class KasuSdk {
-    private readonly _graphClient: GraphQLClient;
-    public readonly Locking: KSULocking;
-    public readonly DataService: DataService;
-    public readonly UserLending: UserLending;
-    public readonly Portfolio: Portfolio;
-    public readonly Swapper: Swapper;
-    constructor(config: SdkConfig, signerOrProvider: Provider | Signer) {
-        this._graphClient = new GraphQLClient(config.subgraphUrl);
-        this.Locking = new KSULocking(config, signerOrProvider);
-        this.UserLending = new UserLending(config, signerOrProvider);
-        this.DataService = new DataService(config, signerOrProvider);
-        this.Portfolio = new Portfolio(config, signerOrProvider);
-        this.Swapper = new Swapper();
-    }
-}
+// ---------------------------------------------------------------------------
+// Re-export service types so consumers don't need deep imports
+// ---------------------------------------------------------------------------
+export type {
+    PoolOverview,
+    TrancheData,
+    LendingTotals,
+    PoolRepayment,
+    RiskManagement,
+    PoolDelegateProfileAndHistory,
+    PoolTranche,
+    PoolCreditMetrics,
+    BadAndDoubtfulDebts,
+    FinancialReportingDocuments,
+} from './services/DataService/types';
+
+export type {
+    UserRequest,
+    UserRequestEvent,
+    UserTrancheBalance,
+    UserPoolBalance,
+    UserApyBonus,
+    PortfolioUserTrancheBalance,
+} from './services/UserLending/types';
+
+export type {
+    PortfolioSummary,
+    PortfolioLendingPool,
+    PortfolioTranche,
+    PortfolioRewards,
+    PortfolioTrancheDepositDetails,
+} from './services/Portfolio/types';
+
+export type {
+    UserLock,
+    UserBonusData,
+    LockPeriod,
+    GQLGetLockingPeriods,
+    SystemVariables,
+} from './services/Locking/types';
+
+export type {
+    PoolOverviewDirectus,
+    PlatformOverviewDirectus,
+} from './services/DataService/directus-types';
+
+// ---------------------------------------------------------------------------
+// Re-export facade (high-level integrator API)
+// ---------------------------------------------------------------------------
+export * from './facade';

package/src/kasu-sdk.ts

@@ -0,0 +1,27 @@
+import { Provider } from '@ethersproject/providers';
+import { Signer } from 'ethers';
+import { GraphQLClient } from 'graphql-request';
+
+import { SdkConfig } from './sdk-config';
+import { DataService } from './services/DataService/data-service';
+import { KSULocking } from './services/Locking/locking';
+import { Portfolio } from './services/Portfolio/portfolio';
+import { Swapper } from './services/Swapper/swapper';
+import { UserLending } from './services/UserLending/user-lending';
+
+export class KasuSdk {
+    private readonly _graphClient: GraphQLClient;
+    public readonly Locking: KSULocking;
+    public readonly DataService: DataService;
+    public readonly UserLending: UserLending;
+    public readonly Portfolio: Portfolio;
+    public readonly Swapper: Swapper;
+    constructor(config: SdkConfig, signerOrProvider: Provider | Signer) {
+        this._graphClient = new GraphQLClient(config.subgraphUrl);
+        this.Locking = new KSULocking(config, signerOrProvider);
+        this.UserLending = new UserLending(config, signerOrProvider);
+        this.DataService = new DataService(config, signerOrProvider);
+        this.Portfolio = new Portfolio(config, signerOrProvider);
+        this.Swapper = new Swapper();
+    }
+}

package/src/sdk-config.ts

@@ -1,5 +1,6 @@
 export interface ContractAddresses {
-    KSUToken: string;
+    /** KSU Token address - only present on Full deployments (Base), undefined on Lite (XDC, Plume) */
+    KSUToken?: string;
     IKSULocking: string;
     IKSULockBonus: string;
     UserManager: string;
@@ -9,27 +10,47 @@ export interface ContractAddresses {
     UserLoyaltyRewards: string;
     KsuPrice: string;
     ClearingCoordinator: string;
-    KasuNFTs: string;
+    /** KasuNFTs address - only present on Full deployments */
+    KasuNFTs?: string;
     ExternalTVL: string;
 }
+
+export interface SdkConfigOptions {
+    subgraphUrl: string;
+    contracts: ContractAddresses;
+    /** Directus CMS URL. Optional – when omitted, pool descriptions/images will not be available but on-chain data still works. */
+    directusUrl?: string;
+    UNUSED_LENDING_POOL_IDS: string[];
+    /**
+     * Whether this is a Lite deployment (no KSU token, locking, or loyalty features).
+     * Set to true for XDC, Plume, and other chains without the full token system.
+     * @default false
+     */
+    isLiteDeployment?: boolean;
+    /**
+     * Maps pool addresses to their metadata source pool address in Directus.
+     * Used for chains (XDC, Plume) that share pool descriptions with Base.
+     * Key: pool address on this chain (lowercase)
+     * Value: pool address in Directus / Base pool (lowercase)
+     */
+    poolMetadataMapping?: Record<string, string>;
+}
+
 export class SdkConfig {
     subgraphUrl: string;
-    plumeSubgraphUrl: string;
     contracts: ContractAddresses;
+    /** Directus CMS URL. When empty, DataService skips CMS enrichment and returns on-chain data only. */
     directusUrl: string;
     UNUSED_LENDING_POOL_IDS: string[];
+    isLiteDeployment: boolean;
+    poolMetadataMapping: Record<string, string>;
 
-    constructor(
-        subgraphUrl: string,
-        plumeSubgraphUrl: string,
-        contracts: ContractAddresses,
-        directusUrl: string,
-        UNUSED_LENDING_POOL_IDS: string[],
-    ) {
-        this.subgraphUrl = subgraphUrl;
-        this.plumeSubgraphUrl = plumeSubgraphUrl;
-        this.contracts = contracts;
-        this.directusUrl = directusUrl;
-        this.UNUSED_LENDING_POOL_IDS = UNUSED_LENDING_POOL_IDS;
+    constructor(options: SdkConfigOptions) {
+        this.subgraphUrl = options.subgraphUrl;
+        this.contracts = options.contracts;
+        this.directusUrl = options.directusUrl ?? '';
+        this.UNUSED_LENDING_POOL_IDS = options.UNUSED_LENDING_POOL_IDS;
+        this.isLiteDeployment = options.isLiteDeployment ?? false;
+        this.poolMetadataMapping = options.poolMetadataMapping ?? {};
     }
 }