@liquidium/client 0.2.1 → 0.3.0

package/dist/index.js

@@ -1591,9 +1591,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(
@@ -2222,6 +2222,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,
@@ -3613,6 +3648,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;
@@ -3669,7 +3712,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.
@@ -3682,21 +3737,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.
@@ -3794,30 +3858,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,
@@ -3831,37 +3894,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) {
@@ -3915,7 +3963,9 @@ var InstantLoansModule = class {
       collateralAmount,
       decimals: collateralDecimals,
       asset: collateralAsset,
-      target: depositTarget
+      target: depositTarget,
+      detectedTimestamp: input.depositDetectedTimestamp,
+      expiryTimestamp: input.expiryTimestamp
     });
     const repayment = {
       amount: repaymentAmount,
@@ -3979,7 +4029,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) {
@@ -4075,6 +4127,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(
@@ -4123,18 +4181,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,
@@ -4253,55 +4299,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];
@@ -5906,7 +5977,7 @@ var PositionsModule = class {
           pool,
           priceUsd,
           suppliedUsd: nativeAmountToUsdScaled(
-            position.deposited + position.earnedInterest,
+            position.deposited,
             position.depositedDecimals,
             priceUsd
           ),
@@ -5941,6 +6012,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) {