@liquidium/client 0.2.1 → 0.3.0

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:

package/dist/index.cjs

@@ -1593,9 +1593,9 @@ function buildActivityStatusPath(request) {
     request.id
   )}/status?${query.toString()}`;
 }
-function buildInstantLoanAddressLookupPath(request) {
-  const query = new URLSearchParams({ address: request.address });
-  return `${INSTANT_LOANS}/address?${query.toString()}`;
+function buildInstantLoanFindPath(request) {
+  const query = new URLSearchParams({ query: request.query });
+  return `${INSTANT_LOANS}/find?${query.toString()}`;
 }
 function buildInstantLoanCollateralHintPath(request) {
   return `${INSTANT_LOANS}/${encodeURIComponent(
@@ -2224,6 +2224,41 @@ function mapHistoryStatusToApi(status) {
   return status.toUpperCase();
 }
 
+// src/core/utils/api-response-parsers.ts
+var MILLISECONDS_PER_SECOND2 = 1e3;
+function parseNonEmptyApiString(value, field) {
+  if (!value) {
+    throwInvalidApiResponseField(field);
+  }
+  return value;
+}
+function parseUnsignedApiBigint(value, field) {
+  if (!value || !/^\d+$/.test(value)) {
+    throwInvalidApiResponseField(field);
+  }
+  return BigInt(value);
+}
+function parseIsoApiTimestampToUnixSeconds(value, field) {
+  const timestamp = parseNonEmptyApiString(value, field);
+  const timestampMilliseconds = Date.parse(timestamp);
+  if (!Number.isFinite(timestampMilliseconds)) {
+    throwInvalidApiResponseField(field);
+  }
+  return BigInt(Math.floor(timestampMilliseconds / MILLISECONDS_PER_SECOND2));
+}
+function parseApiStringUnion(value, allowedValues, field) {
+  if (value !== void 0 && allowedValues.includes(value)) {
+    return value;
+  }
+  throwInvalidApiResponseField(field);
+}
+function throwInvalidApiResponseField(field) {
+  throw new LiquidiumError(
+    LiquidiumErrorCode.VALIDATION_ERROR,
+    `Invalid ${field.context} ${field.label}`
+  );
+}
+
 // src/core/utils/asset-decimals.ts
 var ASSET_NATIVE_DECIMALS = {
   BTC: 8n,
@@ -3615,6 +3650,14 @@ var RATE_SCALE2 = 10n ** 27n;
 var SECONDS_PER_YEAR = 31536000n;
 var ETH_STABLECOIN_INFLOW_FEE_FALLBACK = 1500000n;
 var INSTANT_LOAN_MIN_SLIPPAGE_BUFFER_BPS = 200n;
+var INSTANT_LOAN_FIND_QUERY_MAX_LENGTH = 256;
+var INSTANT_LOAN_WIRE_CONTEXT = "instant loan";
+var INSTANT_LOAN_ASSETS = [
+  Asset.BTC,
+  Asset.SOL,
+  Asset.USDC,
+  Asset.USDT
+];
 var InstantLoansModule = class {
   constructor(canisterContext, apiClient, lending, positions) {
     this.canisterContext = canisterContext;
@@ -3671,7 +3714,19 @@ var InstantLoansModule = class {
       borrowDestination,
       refundDestination
     });
-    return await this.mapLoanWire(response.loan);
+    const loanId = parseUnsignedApiBigint(response.loan.loanId, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "loan ID"
+    });
+    const collateralAmount = parseUnsignedApiBigint(
+      response.loan.collateral.amountHint,
+      {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "collateral amount"
+      }
+    );
+    const record = await this.getLoanRecord(loanId);
+    return await this.mapLoanRecord(record, collateralAmount);
   }
   /**
    * Resolves canonical canister state by loan id or short reference.
@@ -3684,21 +3739,30 @@ var InstantLoansModule = class {
    */
   async get(request) {
     const loanId = "loanId" in request ? request.loanId : decodeRef(request.ref);
-    try {
-      const result = await createInstantLoansActor(
-        this.canisterContext
-      ).get_loan(loanId);
-      if ("Err" in result) {
-        throw mapInstantLoansErrorToLiquidiumError(result.Err);
-      }
-      const collateralAmount = await this.getCollateralAmountHint(loanId);
-      return await this.mapLoanRecord(result.Ok, collateralAmount);
-    } catch (error) {
-      if (error instanceof LiquidiumError) {
-        throw error;
-      }
-      throw mapCanisterCallErrorToLiquidiumError("get_loan", error);
-    }
+    const record = await this.getLoanRecord(loanId);
+    const collateralAmount = await this.getCollateralAmountHint(loanId);
+    return await this.mapLoanRecord(record, collateralAmount);
+  }
+  /**
+   * Finds instant loans by short reference, numeric loan id string, address, or transaction id.
+   *
+   * Search returns lightweight matches. Call `get({ loanId })` or `get({ ref })`
+   * when the user selects a match and you need hydrated loan state.
+   *
+   * @param query - Short reference, address, transaction id/hash, or numeric loan id string.
+   * @returns Matching loan ids and references from the search index.
+   */
+  async find(query) {
+    const validatedQuery = validateInstantLoanFindQuery(query);
+    const candidates = await this.findCandidateLoansByQuery(validatedQuery);
+    return uniqueInstantLoanFindCandidates(candidates).map((candidate) => ({
+      loanId: candidate.loanId,
+      ref: candidate.ref,
+      createdAt: candidate.createdAt,
+      collateral: candidate.collateral,
+      borrow: candidate.borrow,
+      profileId: candidate.profileId
+    }));
   }
   /**
    * Returns the active instant-loans canister config via direct query.
@@ -3796,30 +3860,29 @@ var InstantLoansModule = class {
       throw mapCanisterCallErrorToLiquidiumError("list_warmed_profiles", error);
     }
   }
-  /**
-   * Finds candidate loans associated with an address through the Liquidium SDK
-   * API. Returns discovery candidates only; call `get(...)` to hydrate canister state.
-   *
-   * Candidates are useful for recovery flows where the user knows a borrow or
-   * refund address but not the loan reference.
-   *
-   * @param address - Borrow or refund address to search for.
-   * @returns Lightweight loan candidates associated with the address.
-   */
-  async findByAddress(address) {
-    const trimmedAddress = address.trim();
-    if (!trimmedAddress) {
-      throw new LiquidiumError(
-        LiquidiumErrorCode.VALIDATION_ERROR,
-        "Address lookup requires a non-empty address"
-      );
-    }
-    const apiClient = this.requireApi("Instant loan address lookup");
+  async findCandidateLoansByQuery(query) {
+    const apiClient = this.requireApi("Instant loan find");
     const response = await apiClient.get(
-      buildInstantLoanAddressLookupPath({ address: trimmedAddress })
+      buildInstantLoanFindPath({ query })
     );
     return (response.candidates ?? response.loans ?? []).map(mapCandidateWire);
   }
+  async getLoanRecord(loanId) {
+    try {
+      const result = await createInstantLoansActor(
+        this.canisterContext
+      ).get_loan(loanId);
+      if ("Err" in result) {
+        throw mapInstantLoansErrorToLiquidiumError(result.Err);
+      }
+      return result.Ok;
+    } catch (error) {
+      if (error instanceof LiquidiumError) {
+        throw error;
+      }
+      throw mapCanisterCallErrorToLiquidiumError("get_loan", error);
+    }
+  }
   async mapLoanRecord(record, collateralAmount) {
     return await this.hydrateLoan({
       loanId: record.id,
@@ -3833,37 +3896,22 @@ var InstantLoansModule = class {
       borrowAsset: getVariantKey(record.borrow_asset),
       borrowAmount: record.borrow_amount,
       borrowDestination: accountFromCanister(record.borrow_destination),
-      refundDestination: accountFromCanister(record.refund_destination)
+      refundDestination: accountFromCanister(record.refund_destination),
+      depositDetectedTimestamp: record.deposit_detected_ts[0] ?? null,
+      expiryTimestamp: record.expires_at[0] ?? deriveDepositExpiryTimestamp({
+        depositDetectedTimestamp: record.deposit_detected_ts[0] ?? null,
+        depositWindowSeconds: record.ltv_timer_s
+      })
     });
   }
   async getCollateralAmountHint(loanId) {
-    const apiClient = this.requireApi("Instant loan lookup");
+    const apiClient = this.requireApi("Instant loan collateral hint");
     const response = await apiClient.get(
       buildInstantLoanCollateralHintPath({ loanId })
     );
-    return parseBigintWire(response.collateralAmountHint, "collateral amount");
-  }
-  async mapLoanWire(loan) {
-    const loanId = parseBigintWire(loan.loanId, "loan ID");
-    return await this.hydrateLoan({
-      loanId,
-      profileId: loan.profileId,
-      ltvMaxBps: parseBigintWire(loan.ltvMaxBps, "max LTV"),
-      depositWindowSeconds: parseBigintWire(
-        loan.depositWindowSeconds,
-        "deposit window"
-      ),
-      collateralPoolId: loan.collateral.poolId,
-      collateralAmount: parseBigintWire(
-        loan.collateral.amountHint,
-        "collateral amount"
-      ),
-      borrowPoolId: loan.borrow.poolId,
-      collateralAsset: loan.collateral.asset,
-      borrowAsset: loan.borrow.asset,
-      borrowAmount: parseBigintWire(loan.borrow.amount, "borrow amount"),
-      borrowDestination: accountFromWire(loan.borrow.destination),
-      refundDestination: accountFromWire(loan.refundDestination)
+    return parseUnsignedApiBigint(response.collateralAmountHint, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "collateral amount"
     });
   }
   async hydrateLoan(input) {
@@ -3917,7 +3965,9 @@ var InstantLoansModule = class {
       collateralAmount,
       decimals: collateralDecimals,
       asset: collateralAsset,
-      target: depositTarget
+      target: depositTarget,
+      detectedTimestamp: input.depositDetectedTimestamp,
+      expiryTimestamp: input.expiryTimestamp
     });
     const repayment = {
       amount: repaymentAmount,
@@ -3981,7 +4031,9 @@ var InstantLoansModule = class {
       inflowFeeAmount: inflowFee.totalFee,
       asset: input.asset,
       chain: input.target.chain,
-      target: input.target
+      target: input.target,
+      detectedTimestamp: input.detectedTimestamp,
+      expiryTimestamp: input.expiryTimestamp
     };
   }
   async estimateRepaymentInflowFee(asset, chain) {
@@ -4077,6 +4129,12 @@ function deriveInstantLoanStatus(input) {
   }
   return InstantLoanStatus.awaitingDeposit;
 }
+function deriveDepositExpiryTimestamp(input) {
+  if (input.depositDetectedTimestamp === null) {
+    return null;
+  }
+  return input.depositDetectedTimestamp + input.depositWindowSeconds;
+}
 function validateCreateRequest(request) {
   if (request.collateralAmount <= 0n) {
     throw new LiquidiumError(
@@ -4125,18 +4183,6 @@ function accountFromCanister(account) {
   }
   return { type: "External", address: account.External };
 }
-function accountFromWire(account) {
-  if ("Native" in account) {
-    return { type: "Native", principal: account.Native };
-  }
-  if ("External" in account) {
-    return { type: "External", address: account.External };
-  }
-  if (account.type === "Native") {
-    return { type: "Native", principal: account.principal };
-  }
-  return { type: "External", address: account.address };
-}
 function mapInstantLoanEvent(event) {
   return {
     id: event.id,
@@ -4255,55 +4301,80 @@ function decodeRef(ref) {
     );
   }
 }
-function mapCandidateWire(wire) {
-  const loanId = parseBigintWire(wire.loanId ?? wire.loan_id, "loan ID");
-  const ref = wire.ref ?? wire.short_ref ?? publicIdFromInt(loanId);
-  const createdAt = wire.createdAt ?? wire.created_at;
-  return {
-    loanId,
-    ref,
-    profileId: requiredString(
-      wire.profileId ?? wire.lending_profile,
-      "profile ID"
-    ),
-    ...createdAt ? { createdAt: new Date(createdAt) } : {},
-    collateralPoolId: requiredString(
-      wire.collateralPoolId ?? wire.lend_pool_ic_id,
-      "collateral pool ID"
-    ),
-    borrowPoolId: requiredString(
-      wire.borrowPoolId ?? wire.borrow_pool_ic_id,
-      "borrow pool ID"
-    ),
-    collateralAsset: requiredString(
-      wire.collateralAsset ?? wire.lend_asset,
-      "collateral asset"
-    ),
-    borrowAsset: requiredString(
-      wire.borrowAsset ?? wire.borrow_asset,
-      "borrow asset"
-    ),
-    collateralAmount: parseBigintWire(
-      wire.collateralAmount,
-      "collateral amount"
-    )
-  };
-}
-function parseBigintWire(value, label) {
-  if (!value || !/^\d+$/.test(value)) {
+function validateInstantLoanFindQuery(query) {
+  if (typeof query !== "string") {
     throw new LiquidiumError(
       LiquidiumErrorCode.VALIDATION_ERROR,
-      `Invalid instant loan ${label}`
+      "Instant loan find query must be a string"
     );
   }
-  return BigInt(value);
+  const trimmedQuery = query.trim();
+  if (!trimmedQuery) {
+    throw new LiquidiumError(
+      LiquidiumErrorCode.VALIDATION_ERROR,
+      "Instant loan find query must be non-empty"
+    );
+  }
+  if (trimmedQuery.length > INSTANT_LOAN_FIND_QUERY_MAX_LENGTH) {
+    throw new LiquidiumError(
+      LiquidiumErrorCode.VALIDATION_ERROR,
+      `Instant loan find query must be at most ${INSTANT_LOAN_FIND_QUERY_MAX_LENGTH.toString()} characters`
+    );
+  }
+  return trimmedQuery;
 }
-function requiredString(value, label) {
-  if (value?.trim()) return value;
-  throw new LiquidiumError(
-    LiquidiumErrorCode.VALIDATION_ERROR,
-    `Missing instant loan ${label}`
-  );
+function uniqueInstantLoanFindCandidates(candidates) {
+  const candidatesByLoanId = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    if (!candidatesByLoanId.has(candidate.loanId)) {
+      candidatesByLoanId.set(candidate.loanId, candidate);
+    }
+  }
+  return [...candidatesByLoanId.values()];
+}
+function mapCandidateWire(wire) {
+  return {
+    loanId: parseUnsignedApiBigint(wire.loan_id, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "loan ID"
+    }),
+    ref: parseNonEmptyApiString(wire.short_ref, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "short reference"
+    }),
+    createdAt: parseIsoApiTimestampToUnixSeconds(wire.created_at, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "creation timestamp"
+    }),
+    collateral: {
+      poolId: parseNonEmptyApiString(wire.lend_pool_ic_id, {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "lend pool ID"
+      }),
+      asset: parseApiStringUnion(wire.lend_asset, INSTANT_LOAN_ASSETS, {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "lend asset"
+      }),
+      amount: parseUnsignedApiBigint(wire.collateral_amount, {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "collateral amount"
+      })
+    },
+    borrow: {
+      poolId: parseNonEmptyApiString(wire.borrow_pool_ic_id, {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "borrow pool ID"
+      }),
+      asset: parseApiStringUnion(wire.borrow_asset, INSTANT_LOAN_ASSETS, {
+        context: INSTANT_LOAN_WIRE_CONTEXT,
+        label: "borrow asset"
+      })
+    },
+    profileId: parseNonEmptyApiString(wire.profile, {
+      context: INSTANT_LOAN_WIRE_CONTEXT,
+      label: "profile ID"
+    })
+  };
 }
 function mapInstantLoansErrorToLiquidiumError(error) {
   const [key, payload] = Object.entries(error)[0];
@@ -5908,7 +5979,7 @@ var PositionsModule = class {
           pool,
           priceUsd,
           suppliedUsd: nativeAmountToUsdScaled(
-            position.deposited + position.earnedInterest,
+            position.deposited,
             position.depositedDecimals,
             priceUsd
           ),
@@ -5943,6 +6014,24 @@ var PositionsModule = class {
     const buffered = rawDebt * (BPS_SCALE + bufferBps) / BPS_SCALE;
     return { amount: buffered, decimals: position.borrowedDecimals };
   }
+  /**
+   * Returns the current full withdraw amount for a position.
+   *
+   * `Position.deposited` already reflects the current supplied balance at the
+   * latest lending index; do not add `earnedInterest` to this amount.
+   * Pass `amount` to withdraw calls and use `decimals` for display formatting.
+   *
+   * @param profileId - The Liquidium profile principal text.
+   * @param poolId - The pool principal text.
+   * @returns Full withdraw amount in the supplied asset's base units.
+   */
+  async getFullWithdrawAmount(profileId, poolId) {
+    const position = await this.getPosition(profileId, poolId);
+    if (!position) {
+      return { amount: 0n, decimals: 0n };
+    }
+    return { amount: position.deposited, decimals: position.depositedDecimals };
+  }
 };
 function nativeAmountToUsdScaled(amount, nativeDecimals, priceUsd) {
   if (amount <= 0n || priceUsd <= 0) {