@liquidium/client 0.2.1 → 0.3.1

package/README.md

@@ -38,8 +38,8 @@ Liquidium supports two borrowing and lending integration paths:
 
 | Path | Use when | Main SDK calls |
 | --- | --- | --- |
-| Recommended: accountless instant loans | You want a short checkout-style flow where users borrow against collateral without creating a Liquidium profile first | `client.instantLoans.create(...)`, `client.instantLoans.get(...)`, `client.activities.list(...)` |
-| Account-based profile flows | You want users to keep a Liquidium profile, manage positions across sessions, supply funds, borrow, withdraw, or use ETH contract-interaction deposits | `client.accounts.createProfile(...)`, `client.lending.supply(...)`, `client.lending.borrow(...)`, `client.lending.withdraw(...)`, `client.positions.list(...)` |
+| Recommended: accountless instant loans | You want a short checkout-style flow where users borrow against collateral without creating a Liquidium profile first | `client.instantLoans.create(...)`, `client.instantLoans.get(...)`, `client.instantLoans.find(...)`, `client.activities.list(...)` |
+| Account-based profile flows | You want users to keep a Liquidium profile, manage positions across sessions, supply funds, borrow, withdraw, or use ETH contract-interaction deposits | `client.accounts.createProfile(...)`, `client.lending.supply(...)`, `client.lending.borrow(...)`, `client.lending.withdraw(...)`, `client.positions.listPositions(...)` |
 
 Use accountless instant loans for new borrow flows unless you need profile-level position management. Use account-based flows when your app owns the full lending dashboard experience.
 
@@ -118,6 +118,11 @@ const activities = await client.activities.list({ shortRef: loan.ref });
 
 console.log("Loan activities:", activities);
 
+const foundLoans = await client.instantLoans.find(loan.ref);
+
+console.log("Found loan reference:", foundLoans[0]?.ref);
+console.log("Found loan collateral:", foundLoans[0]?.collateral.amount.toString());
+
 function requirePool(pools: Pool[], asset: string): Pool {
   const pool = pools.find((candidatePool) => candidatePool.asset === asset);
 
@@ -150,7 +155,7 @@ 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 too-small borrow amounts, invalid LTV, or frozen-pool input before creating a loan |
 | 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 |
+| Track loan | `client.instantLoans.get({ ref })`, `client.instantLoans.find(...)`, 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(...)` 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.
@@ -188,11 +193,33 @@ Loads loan state by numeric canister loan id.
 
 Use this when your backend stores the numeric id instead of the short reference.
 
-### `client.instantLoans.findByAddress(address)`
+### `client.instantLoans.find(query)`
+
+Finds instant loans by short reference, numeric canister loan id string, generated deposit or repayment address, borrow or refund destination address, or indexed transaction id/hash through the SDK API search index.
+
+Use this for recovery and manage pages where the user may paste any loan identifier. The method returns lightweight matches because address and transaction-id lookups can match many loans. Use `client.instantLoans.get(...)` after the user selects a match.
+
+```ts
+const results = await client.instantLoans.find("bc1q...");
+const byRef = await client.instantLoans.find("ABC123");
+const byLoanId = await client.instantLoans.find("42");
+
+for (const result of results) {
+  console.log(result.ref);
+  console.log(result.loanId);
+  console.log(result.collateral.asset, result.borrow.asset);
+  console.log(result.collateral.amount);
+}
+
+const selectedLoan = await client.instantLoans.get({ loanId: results[0].loanId });
+```
 
-Finds candidate loans associated with a borrow or refund address.
+Call `get(...)` when you already have an exact canister identifier and want direct canister lookup without an array:
 
-Use this only for recovery. The method returns candidate matches; call `client.instantLoans.get({ ref })` or `client.instantLoans.get({ loanId })` before showing loan state or transfer targets.
+```ts
+const loanById = await client.instantLoans.get({ loanId: 123n });
+const loanByRef = await client.instantLoans.get({ ref: "ABC123" });
+```
 
 ### `client.quote.calculateLtv(request, pools, prices)`
 
@@ -212,6 +239,10 @@ The SDK enforces product minimums before borrow creation:
 
 Use `getMinimumBorrowAmount(asset)` to display the same minimum that `client.quote.calculateLtv(...)`, `client.quote.getQuote(...)`, `client.instantLoans.create(...)`, and `client.lending.prepareBorrow(...)` enforce.
 
+### Profile full withdraw amounts
+
+For profile-based withdraw flows, call `client.positions.getFullWithdrawAmount(profileId, poolId)` before building the withdraw request. The helper returns `{ amount, decimals }`: pass `amount` to `client.lending.withdraw(...)` or `client.lending.prepareWithdraw(...)`, and use `decimals` for display formatting. Do not add `earnedInterest`; the returned amount already uses the current supplied balance.
+
 ## Response Fields
 
 Most instant-loan UIs show or store these fields:
@@ -223,10 +254,14 @@ Most instant-loan UIs show or store these fields:
 | `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.initialDeposit.detectedTimestamp` | Unix timestamp in seconds when the collateral deposit was detected, or `null` before detection |
+| `loan.initialDeposit.expiryTimestamp` | Unix timestamp in seconds when the collateral deposit window expires, or `null` before detection when unavailable |
 | `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 |
 
+`client.instantLoans.find(...)` returns lightweight search matches with `loanId`, `ref`, `createdAt`, `profileId`, `collateral`, and `borrow`. Use `client.instantLoans.get(...)` to load full loan fields, and use `client.activities.list(...)` separately when you need deposit, borrow, repay, or withdraw activity.
+
 ## Amounts
 
 The SDK returns amount fields as `bigint` values in the asset's smallest unit.
@@ -266,7 +301,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) | Accountless instant loan UX with manual destination addresses, 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 loan recovery |
 | [`examples/sdk-method-query`](https://github.com/Liquidium-Inc/liquidium-sdk/tree/main/examples/sdk-method-query) | Developer tool for calling SDK methods, including instant loan method templates |
 
 Run the instant loan example: