@funkit/connect 9.4.3 → 9.5.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @funkit/connect
 
+## 9.5.0
+
+### Minor Changes
+
+- fec5e96: Add QuoteMode types (EXACT_IN, EXACT_OUT, ONE_TO_ONE), QuoteBuilder strategy pattern, dnum-based token math utilities, and quote mode resolution logic
+- 3b3eeba: Add swapped withdrawal method selection screen behind enableswappedwithdrawal flag
+
+### Patch Changes
+
+- 9993a99: fix(connect): use modal=false to prevent multiple dropdowns staying open on client sites that override body scroll locking
+- 0de9370: fix(connect): swapped loading state
+- Updated dependencies [fec5e96]
+  - @funkit/utils@1.2.7
+  - @funkit/api-base@3.0.5
+
 ## 9.4.3
 
 ### Patch Changes

package/dist/domains/quoteMode/exactIn.d.ts

@@ -0,0 +1,2 @@
+import { type QuoteBuilder } from './types';
+export declare function createExactInBuilder(): QuoteBuilder;

package/dist/domains/quoteMode/exactOut.d.ts

@@ -0,0 +1,2 @@
+import { type QuoteBuilder } from './types';
+export declare function createExactOutBuilder(): QuoteBuilder;

package/dist/domains/quoteMode/gasEstimate.d.ts

@@ -0,0 +1,15 @@
+import type { Dnum } from 'dnum';
+/**
+ * Hardcoded gas-unit estimate for a checkout transaction involving a
+ * native token. Checkout relay/swap transactions typically consume
+ * 300k–500k gas; we use 1M as a conservative baseline. The builder
+ * applies an additional 1.5x multiplier on top, giving ~1.5M effective.
+ */
+export declare const CHECKOUT_GAS_UNITS = 1000000n;
+/**
+ * Compute a gas cost estimate in wei as an 18-decimal Dnum.
+ *
+ * @param gasPriceWei - Current gas price in wei (e.g. from `getGasPrice`)
+ * @returns Gas estimate as a Dnum: [gasUnits * gasPriceWei, 18]
+ */
+export declare function getGasEstimateWei(gasPriceWei: bigint): Dnum;

package/dist/domains/quoteMode/index.d.ts

@@ -0,0 +1,9 @@
+export { QuickOptionType, QuoteBuildType, QuoteMode, RetryActionType, RetryErrorReason, } from './types';
+export type { QuoteBuilder, QuoteBuildResult, QuoteRetryError, RetryAction, QuoteDisplayAmounts, MaxSendableParams, } from './types';
+export type { Dnum } from 'dnum';
+export { createExactOutBuilder } from './exactOut';
+export { createExactInBuilder } from './exactIn';
+export { createOneToOneBuilder } from './oneToOne';
+export { createQuoteBuilder, _resolveQuoteMode } from './resolveQuoteMode';
+export type { CreateQuoteBuilderParams } from './resolveQuoteMode';
+export { getGasEstimateWei, CHECKOUT_GAS_UNITS } from './gasEstimate';

package/dist/domains/quoteMode/oneToOne.d.ts

@@ -0,0 +1,21 @@
+import { type QuoteBuilder } from './types';
+/**
+ * @TODO: Wire it up to UI components, currently it is not used.
+ * More about the purpose of this quote mode: https://www.notion.so/the-fun-group/Refactoring-Quote-Mode-Selection-Max-Button-Behavior-327fc3b2a00281eea8f0eb0a28a08045#8d7655b63b9c416a91021718702ffe8f
+ *
+ * ONE_TO_ONE is EXACT_IN with subsidized fees — the user sends X tokens and
+ * receives exactly X tokens on the destination chain. All bridge/relay fees
+ * are absorbed by the protocol, so send === receive and feesUsd === '0'.
+ *
+ * Mechanically it inherits all EXACT_IN behavior (max sendable calculation,
+ * quote request building, retry logic, quick options) and only overrides
+ * `getDisplayAmounts` to reflect the 1:1 guarantee.
+ *
+ * @TODO: Revisit whether ONE_TO_ONE should remain a separate builder or be
+ * collapsed into EXACT_IN with overrides. Jeremy suspects it may just be
+ * EXACT_IN with some config flags. Discuss with Connor before removing since
+ * it's in the approved design doc.
+ * See: https://fun-xyz.slack.com/archives/C0AN3BXPBNK/p1775167066455859
+ * Tracked: https://linear.app/funxyz/issue/ENG-3282/revisit-one-to-one-quote-mode-consider-collapsing-into-exact-in
+ */
+export declare function createOneToOneBuilder(): QuoteBuilder;

package/dist/domains/quoteMode/resolveQuoteMode.d.ts

@@ -0,0 +1,19 @@
+import { type QuoteBuilder } from './types';
+export interface CreateQuoteBuilderParams {
+    hasPostAction: boolean;
+    isExactInEnabled: boolean;
+    providerSupportsExactInWithActions?: boolean;
+}
+/**
+ * Determines the quote mode and returns the corresponding builder.
+ *
+ * Resolution order:
+ * 1. Feature gate off → EXACT_OUT (Stage 1 default)
+ * 2. No action params → EXACT_IN
+ * 3. Action params + provider supports → EXACT_IN
+ * 4. Action params + no support → EXACT_OUT
+ *
+ * Note: ONE_TO_ONE (subsidized routes) is not yet auto-detected.
+ * It will be enabled in a future phase when subsidy detection is implemented.
+ */
+export declare function createQuoteBuilder({ hasPostAction, isExactInEnabled, providerSupportsExactInWithActions, }: CreateQuoteBuilderParams): QuoteBuilder;

package/dist/domains/quoteMode/types.d.ts

@@ -0,0 +1,125 @@
+import type { Dnum } from 'dnum';
+import type { PaymentMethod } from '../../domains/paymentMethods';
+import type { FunkitCheckoutQuoteResult } from '../../domains/quote';
+export declare enum QuoteMode {
+    EXACT_IN = "EXACT_IN",
+    EXACT_OUT = "EXACT_OUT",
+    ONE_TO_ONE = "ONE_TO_ONE"
+}
+export declare enum QuoteBuildType {
+    EXACT_IN = "exactIn",
+    EXACT_OUT = "exactOut"
+}
+export declare enum RetryActionType {
+    CALIBRATE_AMOUNT = "calibrateAmount",
+    REFETCH_BALANCE = "refetchBalance",
+    GIVE_UP = "giveUp"
+}
+export declare enum RetryErrorReason {
+    INSUFFICIENT_BALANCE = "insufficientBalance",
+    INSUFFICIENT_AMOUNT = "insufficientAmount",
+    INTERNAL = "internal"
+}
+export declare enum QuickOptionType {
+    SET_TOKEN_AMOUNT = "setTokenAmount",
+    SET_FIAT_AMOUNT = "setFiatAmount"
+}
+export interface QuoteRetryError {
+    reason: RetryErrorReason;
+    maxTargetAssetAmount?: Dnum;
+    minTargetAssetAmount?: Dnum;
+}
+export type QuoteBuildResult = {
+    type: QuoteBuildType.EXACT_IN;
+    fromAmountBaseUnit: string;
+} | {
+    type: QuoteBuildType.EXACT_OUT;
+    toAmountBaseUnit: string;
+};
+export type RetryAction = {
+    type: RetryActionType.CALIBRATE_AMOUNT;
+    newAmountBaseUnit: Dnum;
+} | {
+    type: RetryActionType.REFETCH_BALANCE;
+} | {
+    type: RetryActionType.GIVE_UP;
+};
+export interface QuoteDisplayAmounts {
+    /** The primary dollar/token amount shown at the top of the confirmation screen */
+    confirmationScreenDisplayAmount: string;
+    /** "You send" line */
+    sendAmount: string;
+    /** "You receive" line */
+    receiveAmount: string;
+    /** Whether the send amount is exact (vs estimated) */
+    isSendExact: boolean;
+    /** Whether the receive amount is exact (vs estimated) */
+    isReceiveExact: boolean;
+    /** Total fees in USD. '0' for ONE_TO_ONE */
+    feesUsd: string;
+}
+export interface MaxSendableParams {
+    /** Token balance as a Dnum */
+    tokenBalanceBaseUnit: Dnum;
+    /** Whether the token is the chain's native token (ETH, MATIC, etc.) */
+    isNativeToken: boolean;
+    /** Estimated gas price in wei (required for native tokens) */
+    gasEstimateWei?: Dnum;
+    /** Token price in USD (used for fee estimation in token terms) */
+    unitPrice: number;
+    /** Checkout target chain ID */
+    targetChainId: string;
+    /** Source asset chain ID */
+    assetChainId: string;
+    /** Payment method */
+    paymentMethod: PaymentMethod | undefined;
+}
+export interface UsdAvailableAmountParams {
+    /** Source asset USD value */
+    assetUsdAmount: number | null | undefined;
+    /** Checkout target chain ID */
+    targetChainId: string;
+    /** Source asset chain ID */
+    assetChainId: string | undefined;
+    /** Payment method */
+    paymentMethod: PaymentMethod | undefined;
+}
+export interface QuoteBuilder {
+    readonly mode: QuoteMode;
+    /** Compute the USD available amount for the source asset, accounting for fees where applicable */
+    getUsdAvailableAmount(params: UsdAvailableAmountParams): number | null;
+    /** Compute max sendable token amount for the max button */
+    getMaxSendableAmount(params: MaxSendableParams): Dnum;
+    /** Build the quote request params from the user's input */
+    buildQuoteRequest(params: {
+        tokenAmountBaseUnit: Dnum;
+    }): QuoteBuildResult;
+    /** Handle quote failure. Returns action to take. */
+    handleRetry(params: {
+        error: QuoteRetryError;
+    }): RetryAction;
+    /** Derive display amounts for confirmation screen.
+     * @param inputAmount — the user's input in human-readable form (e.g., 15.9) */
+    getDisplayAmounts(quote: FunkitCheckoutQuoteResult, inputAmount: number): QuoteDisplayAmounts;
+    /** Whether the confirmation screen can show a dollar amount before the quote resolves */
+    hasKnownAmountBeforeQuote(config: {
+        targetAssetAmount?: number;
+        targetAssetTicker: string;
+        finalizedToken?: unknown;
+    }): boolean;
+    /** Compute the token/fiat amount for a quick-option percentage button.
+     *  Returns the action to dispatch to the state reducer. */
+    computeQuickOptionAmount(params: {
+        percentage: number;
+        tokenBalanceBaseUnit: Dnum | null;
+        frozenUnitPrice: number | null;
+        usdAvailableAmount: number | null;
+    }): {
+        type: QuickOptionType.SET_TOKEN_AMOUNT;
+        tokenAmountBaseUnit: Dnum;
+        frozenUnitPrice: number;
+    } | {
+        type: QuickOptionType.SET_FIAT_AMOUNT;
+        fiatAmount: number;
+    };
+}

package/dist/hooks/queries/useFops.d.ts

@@ -9,4 +9,5 @@ export declare const useFops: () => {
         savedFormsOfPayments: SavedFormOfPayment[];
     } | undefined;
     isLoading: boolean;
+    isFetching: boolean;
 };

package/dist/hooks/queries/useWithdrawFops.d.ts

@@ -0,0 +1,9 @@
+import { type GetFopsResponse } from '@funkit/api-base';
+/**
+ * Hook to fetch available withdrawal forms of payment.
+ * MVP: Returns static mock data. Will be replaced with a real API call later.
+ */
+export declare const useWithdrawFops: () => {
+    data: GetFopsResponse;
+    isLoading: boolean;
+};

package/dist/hooks/track/WithdrawModalEvent.d.ts

@@ -2,6 +2,9 @@ export declare enum WithdrawModalEvent {
     MODAL_OPENED = "fw::modal_opened",
     MODAL_READY = "fw::modal_ready",
     MODAL_CLOSED = "fw::modal_closed",
+    ENTER_AMOUNT_VIEWED = "fw::enter_amount_viewed",
+    CRYPTO_ADDRESS_SELECTED = "fw::crypto_address_selected",
+    CASH_FOP_SELECTED = "fw::cash_fop_selected",
     FINAL_QUOTE = "fw::quote::final_quote",
     VIEW_TRANSACTION_BREAKDOWN = "fw::quote::view_transaction_breakdown",
     PENDING_CALLBACK = "fw::pending_callback",

package/dist/hooks/useCheckoutTransferInit.d.ts

@@ -5,6 +5,7 @@ interface UseCheckoutTransferInitResponse {
     transferInit: CheckoutInitTokenTransferResponse | undefined;
     recipientAddr: FunAddress;
     isLoading: boolean;
+    isFetching: boolean;
 }
 type CheckoutTokenTransferParams = Omit<CheckoutInitTokenTransferAddressParams, 'logger' | 'clientMetadata'>;
 export declare function checkoutTransferFetch(params: CheckoutTokenTransferParams): Promise<CheckoutInitTokenTransferResponse>;