@liquidium/client 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 ![license](https://img.shields.io/badge/license-MIT-blue)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Liquidium-Inc/liquidium-sdk/main/borrow.svg" alt="Liquidium borrow illustration" width="700" />
+  <img src="https://raw.githubusercontent.com/Liquidium-Inc/liquidium-sdk/main/sdk.svg" alt="Liquidium SDK illustration" width="700" />
 </p>
 
 <h1 align="center">Liquidium SDK</h1>
@@ -12,11 +12,18 @@
 </p>
 
 <p align="center">
+  <a href="https://liquidium-inc.github.io/liquidium-sdk/"><b>SDK Docs</b></a> ·
   <a href="https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/instant-loans-flow"><b>Instant Loan Example</b></a> ·
   <a href="https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/vite-react-dynamic"><b>SDK Method Query Example</b></a> ·
   <a href="#core-api"><b>Core API</b></a>
 </p>
 
+## Documentation
+
+Use the SDK docs for setup, guides, API reference, and examples.
+
+[Open the Liquidium SDK docs](https://liquidium-inc.github.io/liquidium-sdk/)
+
 ## Why Start With Instant Loans
 
 - **Accountless loan creation**: create instant loans without requiring a Liquidium profile.
@@ -27,7 +34,7 @@
 
 ## Integration Paths
 
-Liquidium supports two lending integration paths:
+Liquidium supports two borrowing and lending integration paths:
 
 | Path | Use when | Main SDK calls |
 | --- | --- | --- |
@@ -97,11 +104,13 @@ const loan = await client.instantLoans.create({
 });
 
 console.log("Save this loan reference:", loan.ref);
-console.log("Send collateral to:", formatSupplyTarget(loan.depositTarget));
+console.log("Send initial deposit amount:", loan.initialDeposit.amount.toString());
+console.log("Send collateral to:", formatSupplyTarget(loan.initialDeposit.target));
 
 const restoredLoan = await client.instantLoans.get({ ref: loan.ref });
 
 console.log("Loan status:", restoredLoan.status);
+console.log("Restored initial deposit amount:", restoredLoan.initialDeposit.amount.toString());
 console.log("Repay amount:", restoredLoan.repayment.amount.toString());
 console.log("Repay target:", formatSupplyTarget(restoredLoan.repayment.target));
 
@@ -140,11 +149,11 @@ Instant-loan integrations use this sequence:
 | --- | --- | --- |
 | Load market data | `client.market.listPools()` and `client.market.getAssetPrices()` | Show supported collateral and borrow assets |
 | Validate amounts | `client.quote.calculateLtv(...)` | Block invalid LTV or frozen-pool input before creating a loan |
-| Create loan | `client.instantLoans.create(...)` | Store `loan.ref` and show `loan.depositTarget` |
-| Track loan | `client.instantLoans.get({ ref })` and `client.activities.list({ shortRef: ref })` | Reload loan state and monitor deposit, borrow, and repayment activity |
-| Repay loan | Read `loan.repayment` | Ask the user to send `loan.repayment.amount` to `loan.repayment.target` |
+| Create loan | `client.instantLoans.create(...)` | Store `loan.ref` and show `loan.initialDeposit.amount` plus `loan.initialDeposit.target` |
+| Track loan | `client.instantLoans.get({ ref })` and `client.activities.list({ shortRef: ref })` | Reload loan state, initial deposit quote, and repayment activity |
+| Repay loan | Read `loan.repayment` | Ask the user to send `loan.repayment.amount` to `loan.repayment.target`; amount is `0n` when no repayment is due |
 
-`client.instantLoans.create(...)` returns the generated Liquidium profile, transfer targets, current position state, and repayment quote. Users do not manage the generated profile.
+`client.instantLoans.create(...)` and `client.instantLoans.get(...)` return the generated Liquidium profile, current position state, an initial deposit quote with its transfer target, and a repayment quote with its transfer target. Repayment amount fields are zero when the loan has no debt. Users do not manage the generated profile.
 
 ## Core API
 
@@ -158,7 +167,7 @@ Creates an accountless instant loan and returns generated transfer targets.
 | `borrowPoolId` | Pool the loan borrows from |
 | `collateralAsset` | Collateral asset symbol, for example `"BTC"` |
 | `borrowAsset` | Borrow asset symbol, for example `"USDC"` |
-| `collateralAmount` | Collateral amount in base units |
+| `collateralAmount` | Intended credited collateral amount in base units, before deposit/inflow fees |
 | `borrowAmount` | Borrow amount in base units |
 | `ltvMaxBps` | Maximum LTV in basis points, where `6_000n` is 60% |
 | `depositWindowSeconds` | How long the user has to send collateral |
@@ -171,7 +180,7 @@ Creates an accountless instant loan and returns generated transfer targets.
 
 Loads loan state from a saved user-facing reference.
 
-Use this for status pages, refreshes, and support links.
+Use this for status pages, refreshes, and support links. The SDK combines canister state with the Liquidium SDK API lookup so the restored loan includes the original collateral deposit hint.
 
 ### `client.instantLoans.get({ loanId })`
 
@@ -198,9 +207,11 @@ Most instant-loan UIs show or store these fields:
 | Field | Use |
 | --- | --- |
 | `loan.ref` | Save and show this reference so the loan can be restored later |
-| `loan.status` | Show the lifecycle: `awaiting_deposit`, `deposit_detected`, `active`, `settling`, or `closed` |
-| `loan.depositTarget` | Address or ICRC account where the user sends collateral |
-| `loan.repayment.amount` | Full amount to repay, including fee and interest buffer |
+| `loan.status` | Show the lifecycle: `awaiting_deposit`, `deposit_detected`, `active`, `settling`, `closed`, or `expired` |
+| `loan.initialDeposit.amount` | Fee-inclusive collateral amount to send after creation or restore |
+| `loan.initialDeposit.collateralAmount` | Intended credited collateral target used for LTV |
+| `loan.initialDeposit.target` | Address or ICRC account where the user sends collateral |
+| `loan.repayment.amount` | Full amount to repay, including fee and interest buffer. Zero when no repayment is due |
 | `loan.repayment.target` | Address or ICRC account where the user sends repayment |
 | `loan.position` | Current collateral, debt, and interest state for the generated profile |
 
@@ -213,7 +224,7 @@ The SDK returns amount fields as `bigint` values in the asset's smallest unit.
 | BTC | Satoshis |
 | USDC / USDT | Token base units using the pool decimals |
 
-Use `Pool.decimals` from `client.market.listPools()` when converting user-entered decimals to base units.
+Use `Pool.decimals` from `client.market.listPools()` when converting user-entered decimals to base units. Hydrated instant loans also include `loan.collateral.decimals`, `loan.borrow.decimals`, and `loan.initialDeposit.decimals` for display.
 
 ## Status And Activity Tracking
 
@@ -243,7 +254,7 @@ Start browser integrations with the examples.
 
 | Example | What it shows |
 | --- | --- |
-| [`examples/instant-loans-flow`](https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/instant-loans-flow) | Instant loan UX with Dynamic wallet connection, pool selection, LTV preview, loan creation, status reload, activity status, and address recovery |
+| [`examples/instant-loans-flow`](https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/instant-loans-flow) | Accountless instant loan UX with manual destination addresses, pool selection, LTV preview, loan creation, status reload, activity status, and address recovery |
 | [`examples/vite-react-dynamic`](https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/vite-react-dynamic) | Developer tool for calling SDK methods, including instant loan method templates |
 
 Run the instant loan example:
@@ -267,7 +278,7 @@ Use the SDK in browser apps and modern TypeScript runtimes.
 | Node.js | 20+ for this repository |
 | Package manager | pnpm 9+ for local development |
 | Browser APIs | `fetch`, `BigInt`, and standard ESM support |
-| Wallet UI | Bring your own wallet provider; the example apps use Dynamic |
+| Wallet UI | Bring your own wallet provider; wallet-backed examples use Dynamic |
 
 ## Development