@provex/utils 1.11.0 → 2.0.0

package/dist/buy/formatCurrencyBaseUnits.js

@@ -0,0 +1,34 @@
+/**
+ * @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 { formatCurrencyAmount } 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 function formatCurrencyBaseUnits({ amount, currency }) {
+    // `formatAmount` returns null only for a null amount, which the type excludes.
+    return formatCurrencyAmount(currency.formatAmount(amount), currency.ticker);
+}
+/**
+ * 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 function toAmountInputString({ amount, currency }) {
+    const scale = 10n ** BigInt(currency.decimals);
+    const whole = (amount / scale).toString();
+    if (currency.decimals === 0)
+        return whole;
+    const fraction = (amount % scale).toString().padStart(currency.decimals, '0');
+    return `${whole}.${fraction}`;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Tests for currency amounts held in base units.
+ *
+ * Two outputs serve two readers. One is for a person (symbol and separators).
+ * The other is for the amount field, whose sanitizer accepts digits and a dot.
+ */
+export {};

package/dist/buy/formatCurrencyBaseUnits.test.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Tests for currency amounts held in base units.
+ *
+ * Two outputs serve two readers. One is for a person (symbol and separators).
+ * The other is for the amount field, whose sanitizer accepts digits and a dot.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SUPPORTED_CURRENCIES } from '../currencies.js';
+import { formatCurrencyBaseUnits, toAmountInputString } from './formatCurrencyBaseUnits.js';
+const { USD, EUR, KRW } = SUPPORTED_CURRENCIES;
+describe('formatCurrencyBaseUnits', () => {
+    it('shows a symbol and the currency cents', () => {
+        assert.equal(formatCurrencyBaseUnits({ amount: 500n, currency: USD }), '$5.00');
+        assert.equal(formatCurrencyBaseUnits({ amount: 920n, currency: EUR }), '€9.20');
+    });
+    it('shows no cents for a currency without a minor unit', () => {
+        assert.equal(formatCurrencyBaseUnits({ amount: 14000n, currency: KRW }), '₩14,000');
+    });
+});
+describe('toAmountInputString', () => {
+    it('writes cents with a dot and no symbol', () => {
+        assert.equal(toAmountInputString({ amount: 500n, currency: USD }), '5.00');
+    });
+    it('pads a fraction below ten units to full width', () => {
+        assert.equal(toAmountInputString({ amount: 5n, currency: USD }), '0.05');
+    });
+    it('writes no separators, so the field sanitizer accepts it', () => {
+        assert.equal(toAmountInputString({ amount: 123456789n, currency: USD }), '1234567.89');
+    });
+    it('writes whole units, with no dot, for a zero-decimal currency', () => {
+        assert.equal(toAmountInputString({ amount: 14000n, currency: KRW }), '14000');
+    });
+});

package/dist/buy/fulfillTransactionHash.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Which `fulfillIntent` transaction hash the success screen links.
+ *
+ * The buyer's own browser sends `fulfillIntent`, so it knows the hash the
+ * moment the wallet broadcasts. The indexer learns the same hash only after
+ * it has processed the mined block, which can take several seconds more.
+ * The "View on explorer" link should not wait for that.
+ */
+import type { Hex } from 'viem';
+/** A hash the wallet broadcast, tagged with the intent it settles. */
+export interface SubmittedFulfillTransaction {
+    intentHash: Hex;
+    transactionHash: Hex;
+}
+/**
+ * Picks the hash for the explorer link.
+ *
+ * The indexer's hash wins when present: it is the transaction that actually
+ * fulfilled the intent, which differs from the broadcast hash after a
+ * speed-up replaced it. Until the indexer has it, the broadcast hash stands
+ * in, but only for the intent it was sent for.
+ *
+ * @returns The hash to link, or null when neither source has one.
+ */
+export declare function pickFulfillTransactionHash(options: {
+    intentHash: Hex | null;
+    indexedTransactionHash: Hex | null;
+    submitted: SubmittedFulfillTransaction | null;
+}): Hex | null;

package/dist/buy/fulfillTransactionHash.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Which `fulfillIntent` transaction hash the success screen links.
+ *
+ * The buyer's own browser sends `fulfillIntent`, so it knows the hash the
+ * moment the wallet broadcasts. The indexer learns the same hash only after
+ * it has processed the mined block, which can take several seconds more.
+ * The "View on explorer" link should not wait for that.
+ */
+/**
+ * Picks the hash for the explorer link.
+ *
+ * The indexer's hash wins when present: it is the transaction that actually
+ * fulfilled the intent, which differs from the broadcast hash after a
+ * speed-up replaced it. Until the indexer has it, the broadcast hash stands
+ * in, but only for the intent it was sent for.
+ *
+ * @returns The hash to link, or null when neither source has one.
+ */
+export function pickFulfillTransactionHash(options) {
+    if (options.indexedTransactionHash)
+        return options.indexedTransactionHash;
+    if (!options.intentHash || !options.submitted)
+        return null;
+    if (options.submitted.intentHash.toLowerCase() !== options.intentHash.toLowerCase())
+        return null;
+    return options.submitted.transactionHash;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Tests for the hash the success screen links.
+ *
+ * The explorer link should not wait for the indexer, but it must never link a
+ * transaction that belongs to another order.
+ */
+export {};

package/dist/buy/fulfillTransactionHash.test.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Tests for the hash the success screen links.
+ *
+ * The explorer link should not wait for the indexer, but it must never link a
+ * transaction that belongs to another order.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { pickFulfillTransactionHash } from './fulfillTransactionHash.js';
+const intentHash = `0x${'a'.repeat(64)}`;
+const otherIntentHash = `0x${'b'.repeat(64)}`;
+const broadcastHash = `0x${'1'.repeat(64)}`;
+const indexedHash = `0x${'2'.repeat(64)}`;
+describe('pickFulfillTransactionHash', () => {
+    it('links the broadcast hash before the indexer has the transaction', () => {
+        assert.equal(pickFulfillTransactionHash({
+            intentHash,
+            indexedTransactionHash: null,
+            submitted: { intentHash, transactionHash: broadcastHash },
+        }), broadcastHash);
+    });
+    it('prefers the indexed hash, which is the one that settled after a speed-up', () => {
+        assert.equal(pickFulfillTransactionHash({
+            intentHash,
+            indexedTransactionHash: indexedHash,
+            submitted: { intentHash, transactionHash: broadcastHash },
+        }), indexedHash);
+    });
+    it("never links another order's transaction", () => {
+        assert.equal(pickFulfillTransactionHash({
+            intentHash,
+            indexedTransactionHash: null,
+            submitted: { intentHash: otherIntentHash, transactionHash: broadcastHash },
+        }), null);
+    });
+    it('matches the intent regardless of hex letter case', () => {
+        assert.equal(pickFulfillTransactionHash({
+            intentHash: intentHash.toUpperCase().replace('0X', '0x'),
+            indexedTransactionHash: null,
+            submitted: { intentHash, transactionHash: broadcastHash },
+        }), broadcastHash);
+    });
+    it('returns null with neither source, so no dead link renders', () => {
+        assert.equal(pickFulfillTransactionHash({ intentHash, indexedTransactionHash: null, submitted: null }), null);
+    });
+});

package/dist/buy/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Pure helpers for the buy flow.
+ *
+ * Import from `@provex/utils/buy`. Nothing here touches React, a wallet, the
+ * translation layer or the indexer client, so any buy-flow surface can share
+ * these rules. Amounts stay bigint in base units until display.
+ */
+export * from './browsePanelDerivations.js';
+export * from './fillabilityNotice.js';
+export * from './formatCurrencyBaseUnits.js';
+export * from './fulfillTransactionHash.js';
+export * from './orderCap.js';
+export * from './postFeeAmount.js';
+export * from './providerSelectionMode.js';
+export * from './settlementReconciliation.js';
+export * from './submitStepDerivations.js';
+export * from './verifiableBanks.js';

package/dist/buy/index.js

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Pure helpers for the buy flow.
+ *
+ * Import from `@provex/utils/buy`. Nothing here touches React, a wallet, the
+ * translation layer or the indexer client, so any buy-flow surface can share
+ * these rules. Amounts stay bigint in base units until display.
+ */
+export * from './browsePanelDerivations.js';
+export * from './fillabilityNotice.js';
+export * from './formatCurrencyBaseUnits.js';
+export * from './fulfillTransactionHash.js';
+export * from './orderCap.js';
+export * from './postFeeAmount.js';
+export * from './providerSelectionMode.js';
+export * from './settlementReconciliation.js';
+export * from './submitStepDerivations.js';
+export * from './verifiableBanks.js';

package/dist/buy/orderCap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview The buyer's per-order cap, in settlement-token units.
+ *
+ * The server enforces the cap on the TOKEN amount of the order
+ * (`evaluateReputation` compares the intent amount, in USDC base units, with
+ * `getEffectiveCap`). So the cap is a USDC amount, and the UI compares the
+ * USDC the buyer would receive, never the typed fiat figure. What a cap lets a
+ * buyer type depends on the seller's rate: 100 USDC is 140,000 won at 1,400 won
+ * per USDC. See `maximumCurrencyAmountForOrderTokenAmount` in
+ * `@provex/utils/conversionRates` for that conversion.
+ *
+ * Null (platform locked for the tier, limits off) and the unlimited sentinel
+ * both mean "no cap", matching the server's `effectiveCap !== null` guard and
+ * the unreachable unlimited value.
+ */
+import type { ProviderKey, TakerTier } from '../payment.js';
+/** Settlement token decimals the cap is scaled by (USDC). */
+export declare const CAP_TOKEN_DECIMALS = 6;
+/**
+ * The per-order cap for one provider, in settlement-token base units.
+ *
+ * @param params.tier - The buyer's reputation tier; null means limits are off
+ * @param params.providerKey - Provider the buyer pays with (caps differ per provider)
+ * @returns The cap in token base units, or null when there is no cap
+ */
+export declare function orderCapInTokenUnits({ tier, providerKey, }: {
+    tier: TakerTier | null;
+    providerKey: ProviderKey;
+}): bigint | null;

package/dist/buy/orderCap.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview The buyer's per-order cap, in settlement-token units.
+ *
+ * The server enforces the cap on the TOKEN amount of the order
+ * (`evaluateReputation` compares the intent amount, in USDC base units, with
+ * `getEffectiveCap`). So the cap is a USDC amount, and the UI compares the
+ * USDC the buyer would receive, never the typed fiat figure. What a cap lets a
+ * buyer type depends on the seller's rate: 100 USDC is 140,000 won at 1,400 won
+ * per USDC. See `maximumCurrencyAmountForOrderTokenAmount` in
+ * `@provex/utils/conversionRates` for that conversion.
+ *
+ * Null (platform locked for the tier, limits off) and the unlimited sentinel
+ * both mean "no cap", matching the server's `effectiveCap !== null` guard and
+ * the unreachable unlimited value.
+ */
+import { getEffectiveCap, UNLIMITED_CAP_BASE_UNITS } from '../reputation.js';
+/** Settlement token decimals the cap is scaled by (USDC). */
+export const CAP_TOKEN_DECIMALS = 6;
+/**
+ * The per-order cap for one provider, in settlement-token base units.
+ *
+ * @param params.tier - The buyer's reputation tier; null means limits are off
+ * @param params.providerKey - Provider the buyer pays with (caps differ per provider)
+ * @returns The cap in token base units, or null when there is no cap
+ */
+export function orderCapInTokenUnits({ tier, providerKey, }) {
+    if (tier === null)
+        return null;
+    const cap = getEffectiveCap({ tier, providerKey, decimals: CAP_TOKEN_DECIMALS });
+    if (cap === null)
+        return null;
+    if (cap === UNLIMITED_CAP_BASE_UNITS)
+        return null;
+    return cap;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Tests for the buyer's per-order cap.
+ *
+ * The server checks the cap against the token amount of the order. The panel
+ * must read "no cap" in exactly the cases the server does, or it blocks a
+ * buyer the server would accept, or lets one through that it would refuse.
+ */
+export {};

package/dist/buy/orderCap.test.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Tests for the buyer's per-order cap.
+ *
+ * The server checks the cap against the token amount of the order. The panel
+ * must read "no cap" in exactly the cases the server does, or it blocks a
+ * buyer the server would accept, or lets one through that it would refuse.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { providers } from '../payment.js';
+import { CAP_TOKEN_DECIMALS, orderCapInTokenUnits } from './orderCap.js';
+describe('orderCapInTokenUnits', () => {
+    it('scales the cap by the settlement token decimals', () => {
+        // Neutral tier ($250 base) on Zelle (1.5x) is $375, in six-decimal base units.
+        assert.equal(CAP_TOKEN_DECIMALS, 6);
+        assert.equal(orderCapInTokenUnits({ tier: 'neutral', providerKey: providers.ZELLE }), 375000000n);
+    });
+    it('differs by provider for the same tier', () => {
+        assert.equal(orderCapInTokenUnits({ tier: 'peasant', providerKey: providers.REVOLUT }), 500000000n);
+        assert.equal(orderCapInTokenUnits({ tier: 'plus', providerKey: providers.VENMO }), 1000000000n);
+    });
+    it('means no cap when limits are off (tier is null)', () => {
+        assert.equal(orderCapInTokenUnits({ tier: null, providerKey: providers.VENMO }), null);
+    });
+    it('means no cap for the top tier, whose cap is the unlimited sentinel', () => {
+        // The sentinel is unreachable as an amount. Returning it would make every
+        // comparison pass by accident; null states the intent.
+        assert.equal(orderCapInTokenUnits({ tier: 'president', providerKey: providers.VENMO }), null);
+    });
+    it('means no cap when the platform is locked for the tier', () => {
+        // Matches the server guard `effectiveCap !== null`: a locked platform is
+        // refused elsewhere, not by an amount comparison.
+        assert.equal(orderCapInTokenUnits({ tier: 'peasant', providerKey: providers.PAYPAL }), null);
+    });
+});

package/dist/buy/postFeeAmount.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Token amounts after the protocol fee.
+ *
+ * The buy flow shows the buyer what they receive after the fee. Several
+ * panels computed that with the same few lines. This module is the one place
+ * for the rule. Amounts stay bigint in base units.
+ */
+import type { Currency } from '../currencies.js';
+import type { TokenInfo } from '../tokens.js';
+/**
+ * Tokens left after the protocol fee comes off a gross amount.
+ *
+ * A missing, zero or negative fee leaves the gross amount unchanged.
+ *
+ * @param params.grossAmount - Amount before the fee, in token base units
+ * @param params.feeBps - Protocol fee in basis points
+ */
+export declare function netAmountAfterFee({ grossAmount, feeBps, }: {
+    grossAmount: bigint;
+    feeBps: bigint | null | undefined;
+}): bigint;
+/** What the amount a buyer receives depends on. */
+export interface ReceivedAmountContext {
+    token: TokenInfo;
+    currency: Currency;
+    /** Buyer amount in the currency's base units; null or 0n means none typed. */
+    amountInCurrency: bigint | null;
+    /** Protocol fee in basis points; null while unknown. */
+    feeBps: bigint | null;
+}
+/**
+ * The tokens a buyer receives for one rate, after the protocol fee.
+ * Uses the same rule as the "You Receive" card, so a row and the card agree.
+ *
+ * @returns Net token amount, `0n` with no amount typed, or null while the fee is unknown
+ */
+export declare function computeReceivedAmount({ rate, token, currency, amountInCurrency, feeBps, }: ReceivedAmountContext & {
+    rate: bigint;
+}): bigint | null;

package/dist/buy/postFeeAmount.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Token amounts after the protocol fee.
+ *
+ * The buy flow shows the buyer what they receive after the fee. Several
+ * panels computed that with the same few lines. This module is the one place
+ * for the rule. Amounts stay bigint in base units.
+ */
+import { convertCurrencyToOrderTokenAmount } from '../conversionRates.js';
+import { calculateNetAmount } from '../fees.js';
+/**
+ * Tokens left after the protocol fee comes off a gross amount.
+ *
+ * A missing, zero or negative fee leaves the gross amount unchanged.
+ *
+ * @param params.grossAmount - Amount before the fee, in token base units
+ * @param params.feeBps - Protocol fee in basis points
+ */
+export function netAmountAfterFee({ grossAmount, feeBps, }) {
+    if (!feeBps || feeBps <= 0n)
+        return grossAmount;
+    return calculateNetAmount({ grossAmount, feeBps });
+}
+/**
+ * The tokens a buyer receives for one rate, after the protocol fee.
+ * Uses the same rule as the "You Receive" card, so a row and the card agree.
+ *
+ * @returns Net token amount, `0n` with no amount typed, or null while the fee is unknown
+ */
+export function computeReceivedAmount({ rate, token, currency, amountInCurrency, feeBps, }) {
+    if (feeBps === null)
+        return null;
+    if (!amountInCurrency)
+        return 0n;
+    const grossAmount = convertCurrencyToOrderTokenAmount({ token, currency, currencyAmountInt: amountInCurrency, rate });
+    return netAmountAfterFee({ grossAmount, feeBps });
+}

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Tests for token amounts after the protocol fee.
+ *
+ * The expected values were captured from the inline code in `index.tsx`,
+ * `BrowsePanel.tsx` and `providerQuotes.ts` before it moved here. Panels show
+ * these amounts as "You receive", so they must agree with each other and with
+ * the fee the contract takes.
+ */
+export {};

package/dist/buy/postFeeAmount.test.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Tests for token amounts after the protocol fee.
+ *
+ * The expected values were captured from the inline code in `index.tsx`,
+ * `BrowsePanel.tsx` and `providerQuotes.ts` before it moved here. Panels show
+ * these amounts as "You receive", so they must agree with each other and with
+ * the fee the contract takes.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { SUPPORTED_CURRENCIES } from '../currencies.js';
+import { getDefaultToken } from '../tokens.js';
+import { computeReceivedAmount, netAmountAfterFee } from './postFeeAmount.js';
+const token = getDefaultToken(369);
+describe('netAmountAfterFee', () => {
+    const rows = [
+        [0n, null, 0n],
+        [0n, 200n, 0n],
+        [1n, null, 1n],
+        [1n, 0n, 1n],
+        // A fee that rounds down to nothing on one base unit leaves the unit whole.
+        [1n, 1n, 1n],
+        [1n, 200n, 1n],
+        [1n, 10000n, 0n],
+        [99999999n, null, 99999999n],
+        [99999999n, 0n, 99999999n],
+        [99999999n, 1n, 99990000n],
+        [99999999n, 30n, 99700000n],
+        [99999999n, 200n, 98000000n],
+        [100000000n, undefined, 100000000n],
+        [100000000n, 1n, 99990000n],
+        [100000000n, 30n, 99700000n],
+        [100000000n, 200n, 98000000n],
+        [100000000n, 10000n, 0n],
+        [123456789n, 1n, 123444444n],
+        [123456789n, 30n, 123086419n],
+        [123456789n, 200n, 120987654n],
+    ];
+    for (const [grossAmount, feeBps, expected] of rows) {
+        it(`takes ${String(feeBps)} basis points off ${grossAmount}`, () => {
+            assert.equal(netAmountAfterFee({ grossAmount, feeBps }), expected);
+        });
+    }
+    it('treats a negative fee as no fee, so a bad read never pays the buyer more than the lock', () => {
+        assert.equal(netAmountAfterFee({ grossAmount: 100000000n, feeBps: -5n }), 100000000n);
+    });
+});
+describe('computeReceivedAmount', () => {
+    const usd = SUPPORTED_CURRENCIES.USD;
+    const eur = SUPPORTED_CURRENCIES.EUR;
+    const krw = SUPPORTED_CURRENCIES.KRW;
+    const rows = [
+        { name: 'ten dollars at 1.02, fee unknown', currency: usd, amountInCurrency: 1000n, rate: 1020000000000000000n, feeBps: null, expected: null },
+        { name: 'ten dollars at 1.02, no fee', currency: usd, amountInCurrency: 1000n, rate: 1020000000000000000n, feeBps: 0n, expected: 9803921n },
+        { name: 'ten dollars at 1.02, two percent fee', currency: usd, amountInCurrency: 1000n, rate: 1020000000000000000n, feeBps: 200n, expected: 9607843n },
+        { name: 'nine euros twenty at 0.92, fee unknown', currency: eur, amountInCurrency: 920n, rate: 920000000000000000n, feeBps: null, expected: null },
+        { name: 'nine euros twenty at 0.92, no fee', currency: eur, amountInCurrency: 920n, rate: 920000000000000000n, feeBps: 0n, expected: 10000000n },
+        { name: 'nine euros twenty at 0.92, two percent fee', currency: eur, amountInCurrency: 920n, rate: 920000000000000000n, feeBps: 200n, expected: 9800000n },
+        { name: '14,000 won at 1,400 per token, no fee (no cent grid)', currency: krw, amountInCurrency: 14000n, rate: 1400n * 10n ** 18n, feeBps: 0n, expected: 10000000n },
+        { name: '14,000 won at 1,400 per token, two percent fee', currency: krw, amountInCurrency: 14000n, rate: 1400n * 10n ** 18n, feeBps: 200n, expected: 9800000n },
+        { name: 'a zero rate yields nothing, not a crash', currency: usd, amountInCurrency: 1000n, rate: 0n, feeBps: 200n, expected: 0n },
+    ];
+    for (const row of rows) {
+        it(row.name, () => {
+            const received = computeReceivedAmount({
+                token,
+                currency: row.currency,
+                amountInCurrency: row.amountInCurrency,
+                rate: row.rate,
+                feeBps: row.feeBps,
+            });
+            assert.equal(received, row.expected);
+        });
+    }
+    it('returns zero when no amount is typed', () => {
+        assert.equal(computeReceivedAmount({ token, currency: usd, amountInCurrency: null, rate: 10n ** 18n, feeBps: 200n }), 0n);
+        assert.equal(computeReceivedAmount({ token, currency: usd, amountInCurrency: 0n, rate: 10n ** 18n, feeBps: 200n }), 0n);
+    });
+    it('returns null while the fee is unknown, even with no amount, so nothing ranks on a guess', () => {
+        assert.equal(computeReceivedAmount({ token, currency: usd, amountInCurrency: null, rate: 10n ** 18n, feeBps: null }), null);
+    });
+});

package/dist/buy/providerSelectionMode.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @fileoverview How the buyer's payment provider was chosen.
+ */
+/** How the provider was chosen. `manual` needs the URL pair `provider=X` and `mode=manual`. */
+export type ProviderSelectionMode = 'auto' | 'manual';

package/dist/buy/providerSelectionMode.js

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview How the buyer's payment provider was chosen.
+ */
+export {};

package/dist/buy/settlementReconciliation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview What the buyer got when an order settled for less than its ceiling.
+ *
+ * The gate signs an attestation that carries the gross token amount the buyer
+ * is owed. When that amount is below the amount locked for the order, the
+ * buyer paid less than the contracted maximum. The contract then releases the
+ * proportional amount and returns the unused lock to the maker. This module
+ * turns that fact into the figures the success panel shows.
+ *
+ * Amounts stay bigint in base units until the last step. Only the returned
+ * display strings are formatted.
+ */
+import type { ChainId } from '../chain.js';
+import type { IntentStruct } from '../intent.js';
+import type { V3AttestationResponseObject } from '../peer-types.js';
+/** The figures of a partial settlement, ready to show. */
+export interface SettlementReconciliation {
+    /** Symbol of the fiat currency the order was priced in. */
+    currencySymbol: string;
+    /** Fiat value of the full locked amount: the most the buyer could have claimed. */
+    contractedFiat: string;
+    /** Fiat value of the amount the attestation released. */
+    attestedFiat: string;
+    /** Tokens the buyer receives after the protocol fee. */
+    netToBuyer: string;
+    /** Protocol fee in tokens, or null when no fee applies so the caller can skip the row. */
+    protocolFee: string | null;
+    /** Locked tokens returned to the maker. */
+    returnedToMaker: string;
+}
+/**
+ * Work out the partial-settlement figures, or null when there is nothing to reconcile.
+ *
+ * Returns null when the attestation or the intent is missing, when the chain
+ * has no default token, when the currency is unknown, and when the released
+ * amount reaches the locked amount (a full settlement).
+ *
+ * @param params.attestation - The verified gate attestation; only `releaseAmount` is read
+ * @param params.intent - The intent that was fulfilled
+ * @param params.chainId - Chain the order settled on; picks the settlement token
+ * @param params.feeBps - Protocol fee in basis points; null or zero means no fee
+ */
+export declare function reconcileSettlement({ attestation, intent, chainId, feeBps, }: {
+    attestation: V3AttestationResponseObject | null | undefined;
+    intent: Pick<IntentStruct, 'amount' | 'conversionRate' | 'fiatCurrency'> | null | undefined;
+    chainId: ChainId;
+    feeBps: bigint | null | undefined;
+}): SettlementReconciliation | null;

package/dist/buy/settlementReconciliation.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview What the buyer got when an order settled for less than its ceiling.
+ *
+ * The gate signs an attestation that carries the gross token amount the buyer
+ * is owed. When that amount is below the amount locked for the order, the
+ * buyer paid less than the contracted maximum. The contract then releases the
+ * proportional amount and returns the unused lock to the maker. This module
+ * turns that fact into the figures the success panel shows.
+ *
+ * Amounts stay bigint in base units until the last step. Only the returned
+ * display strings are formatted.
+ */
+import { convertTokenInputToCurrency } from '../conversionRates.js';
+import { getCurrencyByContractId } from '../currencies.js';
+import { calculateFeeAmount } from '../fees.js';
+import { getDefaultToken } from '../tokens.js';
+import { formatUnits } from '../units.js';
+import { netAmountAfterFee } from './postFeeAmount.js';
+/**
+ * Work out the partial-settlement figures, or null when there is nothing to reconcile.
+ *
+ * Returns null when the attestation or the intent is missing, when the chain
+ * has no default token, when the currency is unknown, and when the released
+ * amount reaches the locked amount (a full settlement).
+ *
+ * @param params.attestation - The verified gate attestation; only `releaseAmount` is read
+ * @param params.intent - The intent that was fulfilled
+ * @param params.chainId - Chain the order settled on; picks the settlement token
+ * @param params.feeBps - Protocol fee in basis points; null or zero means no fee
+ */
+export function reconcileSettlement({ attestation, intent, chainId, feeBps, }) {
+    if (!attestation || !intent?.amount || !intent?.conversionRate)
+        return null;
+    const token = getDefaultToken(chainId);
+    if (!token)
+        return null;
+    const currency = getCurrencyByContractId(intent.fiatCurrency);
+    if (!currency)
+        return null;
+    const grossReleased = BigInt(attestation.typedDataValue.releaseAmount);
+    if (grossReleased >= intent.amount)
+        return null;
+    const returnedToMaker = intent.amount - grossReleased;
+    const fee = feeBps && feeBps > 0n ? calculateFeeAmount({ amount: grossReleased, feeBps }) : 0n;
+    const netToBuyer = netAmountAfterFee({ grossAmount: grossReleased, feeBps });
+    const contractedFiatRaw = convertTokenInputToCurrency({
+        token,
+        amountOutInt: intent.amount,
+        rate: intent.conversionRate,
+    });
+    const attestedFiatRaw = convertTokenInputToCurrency({
+        token,
+        amountOutInt: grossReleased,
+        rate: intent.conversionRate,
+    });
+    const format = (raw) => formatUnits(raw, { decimals: token.decimals, truncateDecimals: 2, padDecimals: 2 });
+    return {
+        currencySymbol: currency.symbol,
+        contractedFiat: format(contractedFiatRaw),
+        attestedFiat: format(attestedFiatRaw),
+        netToBuyer: format(netToBuyer),
+        protocolFee: fee > 0n ? format(fee) : null,
+        returnedToMaker: format(returnedToMaker),
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Tests for the partial-settlement figures on the success panel.
+ *
+ * The expected strings were captured from the inline code in `CompletePanel`
+ * before it moved here, so each row pins what buyers already saw. A buyer reads
+ * these numbers to learn what they received and what went back to the maker,
+ * so a rounding change here changes a figure that touches money.
+ */
+export {};