@12-apps/payments-frontend 3.9.0 → 3.10.0

package/src/flows/copy.ts

@@ -89,4 +89,16 @@ export interface CheckoutCopyFE {
   manageCardsTitle: string;
   manageCardsEmpty: string;
   manageCardsAdd: string;
+  /**
+   * How a card on file READS — the network's name when the provider shared
+   * none, and the expiry line beside it.
+   *
+   * Both were Portuguese literals inside this screen ("Cartão", "Validade
+   * MM/AAAA"), which is the whole of what a buyer sees of a saved card when
+   * the provider is stingy with metadata. `cardExpiry` is a function because
+   * the order of month and year, and whether the word leads or trails, is the
+   * translator's call — the two numbers arrive already padded.
+   */
+  cardUnknownBrand: string;
+  cardExpiry(month: string, year: number): string;
 }

package/src/flows/create-payment-flows.tsx

@@ -40,7 +40,14 @@ const ALWAYS_PAYABLE: CheckoutAvailability = { payable: true };
 
 /** Build the runtime every screen closes over. */
 function buildRuntime(config: PaymentFlowsConfig): FlowsRuntime {
-  const client = createCheckoutClient(config.transport);
+  // The transport's own failure sentences come from the SAME copy pack the
+  // screens read (FUT-760), so a host answers the question once. A `transport`
+  // that names its own `copy` still wins — a second mount may talk to a
+  // different surface with a different voice.
+  const client = createCheckoutClient({
+    copy: config.copy.views.screens.screens.transport,
+    ...config.transport,
+  });
   const navigate =
     config.ports.navigate ??
     ((url: string) => {

package/src/flows/runtime.tsx

@@ -27,6 +27,7 @@ import { CheckoutClientProvider } from "../components/checkout/client-context";
 import { CheckoutNavigateProvider } from "../components/checkout/navigate-context";
 import type { CheckoutClient } from "../components/checkout/transport";
 import type { CheckoutProviderConfig } from "../components/checkout/types";
+import { CheckoutCopyProvider } from "../components/checkout/copy-context";
 import { CheckoutComponentsProvider } from "../components/checkout/ui";
 
 import type { CheckoutCopyFE } from "./copy";
@@ -102,7 +103,7 @@ export function useResolvedConfig(runtime: FlowsRuntime): CheckoutConfigState {
   return provided ?? own;
 }
 
-/** Slots, transport and the navigate port — what a screen cannot work without. */
+/** Slots, WORDS, transport and the navigate port — what a screen cannot work without. */
 export function FlowsShell({
   runtime,
   children,
@@ -112,9 +113,16 @@ export function FlowsShell({
 }): JSX.Element {
   return (
     <CheckoutComponentsProvider components={runtime.config.components}>
-      <CheckoutClientProvider client={runtime.client}>
-        <CheckoutNavigateProvider navigate={runtime.navigate}>{children}</CheckoutNavigateProvider>
-      </CheckoutClientProvider>
+      {/* The factory's STANDALONE screens (add-card, manage-cards) render the
+          same card fields the checkout does, so they need the same words —
+          and they are mounted here rather than under `CheckoutFlow`. */}
+      <CheckoutCopyProvider copy={runtime.config.copy.views.screens}>
+        <CheckoutClientProvider client={runtime.client}>
+          <CheckoutNavigateProvider navigate={runtime.navigate}>
+            {children}
+          </CheckoutNavigateProvider>
+        </CheckoutClientProvider>
+      </CheckoutCopyProvider>
     </CheckoutComponentsProvider>
   );
 }

package/src/flows/screens-vault.tsx

@@ -29,15 +29,15 @@ import type { CheckoutScreens } from "./types";
 import { useAddCard, type AddCardController } from "./use-add-card";
 
 /** `visa •••• 4242`, or just the brand when the provider shared no last4. */
-function displayLabel(display: VaultedCardDisplay): string {
-  const brand = display.brand ?? "Cartão";
+function displayLabel(copy: CheckoutCopyFE, display: VaultedCardDisplay): string {
+  const brand = display.brand ?? copy.cardUnknownBrand;
   return display.last4 ? `${brand} •••• ${display.last4}` : brand;
 }
 
 /** `Validade 12/2031`, or nothing when the provider shared no expiry. */
-function expiryLabel(display: VaultedCardDisplay): string | null {
+function expiryLabel(copy: CheckoutCopyFE, display: VaultedCardDisplay): string | null {
   if (display.expMonth === null || display.expYear === null) return null;
-  return `Validade ${String(display.expMonth).padStart(2, "0")}/${display.expYear}`;
+  return copy.cardExpiry(String(display.expMonth).padStart(2, "0"), display.expYear);
 }
 
 /** The card is on file — display metadata only, never the vault token. */
@@ -49,7 +49,7 @@ function SavedConfirmation({
   copy: CheckoutCopyFE;
 }): JSX.Element {
   const { Alert, Text } = useCheckoutComponents();
-  const expiry = expiryLabel(display);
+  const expiry = expiryLabel(copy, display);
   return (
     <Box data-testid="add-card-saved" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       <Alert
@@ -60,7 +60,7 @@ function SavedConfirmation({
       />
       <Box>
         <Text variant="body" size="sm" weight="semibold" as="p">
-          {displayLabel(display)}
+          {displayLabel(copy, display)}
         </Text>
         {expiry ? (
           <Text variant="caption" size="xs" color="secondary" as="p">
@@ -195,12 +195,12 @@ function useInstrumentList(
 }
 
 /** The list itself, or the empty-state sentence. Read-only by design. */
-function CardList({ cards, emptyCopy }: { cards: SavedCard[]; emptyCopy: string }): JSX.Element {
+function CardList({ cards, copy }: { cards: SavedCard[]; copy: CheckoutCopyFE }): JSX.Element {
   const { Text } = useCheckoutComponents();
   if (cards.length === 0) {
     return (
       <Text variant="body" size="sm" color="secondary" as="p" data-testid="manage-cards-empty">
-        {emptyCopy}
+        {copy.manageCardsEmpty}
       </Text>
     );
   }
@@ -213,7 +213,7 @@ function CardList({ cards, emptyCopy }: { cards: SavedCard[]; emptyCopy: string
           </Text>
           {card.expMonth && card.expYear ? (
             <Text variant="caption" size="xs" color="secondary" as="p">
-              {`Validade ${String(card.expMonth).padStart(2, "0")}/${card.expYear}`}
+              {copy.cardExpiry(String(card.expMonth).padStart(2, "0"), card.expYear)}
             </Text>
           ) : null}
         </Box>
@@ -235,7 +235,7 @@ function ManageCardsBody({ runtime }: { runtime: FlowsRuntime }): JSX.Element {
       <Text variant="heading" size="md" weight="bold" as="h2">
         {copy.manageCardsTitle}
       </Text>
-      {pending ? null : <CardList cards={cards} emptyCopy={copy.manageCardsEmpty} />}
+      {pending ? null : <CardList cards={cards} copy={copy} />}
       {adding ? (
         <AddCardSection runtime={runtime} onSaved={() => setRefresh((count) => count + 1)} />
       ) : (

package/src/flows/types.ts

@@ -37,7 +37,10 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "../components/checkout/types";
-import type { CheckoutTransport, VaultedCardDisplay } from "../components/checkout/transport";
+import type {
+  CheckoutTransportBinding,
+  VaultedCardDisplay,
+} from "../components/checkout/transport";
 import type { useCheckoutController } from "../components/checkout/use-checkout-controller";
 import type { Result } from "../result";
 
@@ -88,7 +91,7 @@ export interface CheckoutPorts {
 /** What `createPaymentFlows` is configured with. */
 export interface PaymentFlowsConfig {
   /** Where the `createPaymentFlowsBE` mount lives. Default `/api/checkout`. */
-  transport?: CheckoutTransport;
+  transport?: CheckoutTransportBinding;
 
   /**
    * The store being paid. A HOOK because the host's router owns it: taking a

package/src/flows/use-add-card.ts

@@ -143,11 +143,12 @@ export function useAddCard(
 
   const brand = detectBrand(onlyDigits(card.number));
 
+  const fieldCopy = runtime.copy.views.screens.card.fields;
   const validate = (): CardFieldErrors => ({
-    number: validateCardNumber(card.number),
-    holder: validateHolder(card.holder),
-    expiry: validateExpiry(card.expiry),
-    cvv: validateCvv(card.cvv, brand),
+    number: validateCardNumber(card.number, fieldCopy),
+    holder: validateHolder(card.holder, fieldCopy),
+    expiry: validateExpiry(card.expiry, fieldCopy),
+    cvv: validateCvv(card.cvv, fieldCopy, brand),
   });
 
   const submit = async (): Promise<void> => {
@@ -158,7 +159,11 @@ export function useAddCard(
     if (Object.values(errors).some(Boolean)) return;
 
     setSaving(true);
-    const minted = await tokenizeForCheckout(card, sessionTokenization(phase.session, config));
+    const minted = await tokenizeForCheckout(
+      card,
+      sessionTokenization(phase.session, config),
+      runtime.copy.views.screens.card,
+    );
     if (!minted.ok) {
       setError(minted.error);
       setSaving(false);

package/src/index.ts

@@ -37,6 +37,17 @@ export {
   type CheckoutPaymentProps,
   type SavedCardOption,
 } from './components/CheckoutPayment';
+// The words that step renders — required on the prop above, so a host wiring
+// the legacy surface has to answer them (FUT-760).
+export type {
+  CheckoutPaymentCopy,
+  LegacyCardCopy,
+  LegacyMethodCopy,
+  LegacyMoneyCopy,
+  LegacyPixCopy,
+  LegacyRefusalCopy,
+} from './components/checkout-payment-copy';
+export { PT_BR_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-pt-BR';
 
 // ---------------------------------------------------------------------------
 // The buyer checkout surface (FUT-564) — the storefront's three-step flow,
@@ -80,6 +91,7 @@ export {
   type BuyerVaultSession,
   type CheckoutClient,
   type CheckoutTransport,
+  type CheckoutTransportBinding,
   type CompleteVaultInput,
   type VaultedCardDisplay,
 } from './components/checkout/transport';
@@ -98,9 +110,37 @@ export type {
   StatusOutcomeCopy,
 } from './components/checkout/view-copy';
 export {
+  PT_BR_CHECKOUT_COPY,
   PT_BR_CHECKOUT_VIEW_COPY,
   PT_BR_PAYMENT_STATUS_COPY,
 } from './components/checkout/pt-BR';
+// The provider the card fields and buyer inputs read their words from — a host
+// mounting a screen BELOW `CheckoutFlow` (or composing by hand) opens it
+// itself; `CheckoutFlow` and `FlowsShell` already do (FUT-760).
+export {
+  CheckoutCopyProvider,
+  useCheckoutCopy,
+  type BuyerInfoCopy,
+  type CheckoutCopy,
+} from './components/checkout/copy-context';
+// The screens BELOW the steps — the method tiles, the PIX and card panes, the
+// wallet buttons, the hosted handover and the transport's own three sentences.
+// Every slice is named on the barrel, not just the whole: a host writing its
+// pack section by section types the section it is writing (FUT-760).
+export type {
+  CardPaneCopy,
+  CheckoutScreensCopy,
+  CheckoutTransportCopy,
+  CheckoutValidationCopy,
+  HostedHandoverCopy,
+  MethodPickerCopy,
+  PayerSummaryCopy,
+  PaymentErrorCopy,
+  PixPaneCopy,
+  SettlingCopy,
+  WalletCopy,
+} from './components/checkout/screens-copy';
+export { PT_BR_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-pt-BR';
 export { fetchCheckoutConfig } from './components/checkout/client';
 /**
  * The `sessionStorage` key the hosted-checkout return leg parks the raised
@@ -199,7 +239,11 @@ export {
   validateExpiry,
   validateHolder,
   NEW_CARD,
+  PT_BR_CARD_COPY,
   type CardBrand,
+  type CardCopy,
+  type CardFieldCopy,
+  type CardTokenizeCopy,
   type CardDetails,
   type CardFieldErrors,
   type CardToken,
@@ -207,6 +251,25 @@ export {
   type CardTokenizer,
   type SavedCard,
 } from './card';
+// The settings surface's words. `PaymentProviderSettings` takes the pack as a
+// required prop and mounts the provider; the provider is exported for a host
+// that composes the pieces itself (FUT-760).
+export {
+  PaymentsSettingsCopyProvider,
+  usePaymentsSettingsCopy,
+} from './components/settings-copy-context';
+export { PT_BR_PAYMENTS_SETTINGS_COPY } from './components/settings-pt-BR';
+export type {
+  ConnectionBadgeCopy,
+  ConnectionCardCopy,
+  ConnectionStatusCopy,
+  CredentialFormCopy,
+  EnvironmentCopy,
+  OAuthConnectionCopy,
+  PaymentsSettingsCopy,
+  ProviderPriorityCopy,
+  SetupGuideCopy,
+} from './components/settings-copy';
 export {
   ProviderConnection,
   type ProviderConnectionProps,