@kasufinance/kasu-sdk 1.0.1 → 1.0.3

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: read
+
+jobs:
+  quality-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate contract typings
+        run: npm run build-tc
+
+      - name: Lint & type-check
+        run: npm run build
+
+      - name: Bundle library
+        run: npm run rollup-build

package/.github/workflows/main.yml

@@ -16,28 +16,32 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
-      - name: Get the version
-        id: get_version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Remove leading v
-        id: replaced_version
-        env:
-          IMAGE_TAG: ${{ steps.get_version.outputs.VERSION }}
+      - name: Get tag version
+        id: tag_version
         run: |
-          string=$IMAGE_TAG
-          echo "VERSION=${string#v}" >> "$GITHUB_OUTPUT"
+          RAW_TAG="${GITHUB_REF#refs/tags/}"
+          echo "TAG_VERSION=${RAW_TAG#v}" >> "$GITHUB_OUTPUT"
 
-      - name: Replace version inside package.json
-        env:
-          VERSION: ${{ steps.replaced_version.outputs.VERSION }}
-        run: bash versioner.sh $VERSION
+      - name: Read package version
+        id: package_version
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          echo "PACKAGE_VERSION=$PKG_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure tag matches package.json
+        run: |
+          if [ "${{ steps.tag_version.outputs.TAG_VERSION }}" != "${{ steps.package_version.outputs.PACKAGE_VERSION }}" ]; then
+            echo "Tag version ${{ steps.tag_version.outputs.TAG_VERSION }} does not match package.json version ${{ steps.package_version.outputs.PACKAGE_VERSION }}."
+            exit 1
+          fi
 
       - uses: actions/setup-node@v3
         with:
           node-version: 18
           registry-url: https://registry.npmjs.org/
           scope: '@kasufinance'
+
       - run: npm install && npm run build-tc && npm run build && npm run rollup-build && npm publish
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/README.md

@@ -0,0 +1,146 @@
+# Kasu SDK
+
+`@kasufinance/kasu-sdk` is the shared TypeScript/JavaScript toolkit used by Kasu
+frontends to interact with the Kasu protocol. It wraps the core smart
+contracts, subgraphs, and Directus CMS in a single object so that dapps can
+query pool data, compute portfolio statistics, and submit locking or lending
+transactions without re-implementing the plumbing.
+
+## Installation
+
+```bash
+npm install @kasufinance/kasu-sdk
+# or
+yarn add @kasufinance/kasu-sdk
+```
+
+The SDK is built against `ethers@5`, so make sure your project already depends
+on it (or install it alongside the SDK).
+
+## Runtime requirements
+
+- **Node or browser environment with fetch/XHR** – when using the SDK on the
+  server (Next.js `app` router actions, serverless functions, etc.) you must
+  provide an XHR implementation because Directus uses it under the hood:
+
+  ```ts
+  // server.ts
+  import { XMLHttpRequest } from 'xhr2';
+  global.XMLHttpRequest = XMLHttpRequest;
+  ```
+
+- **Provider/Signer** – pass an `ethers` `Signer` for write actions or a
+  `Provider` for read-only usage. The SDK does not create its own provider,
+  so you are free to reuse whatever the dapp already uses.
+
+## Configuring the SDK
+
+The `SdkConfig` object wires the SDK to the right contracts and backends:
+
+```ts
+import { JsonRpcProvider } from '@ethersproject/providers';
+import { KasuSdk, SdkConfig } from '@kasufinance/kasu-sdk';
+import { XMLHttpRequest } from 'xhr2';
+
+global.XMLHttpRequest = XMLHttpRequest; // required on Node runtimes
+
+const provider = new JsonRpcProvider(process.env.RPC_URL!, { skipFetchSetup: true });
+
+const config: SdkConfig = {
+  contracts: {
+    KSUToken: '0x…',
+    IKSULocking: '0x…',
+    IKSULockBonus: '0x…',
+    UserManager: '0x…',
+    LendingPoolManager: '0x…',
+    KasuAllowList: '0x…',
+    SystemVariables: '0x…',
+    UserLoyaltyRewards: '0x…',
+    KsuPrice: '0x…',
+    ClearingCoordinator: '0x…',
+    KasuNFTs: '0x…',
+    ExternalTVL: '0x…',
+  },
+  // If certain pools should be hidden from users, provide their ids. Empty string
+  // keeps the Graph queries happy when nothing is filtered out.
+  UNUSED_LENDING_POOL_IDS: [''],
+  directusUrl: 'https://kasu-finance.directus.app/',
+  subgraphUrl: 'https://subgraph.satsuma-prod.com/.../api',
+  plumeSubgraphUrl: 'https://api.goldsky.com/.../kasu-plume/prod/gn',
+};
+
+export const kasuSdk = new KasuSdk(config, provider);
+```
+
+See `kasu-fe-next/src/config/sdk` in the Kasu frontend repository for full
+mainnet and testnet examples, including how Kasu fetches unused pool ids before
+instantiating the SDK.
+
+## Quick start
+
+```ts
+import { JsonRpcProvider } from '@ethersproject/providers';
+import { KasuSdk } from '@kasufinance/kasu-sdk';
+
+const provider = new JsonRpcProvider(RPC_URL);
+const sdk = new KasuSdk(config, provider);
+
+const pools = await sdk.DataService.getPoolOverview(currentEpochId);
+const lockingPeriods = await sdk.Locking.getLockPeriods();
+const userSummary = await sdk.Portfolio.getPortfolioSummary(userAddress);
+await sdk.Locking.lockKSUTokens(amountBn, lockPeriodBn); // signer required
+```
+
+The SDK exposes services as properties on `KasuSdk`. Each service contains the
+methods for a single protocol facet:
+
+| Service       | Purpose                                                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `DataService` | Aggregates on-chain data (subgraphs/external TVL) and off-chain content from Directus (pool descriptions, KPIs). |
+| `Locking`     | High-level helpers for KSU locking: read locking periods, calculate projected rewards, lock/unlock, claim fees. |
+| `UserLending` | User-centric lending utilities (deposit/withdraw requests, transaction history, CSV builders).               |
+| `Portfolio`   | Portfolio snapshots: balances, rewards, lending totals, APY calculations.                                    |
+| `Swapper`     | Helpers for contract calls through the on-chain swapper.                                                     |
+
+Every method is fully typed, so your editor can discover the shape of responses
+(`PoolOverview`, `LockPeriod`, `PortfolioRewards`, etc.) without digging into
+the implementation.
+
+### Working with pool filters
+
+Many queries accept a list of pool ids to ignore (see `UNUSED_LENDING_POOL_IDS`
+in the config). In the Kasu frontend we load this list from Directus before
+creating the SDK:
+
+```ts
+const unusedPools = await getUnusedPools(); // fetches Directus list
+const sdk = new KasuSdk(
+  { ...config, UNUSED_LENDING_POOL_IDS: unusedPools.length ? unusedPools : [''] },
+  provider,
+);
+```
+
+Mirroring this pattern keeps your subgraph requests aligned with the official
+UI and prevents deprecated pools from leaking into calculations.
+
+## Building & testing locally
+
+```bash
+npm install
+npm run build-tc   # regenerate typechain factories
+npm run build      # type-check + compile
+npm run rollup-build
+npm test
+```
+
+These are the same steps executed by the release workflow before publishing to
+npm.
+
+## Support
+For questions, issues, or contributions:
+- GitHub Issues: [Create an issue](https://github.com/kasufinance/kasu-sdk/issues)
+- Documentation: [View full docs](https://docs.kasu.finance)
+- Discord: [Join our community](https://discord.gg/kasufinance)
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kasufinance/kasu-sdk",
-    "version": "1.0.1",
+    "version": "1.0.3",
     "description": "",
     "main": "dist/bundle.cjs.js",
     "module": "dist/bundle.esm.js",

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.ts","./src/sdk-config.ts","./src/contracts/IClearingCoordinatorAbi.ts","./src/contracts/IERC20MetadataAbi.ts","./src/contracts/IFeeManagerAbi.ts","./src/contracts/IKSULockingAbi.ts","./src/contracts/IKasuAllowListAbi.ts","./src/contracts/IKasuControllerAbi.ts","./src/contracts/IKasuNFTsAbi.ts","./src/contracts/IKsuPriceAbi.ts","./src/contracts/ILendingPoolAbi.ts","./src/contracts/ILendingPoolFactoryAbi.ts","./src/contracts/ILendingPoolManagerAbi.ts","./src/contracts/ILendingPoolTrancheAbi.ts","./src/contracts/ISystemVariablesAbi.ts","./src/contracts/IUserLoyaltyRewardsAbi.ts","./src/contracts/IUserManagerAbi.ts","./src/contracts/KSULockBonusAbi.ts","./src/contracts/KasuPoolExternalTVLAbi.ts","./src/contracts/SwapperAbi.ts","./src/contracts/common.ts","./src/contracts/index.ts","./src/contracts/factories/IClearingCoordinatorAbi__factory.ts","./src/contracts/factories/IERC20MetadataAbi__factory.ts","./src/contracts/factories/IFeeManagerAbi__factory.ts","./src/contracts/factories/IKSULockingAbi__factory.ts","./src/contracts/factories/IKasuAllowListAbi__factory.ts","./src/contracts/factories/IKasuControllerAbi__factory.ts","./src/contracts/factories/IKasuNFTsAbi__factory.ts","./src/contracts/factories/IKsuPriceAbi__factory.ts","./src/contracts/factories/ILendingPoolAbi__factory.ts","./src/contracts/factories/ILendingPoolFactoryAbi__factory.ts","./src/contracts/factories/ILendingPoolManagerAbi__factory.ts","./src/contracts/factories/ILendingPoolTrancheAbi__factory.ts","./src/contracts/factories/ISystemVariablesAbi__factory.ts","./src/contracts/factories/IUserLoyaltyRewardsAbi__factory.ts","./src/contracts/factories/IUserManagerAbi__factory.ts","./src/contracts/factories/KSULockBonusAbi__factory.ts","./src/contracts/factories/KasuPoolExternalTVLAbi__factory.ts","./src/contracts/factories/SwapperAbi__factory.ts","./src/contracts/factories/index.ts","./src/services/shared.ts","./src/services/DataService/data-service.ts","./src/services/DataService/directus-types.ts","./src/services/DataService/queries.ts","./src/services/DataService/subgraph-types.ts","./src/services/DataService/types.ts","./src/services/Locking/locking.ts","./src/services/Locking/queries.ts","./src/services/Locking/types.ts","./src/services/Portfolio/portfolio.ts","./src/services/Portfolio/queries.ts","./src/services/Portfolio/types.ts","./src/services/Swapper/swapper.ts","./src/services/Swapper/types.ts","./src/services/UserLending/helper.ts","./src/services/UserLending/queries.ts","./src/services/UserLending/subgraph-types.ts","./src/services/UserLending/types.ts","./src/services/UserLending/user-lending.ts","./src/tests/sample.test.ts"],"version":"5.8.3"}

package/versioner.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-
-# This script replaces the version inside package.json
-version=$1
-
-sed -i "s/\"version\": \"[0-9]\+.[0-9]\+.[0-9]\+\"/\"version\": \"$version\"/" package.json