@provex/utils 1.11.0 → 2.0.0-rc.20261103015524.5c1d822

package/dist/buy/browsePanelDerivations.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @fileoverview Pure derivations extracted from BrowsePanel.tsx.
+ *
+ * Each helper takes ordinary inputs (no React hooks, no wagmi state)
+ * and returns a value, so they're testable in isolation without
+ * mounting the panel or stubbing wagmi/router/appkit.
+ *
+ * Rationale for the split: BrowsePanel sits at the very top of the
+ * buy-flow surface area — every input flows through it. Inlining
+ * these derivations next to the JSX makes the file (1) hard to read
+ * and (2) impossible to test without a full router+wallet harness.
+ * Pulling them out is both a navigation and a coverage win.
+ *
+ * Keep helpers PURE: no side effects, no module-level state, no
+ * useState/useMemo. The panel still calls each one inside its own
+ * useMemo so React-level memoization stays at the call site.
+ */
+import { type ProviderKey, type SubProviderKey } from '../payment.js';
+import type { ChainId } from '../chain.js';
+import type { Currency } from '../currencies.js';
+/**
+ * Sanitize a raw amount-input string so it only contains digits and a
+ * single `.`, and clamp the fractional precision to `maxDecimals`.
+ *
+ * Mirrors the live filter on the BrowsePanel `<Input>` element. Pure
+ * string transform — the call site wraps it in `setState` per-keystroke.
+ *
+ * @example
+ *   sanitizeAmountInput('12.34.56', 2) // '12.3456' → '12.34'  (clamp)
+ *   sanitizeAmountInput('1a2b.3', 2)   // '12.3'              (filter)
+ *   sanitizeAmountInput('100.500', 2)  // '100.50'            (clamp)
+ */
+export declare function sanitizeAmountInput(raw: string, maxDecimals: number): string;
+/**
+ * Parse the sanitized amount string into a USDC-6-decimal-base-units
+ * bigint (the unit every downstream calc uses).
+ *
+ * Returns `null` if the amount can't be parsed (empty, NaN, missing
+ * currency). Negative values clamp to `0n` rather than propagating
+ * the negative — the input filter already strips `-`, so this is
+ * defensive against a hypothetical refactor that accepts it.
+ *
+ * @param amount - The sanitized amount string ('100.50').
+ * @param currencyDecimals - Decimals of the fiat currency (USD = 2, JPY = 0).
+ *                           Falls back to 2 when undefined to match the
+ *                           panel's `currency?.decimals ?? 2` shape.
+ * @returns Amount as a bigint in USDC base units, or null.
+ */
+export declare function parseAmountToBaseUnits(amount: string, currencyDecimals: number | undefined): bigint | null;
+/** The least a deposit has to expose for the buy panel to rank it. */
+export interface RankableDeposit {
+    depositId: bigint;
+}
+/**
+ * Sort matched deposits by rate ascending (lowest fiat-per-USDC =
+ * best deal for the buyer), breaking ties by deposit id ascending
+ * so the order is deterministic across renders.
+ *
+ * The rate is injected so this module does not depend on the indexer
+ * client, which depends on this package.
+ *
+ * Returns a fresh array — does not mutate the input.
+ *
+ * @param params.deposits - The match set
+ * @param params.rateOf - Rate of one deposit for the selected payment method and currency
+ */
+export declare function sortDepositsByRate<D extends RankableDeposit>({ deposits, rateOf, }: {
+    deposits: readonly D[];
+    rateOf: (deposit: D) => bigint;
+}): D[];
+/**
+ * Is the user's currently-selected deposit the best-rate option
+ * across the full match set?
+ *
+ * Returns `false` when there's no selection or only one match —
+ * the "Best of N" badge gates on this so it doesn't claim "best" in
+ * a one-deposit set (trivially true and not useful), nor when the
+ * user manually picked a non-best alternative.
+ *
+ * @param sortedDeposits - The match set sorted by `sortDepositsByRate`.
+ *                         The first entry is the best.
+ */
+export declare function isSelectedDepositBest({ selectedDeposit, sortedDeposits, }: {
+    selectedDeposit: RankableDeposit | null;
+    sortedDeposits: readonly RankableDeposit[];
+}): boolean;
+export interface TargetedVerifier<V> {
+    /** Payment-method key that resolved (parent OR sub-provider). */
+    providerKey: ProviderKey | SubProviderKey;
+    /** The verifier struct attached to the deposit for that method. */
+    verifier: V;
+}
+/**
+ * Pick the deposit's verifier that should drive the maker-username
+ * lookup, the intent gating, and the payment method the intent is
+ * signalled on. Resolves the rail's own payment method (`zelle`) when the
+ * deposit carries it with a rate for this currency.
+ *
+ * Returns `null` when it does not — the deposit can't accept this currency
+ * through this payment method at all.
+ *
+ * ### Why only the rail
+ *
+ * The bank picker exists so the buyer's capture opens the right bank; it
+ * does not name a payment method. A Zelle attestation is issued for the
+ * rail — every bank template declares `metadata.platform: "zelle"` and
+ * the enclave route is `zelle/transfer_zelle_{bank}` — so an intent
+ * signalled on a bank-level method can never be fulfilled.
+ *
+ * This used to fall back to the picked bank, then to any other bank with a
+ * rate, so that pre-migration deposits stayed addressable. Those fallbacks
+ * were reachable only for deposits whose orders were guaranteed to strand,
+ * and `fetchMatchableDeposits` no longer surfaces such deposits at all.
+ * Returning null instead fails the order at the Reserve button — before the
+ * buyer sends money — rather than at submission, after they have.
+ *
+ * Generic over the verifier shape so tests can pass simplified
+ * structs without importing the full Ponder verifier type.
+ *
+ * The original implementation inlined a 3-loop chain in BrowsePanel's
+ * 30-line `useMemo`. Extracting to a pure helper makes the fallback
+ * order reviewable on its own AND lets us pin each branch without
+ * mounting the panel.
+ */
+export declare function resolveTargetedVerifier<V>({ deposit, paymentMethod, currency, }: {
+    deposit: DepositLikeForResolver<V> | null;
+    /**
+     * The rail. Pass the parent key even when the buyer has picked a bank — the
+     * bank is a capture-time routing detail, not a payment method.
+     */
+    paymentMethod: ProviderKey;
+    currency: Currency;
+}): TargetedVerifier<V> | null;
+/**
+ * The minimal Deposit shape `resolveTargetedVerifier` reads from.
+ * Lets tests pass in a fixture object instead of constructing a full
+ * `Deposit` class instance (which has dozens of unrelated getters).
+ *
+ * `chainId` is typed as `ChainId` (literal union) because
+ * `providerConfigs()` is keyed on that union; tests pass real chain
+ * literals (369, 8453) so the type narrowing holds. The verifier
+ * shape is generic so call sites can pass whatever the indexer
+ * client returns without us re-exporting that type here.
+ */
+export interface DepositLikeForResolver<V> {
+    chainId: ChainId;
+    getVerifier(key: ProviderKey | SubProviderKey | string): V | null | undefined;
+    currentConversionRates: ReadonlyMap<ProviderKey, ReadonlyMap<string, {
+        value: string;
+    } | undefined>>;
+}
+/**
+ * Build a `ProviderKey → totalVolume` map from the indexer's ordered
+ * verifier list. Used as the tiebreaker when multiple deposits share
+ * the same lowest rate in `useDefaultProviderByRate`.
+ *
+ * Returns an empty map when the input is missing or malformed —
+ * downstream callers treat "no volume data" as "no tiebreaker
+ * available", same as a zero entry.
+ */
+export declare function buildVolumeByProviderKey(verifiersByVolume: readonly {
+    verifier: string | null | undefined;
+    totalVolume: bigint;
+}[] | null | undefined): Map<ProviderKey, bigint>;
+/**
+ * Whole-form validity gate for the BrowsePanel Reserve CTA. Returns
+ * `true` only when EVERY precondition is met — any single false
+ * input disables the CTA.
+ *
+ * Order of fields here doesn't drive the disabled-label priority
+ * chain (that's in `reserveDisabledLabel`). This is the boolean
+ * AND of "can we submit at all?"
+ */
+export declare function isBrowseFormValid({ amountInInt, amountOutInt, hasSelectedDeposit, depositRate, amountExceedsCap, makerUnavailable, isOnCooldown, }: {
+    amountInInt: bigint | null;
+    amountOutInt: bigint | null;
+    hasSelectedDeposit: boolean;
+    depositRate: bigint | null | undefined;
+    amountExceedsCap: boolean;
+    makerUnavailable: boolean;
+    isOnCooldown: boolean;
+}): boolean;
+/**
+ * Decide whether the selected provider has to move because it cannot serve
+ * the selected currency, and to what.
+ *
+ * The buy panel's auto-pick only runs in auto mode, so a manual pick or a
+ * shared link can leave a buyer on a rail with no matching liquidity — Venmo
+ * is a United States dollar rail, so `?provider=venmo&currency=GBP` shows an
+ * empty order book and says nothing about why.
+ *
+ * @param selectedProvider - What the URL currently holds.
+ * @param fallbackProvider - Where to move the buyer. The caller passes its
+ *   volume-ranked, currency-filtered default so the replacement is the same
+ *   rail auto mode would have chosen.
+ * @returns The provider to switch to, or `null` to leave the selection alone.
+ *
+ * Returns `null` in two distinct situations, deliberately collapsed because
+ * the caller's action is identical — do nothing:
+ *
+ * 1. The selection is already fine.
+ * 2. The fallback cannot serve the currency either, so no rail this deployment
+ *    offers can. Moving the buyer would swap one dead end for another,
+ *    and returning the fallback here would make the caller's write re-trigger
+ *    this check forever.
+ */
+export declare function reconcileProviderForCurrency({ selectedProvider, fallbackProvider, chainId, currency, }: {
+    selectedProvider: ProviderKey;
+    fallbackProvider: ProviderKey;
+    chainId: ChainId;
+    currency: Currency;
+}): ProviderKey | null;

package/dist/buy/browsePanelDerivations.js

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview Pure derivations extracted from BrowsePanel.tsx.
+ *
+ * Each helper takes ordinary inputs (no React hooks, no wagmi state)
+ * and returns a value, so they're testable in isolation without
+ * mounting the panel or stubbing wagmi/router/appkit.
+ *
+ * Rationale for the split: BrowsePanel sits at the very top of the
+ * buy-flow surface area — every input flows through it. Inlining
+ * these derivations next to the JSX makes the file (1) hard to read
+ * and (2) impossible to test without a full router+wallet harness.
+ * Pulling them out is both a navigation and a coverage win.
+ *
+ * Keep helpers PURE: no side effects, no module-level state, no
+ * useState/useMemo. The panel still calls each one inside its own
+ * useMemo so React-level memoization stays at the call site.
+ */
+import { providerSupportsCurrency } from '../payment.js';
+import { parseUnits } from '../units.js';
+// ---------------------------------------------------------------------------
+// Amount input sanitization
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize a raw amount-input string so it only contains digits and a
+ * single `.`, and clamp the fractional precision to `maxDecimals`.
+ *
+ * Mirrors the live filter on the BrowsePanel `<Input>` element. Pure
+ * string transform — the call site wraps it in `setState` per-keystroke.
+ *
+ * @example
+ *   sanitizeAmountInput('12.34.56', 2) // '12.3456' → '12.34'  (clamp)
+ *   sanitizeAmountInput('1a2b.3', 2)   // '12.3'              (filter)
+ *   sanitizeAmountInput('100.500', 2)  // '100.50'            (clamp)
+ */
+export function sanitizeAmountInput(raw, maxDecimals) {
+    // Step 1: keep only digits + period. Replace every other character
+    // with '' rather than rejecting — pastes with thousands separators
+    // ('1,000.00') still yield '1000.00' instead of dropping the input.
+    const onlyDigitsAndDot = raw.replace(/[^\d.]/g, '');
+    // Step 2: collapse any second/third '.' into the first one. The
+    // regex captures everything from the first '.' onward and strips
+    // additional '.' inside that captured group.
+    const singleDot = onlyDigitsAndDot.replace(/(\..*)\./g, '$1');
+    // Step 3: clamp fractional length. Skip if the input has no '.'.
+    const dotIndex = singleDot.indexOf('.');
+    if (dotIndex === -1)
+        return singleDot;
+    // Special case: zero-decimal currency (JPY) — the dot itself is
+    // meaningless. Strip it entirely rather than leaving a trailing
+    // "100." that the downstream parser would render oddly.
+    if (maxDecimals === 0)
+        return singleDot.slice(0, dotIndex);
+    const fractional = singleDot.length - dotIndex - 1;
+    if (fractional <= maxDecimals)
+        return singleDot;
+    return singleDot.slice(0, dotIndex + maxDecimals + 1);
+}
+/**
+ * Parse the sanitized amount string into a USDC-6-decimal-base-units
+ * bigint (the unit every downstream calc uses).
+ *
+ * Returns `null` if the amount can't be parsed (empty, NaN, missing
+ * currency). Negative values clamp to `0n` rather than propagating
+ * the negative — the input filter already strips `-`, so this is
+ * defensive against a hypothetical refactor that accepts it.
+ *
+ * @param amount - The sanitized amount string ('100.50').
+ * @param currencyDecimals - Decimals of the fiat currency (USD = 2, JPY = 0).
+ *                           Falls back to 2 when undefined to match the
+ *                           panel's `currency?.decimals ?? 2` shape.
+ * @returns Amount as a bigint in USDC base units, or null.
+ */
+export function parseAmountToBaseUnits(amount, currencyDecimals) {
+    // 10^(6 - currencyDecimals) rebases from fiat decimals to USDC
+    // 6-decimal base units. For USD (decimals=2), converter = 10^4
+    // so $1.00 (= parseUnits('1.00') = 100n) becomes 1_000_000n.
+    // For JPY (decimals=0), converter = 10^6 so ¥1 (= 1n) becomes 1_000_000n.
+    const decimals = currencyDecimals ?? 2;
+    if (!amount)
+        return null;
+    try {
+        const parsed = parseUnits(amount, { decimals });
+        if (parsed < 0n)
+            return 0n;
+        const converter = 10n ** BigInt(6 - decimals);
+        return parsed * converter;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sort matched deposits by rate ascending (lowest fiat-per-USDC =
+ * best deal for the buyer), breaking ties by deposit id ascending
+ * so the order is deterministic across renders.
+ *
+ * The rate is injected so this module does not depend on the indexer
+ * client, which depends on this package.
+ *
+ * Returns a fresh array — does not mutate the input.
+ *
+ * @param params.deposits - The match set
+ * @param params.rateOf - Rate of one deposit for the selected payment method and currency
+ */
+export function sortDepositsByRate({ deposits, rateOf, }) {
+    return deposits.slice().sort((a, b) => {
+        const rateA = rateOf(a);
+        const rateB = rateOf(b);
+        if (rateA < rateB)
+            return -1;
+        if (rateA > rateB)
+            return 1;
+        if (a.depositId < b.depositId)
+            return -1;
+        if (a.depositId > b.depositId)
+            return 1;
+        return 0;
+    });
+}
+/**
+ * Is the user's currently-selected deposit the best-rate option
+ * across the full match set?
+ *
+ * Returns `false` when there's no selection or only one match —
+ * the "Best of N" badge gates on this so it doesn't claim "best" in
+ * a one-deposit set (trivially true and not useful), nor when the
+ * user manually picked a non-best alternative.
+ *
+ * @param sortedDeposits - The match set sorted by `sortDepositsByRate`.
+ *                         The first entry is the best.
+ */
+export function isSelectedDepositBest({ selectedDeposit, sortedDeposits, }) {
+    if (!selectedDeposit || sortedDeposits.length < 2)
+        return false;
+    return sortedDeposits[0]?.depositId === selectedDeposit.depositId;
+}
+/**
+ * Pick the deposit's verifier that should drive the maker-username
+ * lookup, the intent gating, and the payment method the intent is
+ * signalled on. Resolves the rail's own payment method (`zelle`) when the
+ * deposit carries it with a rate for this currency.
+ *
+ * Returns `null` when it does not — the deposit can't accept this currency
+ * through this payment method at all.
+ *
+ * ### Why only the rail
+ *
+ * The bank picker exists so the buyer's capture opens the right bank; it
+ * does not name a payment method. A Zelle attestation is issued for the
+ * rail — every bank template declares `metadata.platform: "zelle"` and
+ * the enclave route is `zelle/transfer_zelle_{bank}` — so an intent
+ * signalled on a bank-level method can never be fulfilled.
+ *
+ * This used to fall back to the picked bank, then to any other bank with a
+ * rate, so that pre-migration deposits stayed addressable. Those fallbacks
+ * were reachable only for deposits whose orders were guaranteed to strand,
+ * and `fetchMatchableDeposits` no longer surfaces such deposits at all.
+ * Returning null instead fails the order at the Reserve button — before the
+ * buyer sends money — rather than at submission, after they have.
+ *
+ * Generic over the verifier shape so tests can pass simplified
+ * structs without importing the full Ponder verifier type.
+ *
+ * The original implementation inlined a 3-loop chain in BrowsePanel's
+ * 30-line `useMemo`. Extracting to a pure helper makes the fallback
+ * order reviewable on its own AND lets us pin each branch without
+ * mounting the panel.
+ */
+export function resolveTargetedVerifier({ deposit, paymentMethod, currency, }) {
+    if (!deposit)
+        return null;
+    // The rail's own payment method, and only if it has a rate for this
+    // currency. This is the method an attestation can actually satisfy.
+    const mainRate = deposit.currentConversionRates
+        .get(paymentMethod)
+        ?.get(currency.contractId)?.value;
+    if (!mainRate)
+        return null;
+    const verifier = deposit.getVerifier(paymentMethod);
+    if (!verifier)
+        return null;
+    return { providerKey: paymentMethod, verifier };
+}
+// ---------------------------------------------------------------------------
+// Volume map + monthly default
+// ---------------------------------------------------------------------------
+/**
+ * Build a `ProviderKey → totalVolume` map from the indexer's ordered
+ * verifier list. Used as the tiebreaker when multiple deposits share
+ * the same lowest rate in `useDefaultProviderByRate`.
+ *
+ * Returns an empty map when the input is missing or malformed —
+ * downstream callers treat "no volume data" as "no tiebreaker
+ * available", same as a zero entry.
+ */
+export function buildVolumeByProviderKey(verifiersByVolume) {
+    const map = new Map();
+    if (!verifiersByVolume)
+        return map;
+    for (const entry of verifiersByVolume) {
+        if (entry.verifier) {
+            map.set(entry.verifier, entry.totalVolume);
+        }
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Form validity gate
+// ---------------------------------------------------------------------------
+/**
+ * Whole-form validity gate for the BrowsePanel Reserve CTA. Returns
+ * `true` only when EVERY precondition is met — any single false
+ * input disables the CTA.
+ *
+ * Order of fields here doesn't drive the disabled-label priority
+ * chain (that's in `reserveDisabledLabel`). This is the boolean
+ * AND of "can we submit at all?"
+ */
+export function isBrowseFormValid({ amountInInt, amountOutInt, hasSelectedDeposit, depositRate, amountExceedsCap, makerUnavailable, isOnCooldown, }) {
+    if (!amountInInt)
+        return false;
+    if (!amountOutInt)
+        return false;
+    if (!hasSelectedDeposit)
+        return false;
+    if (!depositRate)
+        return false;
+    if (amountExceedsCap)
+        return false;
+    if (makerUnavailable)
+        return false;
+    if (isOnCooldown)
+        return false;
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Provider / currency reconciliation
+// ---------------------------------------------------------------------------
+/**
+ * Decide whether the selected provider has to move because it cannot serve
+ * the selected currency, and to what.
+ *
+ * The buy panel's auto-pick only runs in auto mode, so a manual pick or a
+ * shared link can leave a buyer on a rail with no matching liquidity — Venmo
+ * is a United States dollar rail, so `?provider=venmo&currency=GBP` shows an
+ * empty order book and says nothing about why.
+ *
+ * @param selectedProvider - What the URL currently holds.
+ * @param fallbackProvider - Where to move the buyer. The caller passes its
+ *   volume-ranked, currency-filtered default so the replacement is the same
+ *   rail auto mode would have chosen.
+ * @returns The provider to switch to, or `null` to leave the selection alone.
+ *
+ * Returns `null` in two distinct situations, deliberately collapsed because
+ * the caller's action is identical — do nothing:
+ *
+ * 1. The selection is already fine.
+ * 2. The fallback cannot serve the currency either, so no rail this deployment
+ *    offers can. Moving the buyer would swap one dead end for another,
+ *    and returning the fallback here would make the caller's write re-trigger
+ *    this check forever.
+ */
+export function reconcileProviderForCurrency({ selectedProvider, fallbackProvider, chainId, currency, }) {
+    if (providerSupportsCurrency({ providerKey: selectedProvider, chainId, currency }))
+        return null;
+    if (!providerSupportsCurrency({ providerKey: fallbackProvider, chainId, currency }))
+        return null;
+    return fallbackProvider;
+}

package/dist/buy/browsePanelDerivations.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Tests for the pure derivations behind the buy panel.
+ *
+ * `browsePanelDerivations.ts` exists so these can be checked without mounting
+ * BrowsePanel. The reconciliation suite guards a bug that put buyers on a rail
+ * their currency cannot settle on. The rest cover helpers whose failure modes
+ * are silent (a swallowed keystroke, a wrong-by-10000 amount) rather than loud.
+ */
+export {};