@provex/utils 1.11.0 → 2.0.0

package/dist/buy/fillabilityNotice.d.ts

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview What the buy panel tells the buyer about provider fillability.
+ *
+ * One pure decision turns the fillability summaries (from
+ * `useProviderFillability`) and the buyer's state into at most one notice.
+ * BrowsePanel renders what this returns and decides nothing itself.
+ *
+ * The rules, from the product owner:
+ *  1. A zero or empty amount never shows an error. There is nothing to fill yet.
+ *  2. Auto mode with no amount cycles through the providers that have sellers
+ *     (`carousel`). Display only. It ends when the buyer types an amount. With
+ *     reduced motion, or with fewer than two providers, nothing cycles.
+ *  3. Auto mode with an amount follows the auto pick. The panel does not fall
+ *     back to the volume leader when nothing fills (see `nearestAmount`).
+ *  4. A manual pick that cannot fill the amount is kept. If another provider
+ *     can, offer a one-tap switch to the best-rate one (`switchProvider`).
+ *     Never override the pick.
+ *  5. If no provider can fill the amount, suggest the nearest amount that works
+ *     (`nearestAmount`). The suggestion comes from the provider the buyer is on:
+ *     the selected one in manual mode, the one auto names otherwise. A manual
+ *     pick never gets another provider's amount; that is the switch segment's job.
+ *  6. "Can fill" includes the buyer's per-order cap. A provider whose cap is
+ *     below the amount does not count, and a suggestion never exceeds the cap.
+ */
+import type { ProviderKey } from '../payment.js';
+import type { ProviderSelectionMode } from './providerSelectionMode.js';
+/**
+ * What the decisions below read from one provider's fillability summary.
+ *
+ * The indexer client's `ProviderFillability` satisfies this shape. It is
+ * declared here because the indexer client depends on this package, so this
+ * package cannot import its type. Deposits are opaque: the decisions only
+ * count them and compare them by identity.
+ */
+export interface FillabilitySummary {
+    providerKey: ProviderKey;
+    /** Deposits that fill the buyer amount, best rate first. */
+    fillingDeposits: readonly unknown[];
+    /** One range per viable deposit, carrying the rate that deposit offers. */
+    fillableRanges: readonly {
+        deposit: unknown;
+        rate: bigint;
+    }[];
+}
+/**
+ * The closest amount a buyer could enter instead, when their amount fills
+ * nowhere. `raise` means the buyer must enter more, `lower` means less.
+ * `reason` says which limit the amount sits on.
+ *
+ * Mirrors `NearestWorkableAmount` in the indexer client, which produces it.
+ * A type test in the ui package fails when the two drift apart.
+ */
+export type NearestWorkableAmount = {
+    direction: 'raise';
+    reason: 'sellerMinimum';
+    amountInCurrency: bigint;
+    providerKey: ProviderKey;
+} | {
+    direction: 'lower';
+    reason: 'buyerCap' | 'sellerFunds' | 'sellerOrderMaximum';
+    amountInCurrency: bigint;
+    providerKey: ProviderKey;
+};
+/** At most one notice the panel shows about fillability. */
+export type FillabilityNotice = {
+    kind: 'none';
+} | {
+    kind: 'carousel';
+    providerKeys: readonly ProviderKey[];
+} | {
+    kind: 'switchProvider';
+    providerKey: ProviderKey;
+    amountInCurrency: bigint;
+} | ({
+    kind: 'nearestAmount';
+} & NearestWorkableAmount);
+export declare const NO_NOTICE: FillabilityNotice;
+export interface DecideFillabilityNoticeInput {
+    mode: ProviderSelectionMode;
+    /** Buyer amount in currency base units. Null or 0n means "no amount yet". */
+    amountInCurrency: bigint | null;
+    selectedProvider: ProviderKey;
+    summaries: readonly FillabilitySummary[];
+    /**
+     * The closest amount the given provider can fill, or the closest across all
+     * providers when given null. Null result: nothing to suggest.
+     */
+    nearestWorkableAmountFor: (providerKey: ProviderKey | null) => NearestWorkableAmount | null;
+    /** Providers with sellers, cheapest first. */
+    providersWithLiquidity: readonly ProviderKey[];
+    prefersReducedMotion: boolean;
+    /** True while the first deposit fetch has not finished. */
+    isLoading: boolean;
+    /** Providers the buyer cannot use right now (cooldown). Excluded from the switch offer. */
+    isProviderExcluded?: (providerKey: ProviderKey) => boolean;
+    /** True when the amount is above the buyer's per-order cap for this provider. */
+    exceedsCapFor?: (providerKey: ProviderKey) => boolean;
+}
+/**
+ * The provider with the lowest rate among those that can fill the amount.
+ * Same order as the auto pick: rate ascending, then provider key for a stable
+ * result. Skips excluded providers and the provider named in `except`.
+ *
+ * @returns The provider key, or null when none can fill
+ */
+export declare function bestRateFillingProvider({ summaries, isProviderExcluded, except, }: {
+    summaries: readonly FillabilitySummary[];
+    isProviderExcluded?: (providerKey: ProviderKey) => boolean;
+    except?: ProviderKey;
+}): ProviderKey | null;
+/** Decide the one fillability notice for the buy panel. */
+export declare function decideFillabilityNotice({ mode, amountInCurrency, selectedProvider, summaries, nearestWorkableAmountFor, providersWithLiquidity, prefersReducedMotion, isLoading, isProviderExcluded, exceedsCapFor, }: DecideFillabilityNoticeInput): FillabilityNotice;
+/**
+ * Whether the "No deposits" badge shows on the send card.
+ * It is an error badge, so it stays hidden when there is no amount, while
+ * data loads, when deposits are listed, or when a notice already explains it.
+ */
+export declare function shouldShowNoDepositsBadge({ amountInCurrency, hasListedDeposits, isLoading, notice, }: {
+    amountInCurrency: bigint | null;
+    hasListedDeposits: boolean;
+    isLoading: boolean;
+    notice: FillabilityNotice;
+}): boolean;
+/** Why the pill names the provider it names. */
+export type AutoProviderBasis = 
+/** Nothing has loaded yet: the only state without a provider. */
+'pending'
+/** Deposits are in but the maker check is not: a best guess from unchecked sellers. */
+ | 'provisional'
+/** The best-rate provider that can fill the amount, or the best-rate provider with sellers when there is no amount. */
+ | 'fills'
+/** An amount no provider can fill: the provider the Min or Max button uses. */
+ | 'nearest'
+/** No seller anywhere for this currency: the volume default. */
+ | 'volume-default';
+export interface AutoProvider {
+    /** The provider auto shows and works with. Null only for `pending`. */
+    provider: ProviderKey | null;
+    basis: AutoProviderBasis;
+}
+/**
+ * Decide which provider auto mode shows. Auto always names a concrete provider,
+ * the one the buyer would actually use; the only state without one is the wait
+ * for the very first deposits.
+ *
+ *  1. No deposits fetched yet: `pending` (a brief skeleton).
+ *  2. Deposits fetched, maker check still running: `provisional`, the best-rate
+ *     provider among UNCHECKED sellers. It names a provider early. The receive
+ *     card stays a skeleton and no notice shows until the check ends, so nothing
+ *     claims "no sellers" about a provider that may change; if the check removes
+ *     the sellers, the pill moves once.
+ *  3. Checked, no amount: the best-rate provider with sellers (the carousel, when
+ *     it runs, only cycles the display).
+ *  4. Checked, an amount some provider fills within the buyer's cap: the best-rate
+ *     one that fills it.
+ *  5. Checked, an amount nothing fills: the provider of the nearest-amount
+ *     suggestion, so the pill and the Min or Max button name the same provider.
+ *  6. No seller anywhere: the volume default. The receive card and the notice
+ *     explain there are no sellers.
+ */
+export declare function decideAutoProvider({ amountInCurrency, hasFetchedDeposits, isVerifying, isRankingPending, provisionalProvider, bestRateProvider, cheapestFillingProvider, someProviderFills, nearestWorkableAmount, providersWithLiquidity, volumeDefault, }: {
+    amountInCurrency: bigint | null;
+    /** The first cross-provider deposit fetch has finished. */
+    hasFetchedDeposits: boolean;
+    /** The maker check is still running. */
+    isVerifying: boolean;
+    /** The completion-rate ranking is still loading. */
+    isRankingPending: boolean;
+    /** Best-rate provider among unchecked sellers, or null. */
+    provisionalProvider: ProviderKey | null;
+    /** The ranked pick (best rate that clears the completion gate), or null. */
+    bestRateProvider: ProviderKey | null;
+    /** Cheapest provider that can serve the amount, ignoring the completion gate. */
+    cheapestFillingProvider: ProviderKey | null;
+    /** Some provider fills the amount within the buyer's cap. */
+    someProviderFills: boolean;
+    nearestWorkableAmount: NearestWorkableAmount | null;
+    /** Providers with checked sellers, cheapest first. */
+    providersWithLiquidity: readonly ProviderKey[];
+    /** The highest-volume provider that serves the currency. A concrete last resort. */
+    volumeDefault: ProviderKey;
+}): AutoProvider;
+/** What the provider pill and the "You Receive" card show while data loads. */
+export interface LoadingPresentation {
+    /**
+     * `loading`: a skeleton, only before auto has any provider to name.
+     * `selected`: show the provider. There is no neutral "Auto" state: auto always
+     * names a concrete provider.
+     */
+    pill: 'selected' | 'loading';
+    /** `skeleton` replaces any "no sellers" text until the data is settled. */
+    receiveCard: 'normal' | 'skeleton';
+}
+/**
+ * Decide how the pill and the receive card look while data is still loading.
+ *
+ * In auto mode the pill is a skeleton only until auto has a provider to name
+ * (see {@link decideAutoProvider}). In manual mode the pick is the buyer's own
+ * and always shows. In both modes the receive card shows a skeleton, never "no
+ * sellers", until loading ends, and in auto mode also while the pick can still
+ * move (provisional).
+ */
+export declare function decideLoadingPresentation({ mode, amountInCurrency, isFillabilityPending, isDepositsPending, isAutoPickPending, autoProvider, }: {
+    mode: ProviderSelectionMode;
+    amountInCurrency: bigint | null;
+    /** Cross-provider deposits or maker verification are still loading. */
+    isFillabilityPending: boolean;
+    /** The selected provider's own deposit list or maker check is still loading. */
+    isDepositsPending: boolean;
+    /** Auto mode only: the ranking is still being computed. */
+    isAutoPickPending: boolean;
+    /** What auto names; null only before the first data. */
+    autoProvider: AutoProvider;
+}): LoadingPresentation;

package/dist/buy/fillabilityNotice.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview What the buy panel tells the buyer about provider fillability.
+ *
+ * One pure decision turns the fillability summaries (from
+ * `useProviderFillability`) and the buyer's state into at most one notice.
+ * BrowsePanel renders what this returns and decides nothing itself.
+ *
+ * The rules, from the product owner:
+ *  1. A zero or empty amount never shows an error. There is nothing to fill yet.
+ *  2. Auto mode with no amount cycles through the providers that have sellers
+ *     (`carousel`). Display only. It ends when the buyer types an amount. With
+ *     reduced motion, or with fewer than two providers, nothing cycles.
+ *  3. Auto mode with an amount follows the auto pick. The panel does not fall
+ *     back to the volume leader when nothing fills (see `nearestAmount`).
+ *  4. A manual pick that cannot fill the amount is kept. If another provider
+ *     can, offer a one-tap switch to the best-rate one (`switchProvider`).
+ *     Never override the pick.
+ *  5. If no provider can fill the amount, suggest the nearest amount that works
+ *     (`nearestAmount`). The suggestion comes from the provider the buyer is on:
+ *     the selected one in manual mode, the one auto names otherwise. A manual
+ *     pick never gets another provider's amount; that is the switch segment's job.
+ *  6. "Can fill" includes the buyer's per-order cap. A provider whose cap is
+ *     below the amount does not count, and a suggestion never exceeds the cap.
+ */
+export const NO_NOTICE = { kind: 'none' };
+/**
+ * Rate a provider offers on its best filling deposit, or null when none fills.
+ * `fillingDeposits` is sorted best rate first, and each filling deposit has a
+ * range carrying its rate.
+ */
+function bestFillingRate(summary) {
+    const bestDeposit = summary.fillingDeposits[0];
+    if (!bestDeposit)
+        return null;
+    const range = summary.fillableRanges.find((candidate) => candidate.deposit === bestDeposit);
+    return range ? range.rate : null;
+}
+/**
+ * The provider with the lowest rate among those that can fill the amount.
+ * Same order as the auto pick: rate ascending, then provider key for a stable
+ * result. Skips excluded providers and the provider named in `except`.
+ *
+ * @returns The provider key, or null when none can fill
+ */
+export function bestRateFillingProvider({ summaries, isProviderExcluded, except, }) {
+    let best = null;
+    for (const summary of summaries) {
+        if (summary.providerKey === except)
+            continue;
+        if (isProviderExcluded?.(summary.providerKey))
+            continue;
+        const rate = bestFillingRate(summary);
+        if (rate === null)
+            continue;
+        const beatsBest = best === null ||
+            rate < best.rate ||
+            (rate === best.rate && summary.providerKey < best.providerKey);
+        if (beatsBest)
+            best = { providerKey: summary.providerKey, rate };
+    }
+    return best ? best.providerKey : null;
+}
+/** Decide the one fillability notice for the buy panel. */
+export function decideFillabilityNotice({ mode, amountInCurrency, selectedProvider, summaries, nearestWorkableAmountFor, providersWithLiquidity, prefersReducedMotion, isLoading, isProviderExcluded, exceedsCapFor, }) {
+    if (isLoading)
+        return NO_NOTICE;
+    if (!amountInCurrency) {
+        const canCycle = mode === 'auto' && !prefersReducedMotion && providersWithLiquidity.length >= 2;
+        return canCycle ? { kind: 'carousel', providerKeys: providersWithLiquidity } : NO_NOTICE;
+    }
+    const fillsWithinCap = (summary) => summary.fillingDeposits.length > 0 && !exceedsCapFor?.(summary.providerKey);
+    const selectedSummary = summaries.find((summary) => summary.providerKey === selectedProvider);
+    if (selectedSummary && fillsWithinCap(selectedSummary))
+        return NO_NOTICE;
+    const someProviderFills = summaries.some(fillsWithinCap);
+    if (!someProviderFills) {
+        const nearestWorkableAmount = nearestWorkableAmountFor(mode === 'manual' ? selectedProvider : null);
+        return nearestWorkableAmount ? { kind: 'nearestAmount', ...nearestWorkableAmount } : NO_NOTICE;
+    }
+    // Auto mode: the auto pick lands on a provider that fills. Nothing to say.
+    if (mode === 'auto')
+        return NO_NOTICE;
+    const alternative = bestRateFillingProvider({
+        summaries,
+        isProviderExcluded: (providerKey) => !!isProviderExcluded?.(providerKey) || !!exceedsCapFor?.(providerKey),
+        except: selectedProvider,
+    });
+    return alternative
+        ? { kind: 'switchProvider', providerKey: alternative, amountInCurrency }
+        : NO_NOTICE;
+}
+/**
+ * Whether the "No deposits" badge shows on the send card.
+ * It is an error badge, so it stays hidden when there is no amount, while
+ * data loads, when deposits are listed, or when a notice already explains it.
+ */
+export function shouldShowNoDepositsBadge({ amountInCurrency, hasListedDeposits, isLoading, notice, }) {
+    if (!amountInCurrency)
+        return false;
+    if (hasListedDeposits)
+        return false;
+    if (isLoading)
+        return false;
+    return notice.kind === 'none';
+}
+/**
+ * Decide which provider auto mode shows. Auto always names a concrete provider,
+ * the one the buyer would actually use; the only state without one is the wait
+ * for the very first deposits.
+ *
+ *  1. No deposits fetched yet: `pending` (a brief skeleton).
+ *  2. Deposits fetched, maker check still running: `provisional`, the best-rate
+ *     provider among UNCHECKED sellers. It names a provider early. The receive
+ *     card stays a skeleton and no notice shows until the check ends, so nothing
+ *     claims "no sellers" about a provider that may change; if the check removes
+ *     the sellers, the pill moves once.
+ *  3. Checked, no amount: the best-rate provider with sellers (the carousel, when
+ *     it runs, only cycles the display).
+ *  4. Checked, an amount some provider fills within the buyer's cap: the best-rate
+ *     one that fills it.
+ *  5. Checked, an amount nothing fills: the provider of the nearest-amount
+ *     suggestion, so the pill and the Min or Max button name the same provider.
+ *  6. No seller anywhere: the volume default. The receive card and the notice
+ *     explain there are no sellers.
+ */
+export function decideAutoProvider({ amountInCurrency, hasFetchedDeposits, isVerifying, isRankingPending, provisionalProvider, bestRateProvider, cheapestFillingProvider, someProviderFills, nearestWorkableAmount, providersWithLiquidity, volumeDefault, }) {
+    if (!hasFetchedDeposits)
+        return { provider: null, basis: 'pending' };
+    if (isVerifying) {
+        return provisionalProvider
+            ? { provider: provisionalProvider, basis: 'provisional' }
+            : { provider: null, basis: 'pending' };
+    }
+    const ranked = isRankingPending ? null : bestRateProvider;
+    if (!amountInCurrency) {
+        const provider = ranked ?? cheapestFillingProvider ?? providersWithLiquidity[0] ?? null;
+        return provider ? { provider, basis: 'fills' } : { provider: volumeDefault, basis: 'volume-default' };
+    }
+    if (someProviderFills) {
+        const provider = ranked ?? cheapestFillingProvider;
+        return provider ? { provider, basis: 'fills' } : { provider: volumeDefault, basis: 'volume-default' };
+    }
+    if (nearestWorkableAmount)
+        return { provider: nearestWorkableAmount.providerKey, basis: 'nearest' };
+    return { provider: volumeDefault, basis: 'volume-default' };
+}
+/**
+ * Decide how the pill and the receive card look while data is still loading.
+ *
+ * In auto mode the pill is a skeleton only until auto has a provider to name
+ * (see {@link decideAutoProvider}). In manual mode the pick is the buyer's own
+ * and always shows. In both modes the receive card shows a skeleton, never "no
+ * sellers", until loading ends, and in auto mode also while the pick can still
+ * move (provisional).
+ */
+export function decideLoadingPresentation({ mode, amountInCurrency, isFillabilityPending, isDepositsPending, isAutoPickPending, autoProvider, }) {
+    const autoPickUnsettled = mode === 'auto' && (isFillabilityPending || isAutoPickPending);
+    const receivePending = isFillabilityPending || isDepositsPending || autoPickUnsettled;
+    const receiveCard = !!amountInCurrency && receivePending ? 'skeleton' : 'normal';
+    const pill = mode === 'auto' && autoProvider.provider === null ? 'loading' : 'selected';
+    return { pill, receiveCard };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Tests for the fillability decisions, with plain-object summaries.
+ *
+ * The user-interface package keeps the end-to-end suite, which builds real
+ * deposits through the indexer client. These tests pin the decisions alone, so
+ * this package can change them without that client.
+ */
+export {};

package/dist/buy/fillabilityNotice.test.js

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Tests for the fillability decisions, with plain-object summaries.
+ *
+ * The user-interface package keeps the end-to-end suite, which builds real
+ * deposits through the indexer client. These tests pin the decisions alone, so
+ * this package can change them without that client.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { providers } from '../payment.js';
+import { bestRateFillingProvider, decideAutoProvider, decideFillabilityNotice, decideLoadingPresentation, shouldShowNoDepositsBadge, } from './fillabilityNotice.js';
+const { VENMO, CASHAPP, ZELLE } = providers;
+/** A summary whose deposits fill the amount at the given rate, or fill nothing when rate is null. */
+const summary = (providerKey, rate) => {
+    if (rate === null)
+        return { providerKey, fillingDeposits: [], fillableRanges: [] };
+    const deposit = { providerKey };
+    return { providerKey, fillingDeposits: [deposit], fillableRanges: [{ deposit, rate }] };
+};
+const nearest = {
+    direction: 'raise',
+    reason: 'sellerMinimum',
+    amountInCurrency: 500n,
+    providerKey: CASHAPP,
+};
+const baseInput = (overrides) => ({
+    mode: 'auto',
+    amountInCurrency: 1000n,
+    selectedProvider: VENMO,
+    summaries: [summary(VENMO, 102n), summary(CASHAPP, 101n)],
+    nearestWorkableAmountFor: () => null,
+    providersWithLiquidity: [CASHAPP, VENMO],
+    prefersReducedMotion: false,
+    isLoading: false,
+    ...overrides,
+});
+describe('decideFillabilityNotice', () => {
+    it('says nothing while data loads', () => {
+        assert.deepEqual(decideFillabilityNotice(baseInput({ isLoading: true })), { kind: 'none' });
+    });
+    it('cycles providers in auto mode with no amount', () => {
+        assert.deepEqual(decideFillabilityNotice(baseInput({ amountInCurrency: null })), {
+            kind: 'carousel',
+            providerKeys: [CASHAPP, VENMO],
+        });
+    });
+    it('does not cycle with reduced motion or a single provider', () => {
+        assert.deepEqual(decideFillabilityNotice(baseInput({ amountInCurrency: null, prefersReducedMotion: true })), {
+            kind: 'none',
+        });
+        assert.deepEqual(decideFillabilityNotice(baseInput({ amountInCurrency: null, providersWithLiquidity: [VENMO] })), {
+            kind: 'none',
+        });
+    });
+    it('offers a switch to the cheapest filling provider when a manual pick cannot fill', () => {
+        const notice = decideFillabilityNotice(baseInput({
+            mode: 'manual',
+            selectedProvider: ZELLE,
+            summaries: [summary(ZELLE, null), summary(VENMO, 102n), summary(CASHAPP, 101n)],
+        }));
+        assert.deepEqual(notice, { kind: 'switchProvider', providerKey: CASHAPP, amountInCurrency: 1000n });
+    });
+    it('keeps a manual pick that fills', () => {
+        const notice = decideFillabilityNotice(baseInput({ mode: 'manual', selectedProvider: VENMO }));
+        assert.deepEqual(notice, { kind: 'none' });
+    });
+    it('treats a provider over the buyer cap as unable to fill', () => {
+        const notice = decideFillabilityNotice(baseInput({ mode: 'manual', selectedProvider: VENMO, exceedsCapFor: (providerKey) => providerKey === VENMO }));
+        assert.deepEqual(notice, { kind: 'switchProvider', providerKey: CASHAPP, amountInCurrency: 1000n });
+    });
+    it('suggests the nearest amount when no provider fills', () => {
+        const asked = [];
+        const notice = decideFillabilityNotice(baseInput({
+            mode: 'manual',
+            selectedProvider: VENMO,
+            summaries: [summary(VENMO, null), summary(CASHAPP, null)],
+            nearestWorkableAmountFor: (providerKey) => {
+                asked.push(providerKey);
+                return nearest;
+            },
+        }));
+        assert.deepEqual(notice, { kind: 'nearestAmount', ...nearest });
+        // A manual pick never gets another provider's amount.
+        assert.deepEqual(asked, [VENMO]);
+    });
+    it('asks across all providers in auto mode', () => {
+        const asked = [];
+        decideFillabilityNotice(baseInput({
+            summaries: [summary(VENMO, null)],
+            nearestWorkableAmountFor: (providerKey) => {
+                asked.push(providerKey);
+                return null;
+            },
+        }));
+        assert.deepEqual(asked, [null]);
+    });
+});
+describe('decideFillabilityNotice: other providers fill but the buyer is not on one', () => {
+    it('says nothing in auto mode, because auto already lands on a provider that fills', () => {
+        const notice = decideFillabilityNotice(baseInput({ mode: 'auto', selectedProvider: ZELLE, summaries: [summary(ZELLE, null), summary(CASHAPP, 101n)] }));
+        assert.deepEqual(notice, { kind: 'none' });
+    });
+    it('offers no switch when every other filling provider is in cooldown', () => {
+        const notice = decideFillabilityNotice(baseInput({
+            mode: 'manual',
+            selectedProvider: ZELLE,
+            summaries: [summary(ZELLE, null), summary(CASHAPP, 101n)],
+            isProviderExcluded: (providerKey) => providerKey === CASHAPP,
+        }));
+        assert.deepEqual(notice, { kind: 'none' });
+    });
+    it('offers no switch when every other filling provider is over the buyer cap', () => {
+        const notice = decideFillabilityNotice(baseInput({
+            mode: 'manual',
+            selectedProvider: ZELLE,
+            summaries: [summary(ZELLE, null), summary(CASHAPP, 101n)],
+            exceedsCapFor: (providerKey) => providerKey === CASHAPP,
+        }));
+        assert.deepEqual(notice, { kind: 'none' });
+    });
+    it('says nothing when no provider fills and there is no nearer amount to suggest', () => {
+        const notice = decideFillabilityNotice(baseInput({ mode: 'manual', summaries: [summary(VENMO, null)], nearestWorkableAmountFor: () => null }));
+        assert.deepEqual(notice, { kind: 'none' });
+    });
+});
+describe('bestRateFillingProvider: inconsistent summaries', () => {
+    it('ignores a filling deposit that has no rate range, so a rate is never invented', () => {
+        const orphan = { providerKey: VENMO, fillingDeposits: [{}], fillableRanges: [] };
+        assert.equal(bestRateFillingProvider({ summaries: [orphan] }), null);
+    });
+    it('keeps the earlier provider when a later one offers a worse rate', () => {
+        assert.equal(bestRateFillingProvider({ summaries: [summary(VENMO, 101n), summary(CASHAPP, 102n)] }), VENMO);
+    });
+});
+describe('bestRateFillingProvider', () => {
+    const summaries = [summary(VENMO, 102n), summary(CASHAPP, 101n), summary(ZELLE, 101n)];
+    it('picks the lowest rate and breaks a tie by provider key', () => {
+        assert.equal(bestRateFillingProvider({ summaries }), CASHAPP);
+    });
+    it('skips the named provider and excluded providers', () => {
+        assert.equal(bestRateFillingProvider({ summaries, except: CASHAPP }), ZELLE);
+        assert.equal(bestRateFillingProvider({ summaries, isProviderExcluded: (providerKey) => providerKey !== VENMO }), VENMO);
+    });
+    it('returns null when none fill', () => {
+        assert.equal(bestRateFillingProvider({ summaries: [summary(VENMO, null)] }), null);
+    });
+});
+describe('shouldShowNoDepositsBadge', () => {
+    it('shows only for a real amount, nothing listed, nothing loading and no notice', () => {
+        const base = { amountInCurrency: 500n, hasListedDeposits: false, isLoading: false, notice: { kind: 'none' } };
+        assert.equal(shouldShowNoDepositsBadge(base), true);
+        assert.equal(shouldShowNoDepositsBadge({ ...base, amountInCurrency: 0n }), false);
+        assert.equal(shouldShowNoDepositsBadge({ ...base, hasListedDeposits: true }), false);
+        assert.equal(shouldShowNoDepositsBadge({ ...base, isLoading: true }), false);
+        assert.equal(shouldShowNoDepositsBadge({ ...base, notice: { kind: 'nearestAmount', ...nearest } }), false);
+    });
+});
+describe('decideAutoProvider', () => {
+    const settled = {
+        amountInCurrency: 1000n,
+        hasFetchedDeposits: true,
+        isVerifying: false,
+        isRankingPending: false,
+        provisionalProvider: null,
+        bestRateProvider: CASHAPP,
+        cheapestFillingProvider: VENMO,
+        someProviderFills: true,
+        nearestWorkableAmount: null,
+        providersWithLiquidity: [CASHAPP, VENMO],
+        volumeDefault: ZELLE,
+    };
+    it('names no provider before the first deposits arrive', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, hasFetchedDeposits: false }), { provider: null, basis: 'pending' });
+    });
+    it('names a provisional provider while the maker check runs', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, isVerifying: true, provisionalProvider: VENMO }), {
+            provider: VENMO,
+            basis: 'provisional',
+        });
+        assert.deepEqual(decideAutoProvider({ ...settled, isVerifying: true }), { provider: null, basis: 'pending' });
+    });
+    it('names the ranked provider that fills the amount', () => {
+        assert.deepEqual(decideAutoProvider(settled), { provider: CASHAPP, basis: 'fills' });
+    });
+    it('falls back to the cheapest filling provider while ranking loads', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, isRankingPending: true }), { provider: VENMO, basis: 'fills' });
+    });
+    it('names the provider of the nearest amount when nothing fills', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, someProviderFills: false, nearestWorkableAmount: nearest }), {
+            provider: CASHAPP,
+            basis: 'nearest',
+        });
+    });
+    it('names the first provider with liquidity when no amount is typed and nothing ranks', () => {
+        assert.deepEqual(decideAutoProvider({
+            ...settled,
+            amountInCurrency: null,
+            bestRateProvider: null,
+            cheapestFillingProvider: null,
+            providersWithLiquidity: [VENMO],
+        }), { provider: VENMO, basis: 'fills' });
+    });
+    it('names the volume default when the buyer cap leaves no provider to name for an amount', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, bestRateProvider: null, cheapestFillingProvider: null }), { provider: ZELLE, basis: 'volume-default' });
+    });
+    it('names the volume default when nothing fills and there is no nearer amount', () => {
+        assert.deepEqual(decideAutoProvider({ ...settled, someProviderFills: false, nearestWorkableAmount: null }), {
+            provider: ZELLE,
+            basis: 'volume-default',
+        });
+    });
+    it('falls back to the volume default when no seller exists', () => {
+        assert.deepEqual(decideAutoProvider({
+            ...settled,
+            amountInCurrency: null,
+            bestRateProvider: null,
+            cheapestFillingProvider: null,
+            providersWithLiquidity: [],
+        }), { provider: ZELLE, basis: 'volume-default' });
+    });
+});
+describe('decideLoadingPresentation', () => {
+    const idle = {
+        mode: 'auto',
+        amountInCurrency: 1000n,
+        isFillabilityPending: false,
+        isDepositsPending: false,
+        isAutoPickPending: false,
+        autoProvider: { provider: VENMO, basis: 'fills' },
+    };
+    it('shows a skeleton pill only in auto mode before a provider exists', () => {
+        assert.equal(decideLoadingPresentation({ ...idle, autoProvider: { provider: null, basis: 'pending' } }).pill, 'loading');
+        assert.equal(decideLoadingPresentation({ ...idle, mode: 'manual', autoProvider: { provider: null, basis: 'pending' } }).pill, 'selected');
+    });
+    it('shows a skeleton receive card instead of "no sellers" while data loads', () => {
+        assert.equal(decideLoadingPresentation({ ...idle, isDepositsPending: true }).receiveCard, 'skeleton');
+        assert.equal(decideLoadingPresentation({ ...idle, isAutoPickPending: true }).receiveCard, 'skeleton');
+        assert.equal(decideLoadingPresentation(idle).receiveCard, 'normal');
+    });
+    it('keeps the receive card normal with no amount typed', () => {
+        assert.equal(decideLoadingPresentation({ ...idle, amountInCurrency: null, isDepositsPending: true }).receiveCard, 'normal');
+    });
+    it('does not wait on the auto pick in manual mode', () => {
+        assert.equal(decideLoadingPresentation({ ...idle, mode: 'manual', isAutoPickPending: true }).receiveCard, 'normal');
+    });
+});

package/dist/buy/formatCurrencyBaseUnits.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Format a currency amount held in base units.
+ *
+ * Two outputs, for two audiences:
+ *  - `formatCurrencyBaseUnits` is for reading: symbol, thousands separators,
+ *    and the currency's own decimals (cents for USD, none for KRW).
+ *  - `toAmountInputString` is for the amount field: plain digits with a dot,
+ *    no symbol and no separators, so the field's own sanitizer accepts it.
+ */
+import { type Currency } from '../currencies.js';
+/**
+ * Display string such as `$5.00`, `€9.20` or `₩14,000`.
+ *
+ * @param params.amount - Amount in the currency's base units
+ * @param params.currency - Currency whose symbol and decimals apply
+ */
+export declare function formatCurrencyBaseUnits({ amount, currency }: {
+    amount: bigint;
+    currency: Currency;
+}): string;
+/**
+ * Plain decimal string for the amount input, such as `5.00` or `14000`.
+ *
+ * @param params.amount - Amount in the currency's base units
+ * @param params.currency - Currency whose decimals apply
+ */
+export declare function toAmountInputString({ amount, currency }: {
+    amount: bigint;
+    currency: Currency;
+}): string;