@12-apps/payments-frontend 3.4.0 → 3.6.0

package/src/components/checkout/providers/hosted-link.tsx

@@ -15,26 +15,112 @@
  * is leaving this page and parking the payable for the return leg matters more
  * than painting a pane they will not see. `hosted-return.ts` picks it back up.
  *
- * So the whole job here is the moment BEFORE that: the buyer has chosen a
- * method and the redirect is being prepared. Previously the pane rendered
- * `null` through that moment, which reads as a checkout that has stalled — the
- * screen tells them where they are going instead. Nothing here touches the
- * money path; the navigation and the parking are unchanged.
+ * So the whole job here is the moment BEFORE that: telling the buyer where
+ * they are about to go, and giving them the one action that takes them.
+ *
+ * ## Why the ACTION lives here and not in the shell's picker
+ *
+ * The shell hides its PIX/card picker for this screen (`methodChosenAtProvider`
+ * in `./registry.ts`), so the screen owns the affordance that starts the
+ * charge. That is the point of the whole arrangement: the method question is
+ * binding on the provider's page, not on ours — every answer mints the same
+ * link — so asking it twice tells the buyer their first answer was thrown
+ * away. One button that says where it leads is the honest version of that
+ * screen, and it also removes the moment where the pane rendered `null` under
+ * a picker, which reads as a checkout that has stalled.
  */
 import { Box } from "@mui/material";
 import type { JSX } from "react";
 
+import { offeredMethods } from "../method-capability";
+import type { CheckoutProviderConfig } from "../types";
 import { useCheckoutComponents } from "../ui";
 
 import type { ProviderCheckoutScreenProps } from "./types";
 
-export function HostedLinkScreen({ method }: ProviderCheckoutScreenProps): JSX.Element | null {
-  const { Text, LoadingState } = useCheckoutComponents();
+/**
+ * How the store's own page is named to the buyer — "à página segura da
+ * InfinitePay", or the provider-neutral phrasing when no name was published.
+ *
+ * The neutral form is not a lesser fallback to be tidied away later: a host one
+ * release behind serves no `displayName`, and the buyer of that store gets a
+ * true sentence rather than our internal id ("infinitepay") dressed up as a
+ * brand.
+ */
+function destinationLabel(config: CheckoutProviderConfig | null): string {
+  const name = config?.chain?.[0]?.displayName?.trim();
+  return name ? `à página de pagamento da ${name}` : "à página de pagamento segura do provedor";
+}
 
-  // Nothing chosen yet ⇒ the shell is still showing the picker. Same as every
-  // other screen: the pane stays out of the way until there is something to say.
-  if (!method) return null;
+/**
+ * What the buyer will be asked to choose between once they get there, so the
+ * sentence promises exactly what the provider's page offers.
+ *
+ * Read from the same declaration the picker used to render, which is what
+ * keeps this honest for a provider that takes only one of the two: a hosted
+ * PIX-only store must not promise a card.
+ */
+function methodsPhrase(config: CheckoutProviderConfig | null): string | null {
+  const offered = offeredMethods(config);
+  const pix = offered === null || offered.includes("PIX");
+  const card = offered === null || offered.includes("CARD");
+  if (pix && card) return "PIX ou cartão";
+  if (pix) return "PIX";
+  if (card) return "cartão";
+  return null;
+}
+
+/** The full "where you are going and what happens there" sentence. */
+function handoffMessage(config: CheckoutProviderConfig | null): string {
+  const methods = methodsPhrase(config);
+  const choice = methods ? `, onde você escolhe pagar com ${methods}` : "";
+  return `Você será levado ${destinationLabel(config)}${choice}.`;
+}
+
+/** The invitation: what happens next, and the one button that starts it. */
+function HandOffInvite({
+  config,
+  onStart,
+}: {
+  config: CheckoutProviderConfig | null;
+  onStart: () => void;
+}): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  return (
+    <Box
+      data-testid="checkout-handoff-invite"
+      sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+    >
+      <Text variant="body" size="md" as="p">
+        {handoffMessage(config)}
+      </Text>
+      <Text variant="caption" size="sm" as="p" color="secondary">
+        Assim que o pagamento for concluído, você volta para cá e nós confirmamos o pedido.
+      </Text>
+      <Button
+        variant="solid"
+        color="primary"
+        size="lg"
+        fullWidth
+        onClick={onStart}
+        dataTestId="checkout-handoff-start"
+      >
+        Seguir para o pagamento
+      </Button>
+    </Box>
+  );
+}
 
+/**
+ * The moment after the button: the charge is being raised, then we navigate.
+ *
+ * Says the SAME sentence the invite did, from the same helper. It used to word
+ * the destination differently — "a página segura do provedor" against the
+ * invite's named one — so the screen appeared to change its mind about where
+ * the buyer was going at the exact moment they committed to going there.
+ */
+function HandOffPending({ config }: { config: CheckoutProviderConfig | null }): JSX.Element {
+  const { Text, LoadingState } = useCheckoutComponents();
   return (
     <Box
       data-testid="checkout-handoff-pending"
@@ -42,11 +128,26 @@ export function HostedLinkScreen({ method }: ProviderCheckoutScreenProps): JSX.E
     >
       <LoadingState variant="spinner" message="Preparando o pagamento" size="md" />
       <Text variant="body" size="md" as="p">
-        Você será levado à página segura do provedor para concluir o pagamento.
+        {handoffMessage(config)}
       </Text>
       <Text variant="caption" size="sm" as="p" color="secondary">
-        Assim que terminar, você volta para cá e nós confirmamos o pedido.
+        Assim que o pagamento for concluído, você volta para cá e nós confirmamos o pedido.
       </Text>
     </Box>
   );
 }
+
+export function HostedLinkScreen({
+  method,
+  config,
+  onStart,
+}: ProviderCheckoutScreenProps): JSX.Element | null {
+  // A method is only ever set here once the buyer has committed — either by
+  // pressing the CTA below, or (on a host whose shell still renders a picker)
+  // by choosing a tile. Both mean the same thing: the hand-off is underway.
+  if (method) return <HandOffPending config={config} />;
+  // No method and no CTA to offer ⇒ the shell is still showing its picker, and
+  // the pane stays out of the way exactly as every other screen does.
+  if (!onStart) return null;
+  return <HandOffInvite config={config} onStart={onStart} />;
+}

package/src/components/checkout/providers/registry.ts

@@ -26,8 +26,10 @@
  * to an empty pane.
  */
 import { CapabilityDefaultScreen } from "./capability-default";
+import { handsBuyerOver } from "./hands-over";
 import { HostedLinkScreen } from "./hosted-link";
 import { PixAndCardScreen } from "./pix-and-card";
+import type { CheckoutProviderConfig } from "../types";
 import type { ProviderCheckoutScreen } from "./types";
 
 /**
@@ -76,3 +78,31 @@ export function resolveCheckoutScreen(
 ): ProviderCheckoutScreen {
   return screenFor(chainHeadScreen) ?? CapabilityDefaultScreen;
 }
+
+/**
+ * Does the buyer choose PIX-or-card on the PROVIDER's page rather than on ours?
+ *
+ * The shell asks this before rendering its method picker, and hides the picker
+ * when the answer is yes (FUT-596 follow-up). A hand-off store asks the
+ * question twice otherwise: once here, where the answer changes nothing —
+ * every method mints the same checkout link — and again on the provider's own
+ * page, where it is finally binding. The first ask is not merely redundant, it
+ * is misleading: the buyer who picked PIX here has picked nothing, and finding
+ * the same two options waiting for them on another site reads as a checkout
+ * that lost their answer.
+ *
+ * Resolved in the SAME order as {@link resolveCheckoutScreen} — a declared id
+ * wins, and an undeclared or unknown one falls back to the capability read —
+ * so the picker and the pane can never disagree about which flow this is. That
+ * is why the test is an identity check against the hand-off screen rather than
+ * a second table of ids: a table would be the copy that drifts, and it would
+ * drift the moment a new hand-off adapter declared its own id.
+ */
+export function methodChosenAtProvider(
+  chainHeadScreen: string | null | undefined,
+  config: CheckoutProviderConfig | null,
+): boolean {
+  const declared = screenFor(chainHeadScreen);
+  if (declared) return declared === HostedLinkScreen;
+  return handsBuyerOver(config);
+}

package/src/components/checkout/providers/types.ts

@@ -46,8 +46,26 @@ export interface ProviderCheckoutScreenProps {
    * those readings call the helpers themselves.
    */
   config: CheckoutProviderConfig | null;
-  /** What the shell's picker currently has selected; `null` before a choice. */
+  /**
+   * What the shell currently has selected; `null` before a choice.
+   *
+   * `null` is also the resting state of a screen that OWNS the choice (see
+   * {@link ProviderCheckoutScreenProps.onStart}): nothing is selected until
+   * the buyer presses that screen's own CTA.
+   */
   method: PaymentMethod | null;
+  /**
+   * Present ⇒ this screen owns the "how do I start paying" affordance, because
+   * the shell has hidden its method picker for it (FUT-596 follow-up). Calling
+   * it commits the buyer to the store's hand-off method and raises the charge,
+   * exactly as choosing a tile in the picker does.
+   *
+   * Absent for every screen where the picker is still on the page — those
+   * screens must not grow a second way to start the same charge.
+   */
+  onStart?: () => void;
+  /** A charge is being raised right now — the shell's own busy flag. */
+  creating?: boolean;
   /** Scopes the saved-card list to the store being paid. */
   tenantSlug?: string;
   /** The shell's polling cadence, passed through so tests can shorten it. */

package/src/components/checkout/types.ts

@@ -250,6 +250,17 @@ export interface CheckoutCustomerField {
  */
 export interface CheckoutChainLink {
   provider: string;
+  /**
+   * The provider's own name as a BUYER should read it ("InfinitePay"), which
+   * `GET /api/checkout/config` publishes per entry.
+   *
+   * Optional, and the DEGRADE DIRECTION IS "SAY NOTHING": an older host serves
+   * no name, and a hand-off screen then describes where the buyer is going
+   * without naming it, rather than printing the internal `provider` id — a
+   * buyer shown "infinitepay" learns less than one shown nothing, and learns
+   * it in a vocabulary that is ours rather than theirs.
+   */
+  displayName?: string | null;
   tokenization: "NONE" | "PUBLIC_KEY" | "SDK" | "REDIRECT";
   publicKey: string | null;
   mockTokenization: boolean;

package/src/index.ts

@@ -252,6 +252,39 @@ export {
  */
 export type { PaymentEnvironment } from '@12-apps/payments-backend';
 
+// ---------------------------------------------------------------------------
+// The REDIRECT ACTIVATION protocol (FUT-463, packaged by FUT-763) — proving a
+// connection can charge, for a provider whose payer pays on its own page.
+//
+// `renderVerification` above stays what it was: the package decides where the
+// step appears and the host owns the screen. What moved is the protocol behind
+// it — resume-on-mount, the return trip's ids, the refusal/expiry/transport
+// distinctions, the bounded wait. Every one of those was learned from a payment
+// that went wrong, and no second host should have to learn them again.
+// ---------------------------------------------------------------------------
+export {
+  useRedirectActivation,
+  type RedirectActivation,
+  type RedirectActivationOptions,
+} from './activation/use-redirect-activation';
+export { type RedirectActivationCopy } from './activation/copy';
+export {
+  creationFailure,
+  postActivation,
+  refusedByProvider,
+  settleActivationPoll,
+  type ActivationClock,
+  type ActivationPendingBody,
+  type ActivationPollBody,
+  type RedirectActivationState,
+  type SettlePollIo,
+} from './activation/redirect-state';
+export {
+  clearReturnedSettlement,
+  takeReturnedSettlement,
+  RETURNED_SETTLEMENT_KEY,
+} from './activation/returned-settlement';
+
 // ---------------------------------------------------------------------------
 // The connect ROUND TRIP's other end (FUT-763): what the OAuth callback
 // redirected back with, taken out of the address bar once. The codes are a