@12-apps/payments-frontend 3.8.0 → 3.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "type": "module",
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.16.0",
+    "@12-apps/payments-backend": "^4.18.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/activation/charge-copy.ts

@@ -1,3 +1,5 @@
+import type { CardCopy } from '../card/copy';
+
 /**
  * The three sentences the card activation charge has to put on screen itself
  * (FUT-763).
@@ -8,6 +10,14 @@
  * product's voice reaches every adopter. No defaults, and the field is required.
  */
 export interface ActivationChargeCopy {
+  /**
+   * The card form's own words — its labels, its field-level refusals, and
+   * everything a tokenizer can fail with.
+   *
+   * The activation charge IS a card form, so it carries the same port the
+   * buyer checkout does rather than a second one shaped almost like it.
+   */
+  card: CardCopy;
   /**
    * No tokenizer is registered for this provider, so nothing can be encrypted
    * and there is no charge to make.

package/src/activation/use-activation-charge.ts

@@ -18,6 +18,7 @@ import {
 } from '../card';
 
 import type { ActivationChargeCopy } from './charge-copy';
+import type { CardCopy } from '../card/copy';
 
 /**
  * The activation charge for a provider whose payer pays HERE (FUT-463, moved
@@ -166,16 +167,17 @@ function useActivationProbe(verifyChargeUrl: string): ActivationProbe {
 }
 
 /** Local validation — nothing reaches the provider until the card is well-formed. */
-function validateAll(card: CardDetails, cpf: string) {
+function validateAll(card: CardDetails, cpf: string, copy: CardCopy) {
   const brand = detectBrand(onlyDigits(card.number));
+  const fields = copy.fields;
   return {
     fieldErrors: {
-      number: validateCardNumber(card.number),
-      holder: validateHolder(card.holder),
-      expiry: validateExpiry(card.expiry),
-      cvv: validateCvv(card.cvv, brand),
+      number: validateCardNumber(card.number, fields),
+      holder: validateHolder(card.holder, fields),
+      expiry: validateExpiry(card.expiry, fields),
+      cvv: validateCvv(card.cvv, fields, brand),
     } satisfies CardFieldErrors,
-    cpfError: validateCpf(cpf),
+    cpfError: validateCpf(cpf, fields),
   };
 }
 
@@ -205,7 +207,7 @@ async function runCharge(request: ChargeRequest): Promise<ActivationChargeState>
     };
   }
 
-  const tokenized = await tokenizeCard(request.card, request.publicKey, tokenizer);
+  const tokenized = await tokenizeCard(request.card, request.publicKey, request.copy.card, tokenizer);
   if (!tokenized.ok) return { kind: 'failed', reason: tokenized.error };
 
   try {
@@ -259,7 +261,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
   const { card, cpf, setFieldErrors, setCpfError, clear } = form;
 
   const submit = useCallback(async () => {
-    const validation = validateAll(card, cpf);
+    const validation = validateAll(card, cpf, options.copy.card);
     setFieldErrors(validation.fieldErrors);
     setCpfError(validation.cpfError);
     if (Object.values(validation.fieldErrors).some(Boolean) || validation.cpfError) return;

package/src/card/copy.ts

@@ -0,0 +1,115 @@
+/**
+ * Every sentence the card form and its tokenizers put in front of a BUYER
+ * (FUT-760).
+ *
+ * Required, with no defaults, which is this package's own doctrine
+ * (`components/checkout/view-copy.ts` states it): a default in the origin
+ * host's language reads as finished to the next host right up until a shopper
+ * sees it.
+ *
+ * The split is the one the whole port draws. WHICH refusal this is — a number
+ * that fails Luhn, an expiry already past, a CVV of the wrong length for the
+ * detected network, an SDK that never loaded, a provider that refused the
+ * card outright — is knowledge of card processing, and it stays here. The
+ * words are the host's.
+ */
+
+/**
+ * The card networks this form can recognise from a number's prefix.
+ *
+ * `Unknown` used to be spelled `"Cartão"` — a Portuguese word inside an
+ * exported TYPE UNION, so it reached every adopter's types and, through
+ * `CardBrand`, their API surface. A string leak is cosmetic; a union member is
+ * structural, and it propagates. The brand's LABEL is
+ * {@link CardFieldCopy.unknownBrand} now, and the union names the fact.
+ */
+export type CardBrand = 'Visa' | 'Mastercard' | 'Amex' | 'Elo' | 'Unknown';
+
+/** The card form's labels and its field-level refusals. */
+export interface CardFieldCopy {
+  /** The adornment shown when the number matches no network we know. */
+  unknownBrand: string;
+  numberLabel: string;
+  numberRequired: string;
+  numberIncomplete: string;
+  numberInvalid: string;
+  holderLabel: string;
+  holderRequired: string;
+  /**
+   * The expiry field's label, whose parenthetical spells the ORDER — "MM/AA"
+   * in Portuguese, "MM/YY" in English. Unaccented, so no diacritic scan ever
+   * flagged it, and getting it wrong makes a buyer type the year first.
+   */
+  expiryLabel: string;
+  cvvLabel: string;
+  /** A month outside 1–12 — a typo, not an expiry. */
+  monthInvalid: string;
+  /** A well-formed date that has already passed. */
+  expired: string;
+  /**
+   * Either of the two, from a tokenizer that cannot tell them apart: it reads
+   * the expiry as one string and only learns it is unusable.
+   */
+  expiryInvalid: string;
+  cvvInvalid: string;
+  /**
+   * The CVV is the wrong length for the detected network — Amex wants four,
+   * everyone else three.
+   *
+   * A function, because where the number sits in the sentence is the
+   * translator's call, and some languages agree the noun with it.
+   */
+  cvvDigits(length: number): string;
+  cpfRequired: string;
+  cpfInvalid: string;
+  /** The saved-cards radio group's own label. */
+  savedCardsLabel: string;
+  /** The trailing option that opens the new-card form. */
+  newCard: string;
+  newCardDescription: string;
+  /** The "keep this card" checkbox. */
+  saveCard: string;
+}
+
+/** What can go wrong between "Pagar" and a token, in the buyer's words. */
+export interface CardTokenizeCopy {
+  /** The provider's browser SDK never loaded. */
+  sdkUnavailable: string;
+  /** The SDK loaded and refused the card data it was handed. */
+  cardNotProcessed: string;
+  /** We could not reach the tokenizing provider at all. */
+  providerUnreachable: string;
+  /**
+   * The tokenizer was reached and simply did not answer in time.
+   *
+   * Separate from unreachable because the buyer's next move differs: an
+   * outage is worth retrying now, a timeout usually means trying the other
+   * method. Unaccented in pt-BR, so only a reading found it.
+   */
+  providerTimedOut: string;
+  /**
+   * The provider answered, refusing the card's details.
+   *
+   * Takes the status AND the provider's own truncated answer, because both
+   * are what a human reads back to support — this failure surfaces on the
+   * activation screen, and carrying the raw response there is deliberate.
+   * Where either sits in the sentence is the translator's call.
+   */
+  providerRefused(status: number, response: string): string;
+  /**
+   * This store has no card-encryption key, so the browser cannot encrypt
+   * anything. A configuration fault, phrased for the person who hit it.
+   */
+  noPublicKey: string;
+  /**
+   * Card is off for this store entirely — the sentence that has to offer the
+   * buyer somewhere else to go, because there is nothing they can retry.
+   */
+  cardUnavailable: string;
+}
+
+/** Both halves, for a host wiring the card form in one place. */
+export interface CardCopy {
+  fields: CardFieldCopy;
+  tokenize: CardTokenizeCopy;
+}

package/src/card/cpf.ts

@@ -1,3 +1,4 @@
+import type { CardFieldCopy } from "./copy";
 import { onlyDigits } from "./format";
 
 /**
@@ -19,8 +20,14 @@ export function formatCpf(value: string): string {
   return out;
 }
 
-/** Verify the two CPF check digits (rejects all-same-digit sequences too). */
-function isValidCpf(value: string): boolean {
+/**
+ * Verify the two CPF check digits (rejects all-same-digit sequences too).
+ *
+ * Exported as the PREDICATE beside {@link validateCpf}'s sentence, because a
+ * caller that only needs the verdict should not have to hold the words to get
+ * it — `buyer-fields.ts` gates a field on this and threw the message away.
+ */
+export function isValidCpf(value: string): boolean {
   const d = onlyDigits(value);
   if (d.length !== 11) return false;
   if (/^(\d)\1{10}$/.test(d)) return false;
@@ -36,7 +43,7 @@ function isValidCpf(value: string): boolean {
 }
 
 /** Field validator: returns an error message, or `undefined` when valid. */
-export function validateCpf(value: string): string | undefined {
-  if (!onlyDigits(value)) return "CPF obrigatório.";
-  return isValidCpf(value) ? undefined : "CPF inválido.";
+export function validateCpf(value: string, copy: CardFieldCopy): string | undefined {
+  if (!onlyDigits(value)) return copy.cpfRequired;
+  return isValidCpf(value) ? undefined : copy.cpfInvalid;
 }

package/src/card/fields.tsx

@@ -1,6 +1,7 @@
 import { Box } from "@mui/material";
 import type { JSX } from "react";
 
+import { useCheckoutCopy } from "../components/checkout/copy-context";
 import { useCheckoutComponents } from "../components/checkout/ui";
 
 import {
@@ -30,9 +31,10 @@ export function SavedCardsPicker({
   onSelect: (id: string) => void;
 }): JSX.Element {
   const { RadioGroup } = useCheckoutComponents();
+  const copy = useCheckoutCopy().card.fields;
   return (
     <RadioGroup
-      label="Cartão"
+      label={copy.savedCardsLabel}
       value={selection}
       onChange={(_event, next) => onSelect(next)}
       options={[
@@ -41,7 +43,7 @@ export function SavedCardsPicker({
           label: `${saved.brand} •••• ${saved.last4}`,
           description: `Validade ${String(saved.expMonth).padStart(2, "0")}/${saved.expYear}`,
         })),
-        { value: NEW_CARD, label: "Novo cartão", description: "Inserir outro cartão" },
+        { value: NEW_CARD, label: copy.newCard, description: copy.newCardDescription },
       ]}
       dataTestId="saved-cards"
     />
@@ -63,9 +65,10 @@ function CardNumberInput({
   setFieldErrors: SetErrors;
 }): JSX.Element {
   const { Input, Text } = useCheckoutComponents();
+  const copy = useCheckoutCopy().card.fields;
   return (
     <Input
-      label="Número do cartão"
+      label={copy.numberLabel}
       type="text"
       inputMode="numeric"
       variant="outlined"
@@ -77,14 +80,14 @@ function CardNumberInput({
       error={Boolean(fieldErrors.number)}
       helperText={fieldErrors.number}
       endAdornment={
-        brand !== "Cartão" ? (
+        brand !== "Unknown" ? (
           <Text variant="caption" size="xs" color="secondary" as="span">
             {brand}
           </Text>
         ) : undefined
       }
       onChange={(event) => setCard((prev) => ({ ...prev, number: formatCardNumber(event.target.value) }))}
-      onBlur={() => setFieldErrors((prev) => ({ ...prev, number: validateCardNumber(card.number) }))}
+      onBlur={() => setFieldErrors((prev) => ({ ...prev, number: validateCardNumber(card.number, copy) }))}
       data-testid="card-number"
     />
   );
@@ -105,10 +108,11 @@ function ExpiryCvvFields({
   setFieldErrors: SetErrors;
 }): JSX.Element {
   const { Input } = useCheckoutComponents();
+  const copy = useCheckoutCopy().card.fields;
   return (
     <Box sx={{ display: "flex", gap: 2 }}>
       <Input
-        label="Validade (MM/AA)"
+        label={copy.expiryLabel}
         type="text"
         inputMode="numeric"
         placeholder="MM/AA"
@@ -120,11 +124,11 @@ function ExpiryCvvFields({
         error={Boolean(fieldErrors.expiry)}
         helperText={fieldErrors.expiry}
         onChange={(event) => setCard((prev) => ({ ...prev, expiry: formatExpiry(event.target.value) }))}
-        onBlur={() => setFieldErrors((prev) => ({ ...prev, expiry: validateExpiry(card.expiry) }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, expiry: validateExpiry(card.expiry, copy) }))}
         data-testid="card-expiry"
       />
       <Input
-        label="CVV"
+        label={copy.cvvLabel}
         type="text"
         inputMode="numeric"
         variant="outlined"
@@ -136,7 +140,7 @@ function ExpiryCvvFields({
         error={Boolean(fieldErrors.cvv)}
         helperText={fieldErrors.cvv}
         onChange={(event) => setCard((prev) => ({ ...prev, cvv: formatCvv(event.target.value) }))}
-        onBlur={() => setFieldErrors((prev) => ({ ...prev, cvv: validateCvv(card.cvv, brand) }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, cvv: validateCvv(card.cvv, copy, brand) }))}
         data-testid="card-cvv"
       />
     </Box>
@@ -169,6 +173,7 @@ export function NewCardForm({
   onSaveCardChange?: (checked: boolean) => void;
 }): JSX.Element {
   const { Input, Checkbox } = useCheckoutComponents();
+  const copy = useCheckoutCopy().card.fields;
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
       <CardNumberInput
@@ -179,7 +184,7 @@ export function NewCardForm({
         setFieldErrors={setFieldErrors}
       />
       <Input
-        label="Nome impresso no cartão"
+        label={copy.holderLabel}
         type="text"
         variant="outlined"
         size="md"
@@ -189,7 +194,7 @@ export function NewCardForm({
         error={Boolean(fieldErrors.holder)}
         helperText={fieldErrors.holder}
         onChange={(event) => setCard((prev) => ({ ...prev, holder: event.target.value }))}
-        onBlur={() => setFieldErrors((prev) => ({ ...prev, holder: validateHolder(card.holder) }))}
+        onBlur={() => setFieldErrors((prev) => ({ ...prev, holder: validateHolder(card.holder, copy) }))}
         data-testid="card-holder"
       />
       <ExpiryCvvFields
@@ -201,7 +206,7 @@ export function NewCardForm({
       />
       {onSaveCardChange ? (
         <Checkbox
-          label="Salvar cartão para próximas compras"
+          label={copy.saveCard}
           checked={saveCard}
           onChange={(_event, checked) => onSaveCardChange(checked)}
           data-testid="save-card"

package/src/card/format.ts

@@ -1,12 +1,17 @@
+import type { CardBrand, CardFieldCopy } from "./copy";
+
 /**
  * Client-side card formatting + validation (FUT-58).
  *
- * Pure helpers with no imports — the card form uses them to format input live and
- * to validate before tokenizing. They never transmit anything; the PAN is only
- * checked locally (Luhn + brand + length) then handed to the tokenizer.
+ * Pure helpers — the card form uses them to format input live and to validate
+ * before tokenizing. They never transmit anything; the PAN is only checked
+ * locally (Luhn + brand + length) then handed to the tokenizer.
+ *
+ * The validators take the host's words (FUT-760). WHICH refusal a value earns
+ * is the rule, and it stays here; the sentence is not ours.
  */
 
-export type CardBrand = "Visa" | "Mastercard" | "Amex" | "Elo" | "Cartão";
+export type { CardBrand } from "./copy";
 
 /** Strip everything but digits. */
 export function onlyDigits(value: string): string {
@@ -19,7 +24,7 @@ export function detectBrand(digits: string): CardBrand {
   if (/^(5[1-5]|2[2-7])/.test(digits)) return "Mastercard";
   if (/^3[47]/.test(digits)) return "Amex";
   if (/^6/.test(digits)) return "Elo";
-  return "Cartão";
+  return "Unknown";
 }
 
 /** Expected CVV length for a brand (Amex uses 4, everyone else 3). */
@@ -71,33 +76,44 @@ function luhnValid(digits: string): boolean {
 }
 
 /** @returns an error message, or `undefined` when valid. */
-export function validateCardNumber(value: string): string | undefined {
+export function validateCardNumber(
+  value: string,
+  copy: CardFieldCopy,
+): string | undefined {
   const digits = onlyDigits(value);
-  if (!digits) return "Informe o número do cartão.";
-  if (digits.length < 13) return "Número de cartão incompleto.";
-  if (!luhnValid(digits)) return "Número de cartão inválido.";
+  if (!digits) return copy.numberRequired;
+  if (digits.length < 13) return copy.numberIncomplete;
+  if (!luhnValid(digits)) return copy.numberInvalid;
   return undefined;
 }
 
-export function validateHolder(value: string): string | undefined {
-  return value.trim().length < 2 ? "Informe o nome impresso no cartão." : undefined;
+export function validateHolder(value: string, copy: CardFieldCopy): string | undefined {
+  return value.trim().length < 2 ? copy.holderRequired : undefined;
 }
 
-export function validateExpiry(value: string, now: Date = new Date()): string | undefined {
+export function validateExpiry(
+  value: string,
+  copy: CardFieldCopy,
+  now: Date = new Date(),
+): string | undefined {
   const match = /^(\d{2})\/(\d{2})$/.exec(value.trim());
   if (!match) return "Validade incompleta (MM/AA).";
   const mm = match[1];
   const yy = match[2];
   if (mm === undefined || yy === undefined) return "Validade incompleta (MM/AA).";
   const month = Number(mm);
-  if (month < 1 || month > 12) return "Mês inválido.";
+  if (month < 1 || month > 12) return copy.monthInvalid;
   const endOfMonth = new Date(2000 + Number(yy), month, 0, 23, 59, 59, 999);
-  return endOfMonth.getTime() < now.getTime() ? "Cartão expirado." : undefined;
+  return endOfMonth.getTime() < now.getTime() ? copy.expired : undefined;
 }
 
-export function validateCvv(value: string, brand: CardBrand = "Cartão"): string | undefined {
+export function validateCvv(
+  value: string,
+  copy: CardFieldCopy,
+  brand: CardBrand = "Unknown",
+): string | undefined {
   const digits = onlyDigits(value);
   if (!digits) return "Informe o CVV.";
   const len = cvvLength(brand);
-  return digits.length === len ? undefined : `CVV deve ter ${len} dígitos.`;
+  return digits.length === len ? undefined : copy.cvvDigits(len);
 }

package/src/card/index.ts

@@ -27,7 +27,7 @@ export {
   type CardBrand,
 } from "./format";
 
-export { formatCpf, validateCpf } from "./cpf";
+export { formatCpf, isValidCpf, validateCpf } from "./cpf";
 
 export { CardPayBar, NewCardForm, SavedCardsPicker } from "./fields";
 
@@ -40,3 +40,5 @@ export {
 } from "./tokenize";
 
 export { NEW_CARD, type CardDetails, type CardFieldErrors, type CardToken, type SavedCard } from "./types";
+export type { CardCopy, CardFieldCopy, CardTokenizeCopy } from "./copy";
+export { PT_BR_CARD_COPY } from "./pt-BR";

package/src/card/pt-BR.ts

@@ -0,0 +1,51 @@
+import type { CardCopy } from './copy';
+
+/**
+ * The pt-BR pack for the card form — a NAMED constant a host passes by hand,
+ * never a default.
+ *
+ * The filename is what exempts this file from the copy-portability gate:
+ * Portuguese may ship, it may not be silent. Every sentence is VERBATIM what
+ * the form used to render, so a host adopting it sees no change on screen —
+ * what changes is that the words are chosen in a diff.
+ */
+export const PT_BR_CARD_COPY: CardCopy = {
+  fields: {
+    unknownBrand: 'Cartão',
+    numberLabel: 'Número do cartão',
+    numberRequired: 'Informe o número do cartão.',
+    numberIncomplete: 'Número de cartão incompleto.',
+    numberInvalid: 'Número de cartão inválido.',
+    holderLabel: 'Nome impresso no cartão',
+    holderRequired: 'Informe o nome impresso no cartão.',
+    expiryLabel: 'Validade (MM/AA)',
+    cvvLabel: 'CVV',
+    monthInvalid: 'Mês inválido.',
+    expired: 'Cartão expirado.',
+    expiryInvalid: 'Validade inválida ou expirada.',
+    cvvInvalid: 'CVV inválido.',
+    cvvDigits: (length) => `CVV deve ter ${length} dígitos.`,
+    cpfRequired: 'CPF obrigatório.',
+    cpfInvalid: 'CPF inválido.',
+    savedCardsLabel: 'Cartão',
+    newCard: 'Novo cartão',
+    newCardDescription: 'Inserir outro cartão',
+    saveCard: 'Salvar cartão para próximas compras',
+  },
+  tokenize: {
+    sdkUnavailable: 'Não foi possível carregar o meio de pagamento. Recarregue a página.',
+    cardNotProcessed:
+      'Não foi possível processar o cartão. Verifique os dados e tente novamente.',
+    providerUnreachable:
+      'Não foi possível contatar o provedor do cartão. Verifique sua conexão.',
+    providerTimedOut: 'O provedor do cartão não respondeu a tempo.',
+    providerRefused: (status, response) =>
+      `O provedor recusou os dados do cartão (HTTP ${status}). ` +
+      `Resposta: ${response}`,
+    noPublicKey:
+      'A chave pública do cartão não está disponível para esta loja. ' +
+      'Reconecte o provedor e tente novamente.',
+    cardUnavailable:
+      'O pagamento com cartão está indisponível nesta loja no momento. Recarregue a página e tente de novo, escolha outro método de pagamento ou combine diretamente com a loja.',
+  },
+};

package/src/card/stripe-token.ts

@@ -19,6 +19,7 @@
 import { err, ok, type Result } from "../result";
 
 import type { CardDetails, CardToken } from "./types";
+import type { CardCopy } from "./copy";
 
 /** Stripe payment-methods endpoint — the publishable key authenticates. */
 const STRIPE_PAYMENT_METHODS_URL = "https://api.stripe.com/v1/payment_methods";
@@ -37,11 +38,12 @@ export async function tokenizeWithStripe(
   publicKey: string,
   brand: string,
   last4: string,
+  copy: CardCopy,
   /** Deadline for the round trip; an abort reads as "could not contact". */
   signal?: AbortSignal,
 ): Promise<Result<CardToken>> {
   const match = /^(\d{2})\/(\d{2})$/.exec(card.expiry.trim());
-  if (!match) return err("Validade inválida ou expirada.");
+  if (!match) return err(copy.fields.expiryInvalid);
 
   // Stripe's API speaks form-encoding, not JSON.
   const body = new URLSearchParams({
@@ -65,7 +67,7 @@ export async function tokenizeWithStripe(
       signal,
     });
   } catch {
-    return err("Não foi possível contatar o provedor do cartão. Verifique sua conexão.");
+    return err(copy.tokenize.providerUnreachable);
   }
 
   const parsed = (await response.json().catch(() => null)) as {
@@ -75,10 +77,7 @@ export async function tokenizeWithStripe(
   if (!response.ok || typeof parsed?.id !== "string") {
     const reason =
       typeof parsed?.error?.message === "string" ? parsed.error.message : JSON.stringify(parsed);
-    return err(
-      `O provedor recusou os dados do cartão (HTTP ${response.status}). ` +
-        `Resposta: ${String(reason).slice(0, 300)}`,
-    );
+    return err(copy.tokenize.providerRefused(response.status, String(reason).slice(0, 300)));
   }
   return ok({ token: parsed.id, brand, last4 });
 }