feat(pay-card): add a Balance screen to the devtool

The linked-wallet total has no UI that shows the number itself, so a wrong
total cannot be told apart from a wrong formatter. The devtool shows what the
calculation returned.

- Opening the screen requests the wallets: the queries are skipped until then,
  so the tool does not fetch a cardholder's wallets to render a list of flags.
- The total is rendered raw, in the counter-value currency's smallest unit.
  Formatting it would hide the unit bug this screen exists to catch.
- A partial total says so. A wallet the rates could not price is left out of the
  sum rather than counted as zero, which otherwise reads as a complete total.
- Pricing needs the app's rates and currency settings, so the host passes its
  resolver in, the same way the card visual gets one.

Author: philipptpunkt

.changeset/pay-card-devtools-balance.md

@@ -0,0 +1,12 @@
+---
+"@devtools/pay-card": minor
+"@devtools/bindings": minor
+"live-mobile": patch
+---
+
+Add a "Balance" screen to the Card / Pay devtool.
+
+- Opening it requests the card-linked wallets and shows the total the balance calculation returned, unformatted, in the counter-value currency's smallest unit.
+- A refresh button refetches them.
+- Says when the total is partial, so a wallet the rates could not price does not read as a complete total.
+- Pricing needs the app's rates and currency settings, so the host passes `resolveCounterValue` in; without one the wallets are never requested.

apps/ledger-live-mobile/src/mvvm/features/DevTools/__integrations__/DevToolsScreen.integration.test.tsx

@@ -59,8 +59,9 @@ describe("DevToolsScreen", () => {
   it("mounts DevTools with the configured tools and stack screen options padded by the bottom inset", () => {
     render(withBottomInset(<DevToolsScreen />));
 
-    expect(devToolsSpy).toHaveBeenCalledTimes(1);
-    const props = devToolsSpy.mock.calls[0][0];
+    // The last render, not the first: the tool props read queries that settle after mount.
+    expect(devToolsSpy).toHaveBeenCalled();
+    const props = devToolsSpy.mock.lastCall![0];
 
     expect(props.config).toEqual([
       { id: "feature-flags", config: { marker: "ff-props" } },

apps/ledger-live-mobile/src/mvvm/features/DevTools/screens/DevToolsScreen/useDevToolsScreenViewModel.ts

@@ -9,11 +9,13 @@ import {
   useEnvDevToolProps,
 } from "@devtools/bindings";
 import type { DevToolsConfig } from "@devtools/shell";
+import { usePayCardWalletCounterValue } from "LLM/features/PayTab/hooks/usePayCardWalletCounterValue";
 import { useDevToolsRelay } from "./useDevToolsRelay";
 
 export function useDevToolsScreenViewModel() {
   const featureFlagsProps = useFeatureFlagsToolProps();
-  const payCardToolProps = usePayCardToolProps({ platform: "native" });
+  const resolveCounterValue = usePayCardWalletCounterValue();
+  const payCardToolProps = usePayCardToolProps({ platform: "native", resolveCounterValue });
   const envToolProps = useEnvDevToolProps();
   const { theme } = useTheme();
   const { bottom } = useSafeAreaInsets();

devtools/bindings/package.json

@@ -23,6 +23,7 @@
     "@devtools/env": "workspace:*",
     "@devtools/registry": "workspace:*",
     "@domain/api-card-management": "workspace:*",
+    "@features/flow-pay-card-wallets": "workspace:*",
     "@features/flow-pay-feature-tour": "workspace:*",
     "@features/platform-feature-flags": "workspace:*",
     "@shared/env": "workspace:*",
@@ -35,6 +36,7 @@
   "devDependencies": {
     "@ledgerhq/test-quarantine": "workspace:*",
     "@reduxjs/toolkit": "catalog:",
+    "@shared/api-services": "workspace:*",
     "@swc/core": "catalog:",
     "@swc/jest": "catalog:",
     "@testing-library/dom": "catalog:",
@@ -44,10 +46,10 @@
     "@types/react": "catalog:",
     "jest": "catalog:",
     "jest-environment-jsdom": "catalog:",
+    "jest-sonar": "0.2.16",
     "react": "catalog:",
     "react-dom": "catalog:",
     "react-redux": "catalog:",
-    "typescript": "catalog:",
-    "jest-sonar": "0.2.16"
+    "typescript": "catalog:"
   }
 }

devtools/bindings/src/usePayCardToolProps.test.tsx

@@ -7,15 +7,21 @@ import {
   payCardFeatureTourSlice,
   markPayCardFeatureTourSeen,
 } from "@features/flow-pay-feature-tour/state";
+import { cardApi } from "@shared/api-services";
 import { usePayCardToolProps } from "./usePayCardToolProps";
 
 function buildStore() {
   return configureStore({
     reducer: {
       featureFlags: featureFlagsReducer,
       payCardFeatureTour: payCardFeatureTourSlice.reducer,
+      // The tool reads the Card endpoints, so its api has to be part of the store under test.
+      [cardApi.reducerPath]: cardApi.reducer,
     },
-    middleware: gdm => gdm().concat(createFeatureFlagsMiddleware({ resolutionConfig: {} })),
+    middleware: gdm =>
+      gdm()
+        .concat(createFeatureFlagsMiddleware({ resolutionConfig: {} }))
+        .concat(cardApi.middleware),
   });
 }
 

devtools/bindings/src/usePayCardToolProps.ts

@@ -1,5 +1,9 @@
 import { useCallback, useMemo, useState } from "react";
 import { useLazyGetCardStatusQuery } from "@domain/api-card-management";
+import {
+  useCardLinkedWallets,
+  type ResolveWalletCounterValue,
+} from "@features/flow-pay-card-wallets";
 import { useDispatch, useSelector } from "react-redux";
 import { setOverride } from "@shared/feature-flags";
 import { useFeature } from "@features/platform-feature-flags";
@@ -16,6 +20,11 @@ type PayCardProbe = PayCardToolProps["interaction"]["probes"][number];
 export type UsePayCardToolPropsOptions = {
   /** Pass `"native"` on mobile to include the `walletPay` onboarding step. */
   readonly platform?: "web" | "native";
+  /**
+   * Prices one card-linked wallet. Pricing needs the app's rates and currency settings, so the host
+   * owns it; without one the tool reports no balance rather than a wrong zero.
+   */
+  readonly resolveCounterValue?: ResolveWalletCounterValue;
 };
 
 const LEADING_ONBOARDING_STEPS: readonly OnboardingStep[] = [
@@ -39,6 +48,9 @@ function initialSteps(platform: "web" | "native"): readonly OnboardingStep[] {
     : [...LEADING_ONBOARDING_STEPS, PURCHASE_STEP];
 }
 
+/** Never called: the wallet queries are skipped whenever the host omits its own resolver. */
+const NO_COUNTER_VALUE: ResolveWalletCounterValue = () => null;
+
 /** Reads what an endpoint answered, whatever shape the failure arrives in. */
 function describeError(error: unknown): string {
   if (error === undefined || error === null) return "";
@@ -133,14 +145,45 @@ export function usePayCardToolProps(options: UsePayCardToolPropsOptions = {}): P
 
   const interaction = useMemo(() => ({ probes: [cardStatusProbe] }), [cardStatusProbe]);
 
+  // The wallets are read when the balance screen opens, not when the tool mounts.
+  const [walletsRequested, setWalletsRequested] = useState(false);
+  const { resolveCounterValue } = options;
+
+  const linkedWallets = useCardLinkedWallets({
+    resolveCounterValue: resolveCounterValue ?? NO_COUNTER_VALUE,
+    skip: !walletsRequested || !resolveCounterValue,
+  });
+
+  const loadWallets = useCallback(() => setWalletsRequested(true), []);
+
+  const { refetch: refetchWallets } = linkedWallets;
+  const refreshWallets = useCallback(() => {
+    setWalletsRequested(true);
+    refetchWallets();
+  }, [refetchWallets]);
+
+  const balance = useMemo(
+    () => ({
+      total: linkedWallets.total,
+      isPartialTotal: linkedWallets.isPartialTotal,
+      walletCount: linkedWallets.wallets.length,
+      isFetching: linkedWallets.isFetching,
+      error: linkedWallets.isError ? "The wallet endpoints answered with an error." : undefined,
+      load: loadWallets,
+      refresh: refreshWallets,
+    }),
+    [linkedWallets, loadWallets, refreshWallets],
+  );
+
   return useMemo(
     () => ({
       flags,
       onboarding,
       interaction,
+      balance,
       hasSeenFeatureTour,
       resetPayCardFeatureTourSeen: resetFeatureTour,
     }),
-    [flags, onboarding, interaction, hasSeenFeatureTour, resetFeatureTour],
+    [flags, onboarding, interaction, balance, hasSeenFeatureTour, resetFeatureTour],
   );
 }

devtools/pay-card/src/components/Balance/Balance.native.tsx

@@ -0,0 +1,69 @@
+import { ScrollView } from "react-native";
+import { Box, Button, IconButton, Text } from "@ledgerhq/lumen-ui-rnative";
+import { Refresh } from "@ledgerhq/lumen-ui-rnative/symbols";
+import type { PayCardBalanceProps } from "../../types";
+
+export interface BalanceScreenProps extends PayCardBalanceProps {
+  readonly onBack: () => void;
+}
+
+const CONTAINER_LX = { gap: "s12", padding: "s16" } as const;
+const HEADER_LX = {
+  flexDirection: "row",
+  alignItems: "center",
+  justifyContent: "space-between",
+} as const;
+const ROW_LX = { gap: "s4" } as const;
+
+export function BalanceScreen({
+  total,
+  isPartialTotal,
+  walletCount,
+  isFetching,
+  error,
+  onBack,
+  refresh,
+}: BalanceScreenProps) {
+  return (
+    <ScrollView>
+      <Box lx={CONTAINER_LX}>
+        <Box lx={HEADER_LX}>
+          <Button appearance="gray" size="sm" onPress={onBack}>
+            Back
+          </Button>
+          <IconButton
+            icon={Refresh}
+            appearance="no-background"
+            size="sm"
+            loading={isFetching}
+            onPress={refresh}
+            accessibilityLabel="Refresh"
+          />
+        </Box>
+
+        <Box lx={ROW_LX}>
+          <Text typography="body3" lx={{ color: "muted" }}>
+            Total amount
+          </Text>
+          <Text typography="heading4SemiBold">{total}</Text>
+        </Box>
+
+        <Text typography="body3" lx={{ color: "muted" }}>
+          {`${walletCount} linked wallet(s)`}
+        </Text>
+
+        {isPartialTotal ? (
+          <Text typography="body3" lx={{ color: "warning" }}>
+            Partial: a wallet could not be priced and is not in the total.
+          </Text>
+        ) : null}
+
+        {error === undefined ? null : (
+          <Text typography="body3" lx={{ color: "error" }}>
+            {error}
+          </Text>
+        )}
+      </Box>
+    </ScrollView>
+  );
+}

devtools/pay-card/src/components/Balance/Balance.web.tsx

@@ -0,0 +1,10 @@
+import type { PayCardBalanceProps } from "../../types";
+
+export interface BalanceScreenProps extends PayCardBalanceProps {
+  readonly onBack: () => void;
+}
+
+/** Native-only for now, like the interaction screen it sits next to. */
+export function BalanceScreen(_props: BalanceScreenProps) {
+  return null;
+}

devtools/pay-card/src/pay-card/PayCard.native.test.tsx

@@ -23,6 +23,15 @@ function buildProps(): PayCardToolProps {
       setStepDone: jest.fn(),
     },
     interaction: { probes: [] },
+    balance: {
+      total: 0,
+      isPartialTotal: false,
+      walletCount: 0,
+      isFetching: false,
+      error: undefined,
+      load: jest.fn(),
+      refresh: jest.fn(),
+    },
     hasSeenFeatureTour: false,
     resetPayCardFeatureTourSeen: jest.fn(),
   };
@@ -107,6 +116,44 @@ describe("PayCard (native)", () => {
     expect(screen.getByText('{ "status": "ACTIVE" }')).toBeTruthy();
   });
 
+  it("requests the linked wallets when the balance screen opens, and shows the total", async () => {
+    const user = userEvent.setup();
+    const load = jest.fn();
+    const props = buildProps();
+    render(
+      <PayCard {...props} balance={{ ...props.balance, total: 12540, walletCount: 3, load }} />,
+    );
+
+    await user.press(screen.getByText("Balance"));
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(screen.getByText("Total amount")).toBeTruthy();
+    expect(screen.getByText("12540")).toBeTruthy();
+    expect(screen.getByText("3 linked wallet(s)")).toBeTruthy();
+  });
+
+  it("refetches the linked wallets from the balance screen", async () => {
+    const user = userEvent.setup();
+    const refresh = jest.fn();
+    const props = buildProps();
+    render(<PayCard {...props} balance={{ ...props.balance, refresh }} />);
+
+    await user.press(screen.getByText("Balance"));
+    await user.press(screen.getByLabelText("Refresh"));
+
+    expect(refresh).toHaveBeenCalledTimes(1);
+  });
+
+  it("says the total is partial rather than letting it read as complete", async () => {
+    const user = userEvent.setup();
+    const props = buildProps();
+    render(<PayCard {...props} balance={{ ...props.balance, isPartialTotal: true }} />);
+
+    await user.press(screen.getByText("Balance"));
+
+    expect(screen.getByText(/Partial/)).toBeTruthy();
+  });
+
   it("wires onboarding actions", async () => {
     const user = userEvent.setup();
     const props = buildProps();

devtools/pay-card/src/pay-card/PayCard.native.tsx

@@ -19,15 +19,27 @@ import type { PayCardToolProps } from "../types";
 import { Section } from "../components/Section/Section";
 import { ToggleRow } from "../components/ToggleRow/ToggleRow";
 import { Interaction } from "../components/Interaction/Interaction";
+import { BalanceScreen } from "../components/Balance/Balance";
 
 const BUTTON_ROW_STYLE = { flexDirection: "row", flexWrap: "wrap", gap: 8 } as const;
 
 export function PayCard(props: Readonly<PayCardToolProps>) {
-  const { flags, onboarding, interaction, hasSeenFeatureTour, resetPayCardFeatureTourSeen } = props;
-  const [showInteraction, setShowInteraction] = useState(false);
+  const {
+    flags,
+    onboarding,
+    interaction,
+    balance,
+    hasSeenFeatureTour,
+    resetPayCardFeatureTourSeen,
+  } = props;
+  const [screen, setScreen] = useState<"tool" | "interaction" | "balance">("tool");
 
-  if (showInteraction) {
-    return <Interaction {...interaction} onBack={() => setShowInteraction(false)} />;
+  if (screen === "interaction") {
+    return <Interaction {...interaction} onBack={() => setScreen("tool")} />;
+  }
+
+  if (screen === "balance") {
+    return <BalanceScreen {...balance} onBack={() => setScreen("tool")} />;
   }
 
   return (
@@ -36,7 +48,7 @@ export function PayCard(props: Readonly<PayCardToolProps>) {
         <SectionHeaderTitle>Debug</SectionHeaderTitle>
       </SectionHeader>
 
-      <ListItem onPress={() => setShowInteraction(true)}>
+      <ListItem onPress={() => setScreen("interaction")}>
         <ListItemLeading lx={{ paddingHorizontal: "s16" }}>
           <Spot appearance="icon" icon={CreditCard} />
           <ListItemContent>
@@ -48,7 +60,12 @@ export function PayCard(props: Readonly<PayCardToolProps>) {
         </ListItemTrailing>
       </ListItem>
 
-      <ListItem>
+      <ListItem
+        onPress={() => {
+          balance.load();
+          setScreen("balance");
+        }}
+      >
         <ListItemLeading lx={{ paddingHorizontal: "s16" }}>
           <Spot appearance="icon" icon={CoinsCrypto} />
           <ListItemContent>