@12-apps/payments-frontend 3.18.0 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.18.0",
+  "version": "3.19.0",
   "type": "module",
   "sideEffects": false,
   "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.",
@@ -22,7 +22,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.25.0",
+    "@12-apps/payments-backend": "^4.26.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/activation/screens/copy-en-US.ts

@@ -0,0 +1,110 @@
+import { EN_US_CARD_COPY } from '../../card';
+
+import type { ActivationStepCopy } from './copy';
+
+/**
+ * The twin of `./copy-pt-BR.ts`, key for key (FUT-764).
+ *
+ * A pack, not a default — see that file for the whole argument, and for the
+ * list of strings that deliberately do not move across the pair: **Checkout
+ * Integrado** (PagBank's own console label), **CPF** and its `000.000.000-00`
+ * mask (a Brazilian document and a FORMAT), the provider names, and this
+ * package's `{provider}` placeholder.
+ */
+export const EN_US_ACTIVATION_STEP_COPY: ActivationStepCopy = {
+  intro: {
+    title: 'Step 3 · Turn selling on',
+    cardBody: (amountLabel) =>
+      `Make a test charge${amountLabel ? ` of ${amountLabel}` : ''} on your own card. It is ` +
+      'refunded automatically, and it is what proves your shop can genuinely take money.',
+    realCharge: (amountLabel) =>
+      `We raise a real ${amountLabel} charge on your own account. Paying it is what proves your ` +
+      'shop can genuinely take money.',
+    payingYourself: (amountLabel) =>
+      `You are paying yourself: the ${amountLabel} leaves your payment method and lands in the ` +
+      "account that receives this shop's sales. There is no refund because the money never left " +
+      'your control.',
+  },
+  actions: {
+    chargeAndActivate: (amountLabel) =>
+      `Charge${amountLabel ? ` ${amountLabel}` : ''} and activate`,
+    payAndActivate: (amountLabel) => `Pay ${amountLabel} and activate`,
+    testAgain: 'Test again',
+    retry: 'Try again',
+    tryAgain: 'Try once more',
+    restart: 'I have switched it on — restart Step 3',
+    generateNewCharge: 'Generate a new charge',
+    checkNow: 'Check now',
+    alreadyPaidCheckNow: 'I have paid — check now',
+    setProviderOrder: 'Set the order between providers',
+    seePublishedStore: 'See the published shop',
+  },
+  awaiting: {
+    receivedTitle: 'Payment received — confirming',
+    receivedBody:
+      'We are confirming your payment with the provider. This usually takes a few seconds.',
+    declinedTitle: 'The payment was declined',
+    waitingTitle: 'Waiting for the payment…',
+    waitingBody: (amountLabel) =>
+      `We raised the ${amountLabel} charge and opened the provider's page in another tab. ` +
+      'Pay there and come back: we check for ourselves the moment it lands.',
+    lastChecked: (seconds) => `Last checked ${seconds}s ago`,
+    openPaymentPage: 'Open the payment page',
+    copyLink: 'Copy the link',
+    linkCopied: 'Link copied',
+    showLink: 'Show the link',
+    hideLink: 'Hide the link',
+  },
+  outcome: {
+    approvedTitle: 'Test charge approved',
+    refundedBody: (amountLabel) =>
+      `Your shop can take payments. The ${amountLabel} was refunded automatically.`,
+    refundPendingBody: (amountLabel) =>
+      `Your shop can take payments. The ${amountLabel} refund did not complete — ` +
+      'it will show up on your statement.',
+    someAmount: 'amount',
+    authenticatedNotActive: 'Authenticated, but not activated',
+    refusedTitle: (displayName) => `${displayName} refused to create the charge`,
+    refusedBody: (displayName) =>
+      `${displayName} refused to create the charge. That almost always means ` +
+      'Checkout Integrado is still switched off on your account. Nothing was charged — ' +
+      'we reopened Step 2 above: turn it on there and come back.',
+    unreachableTitle: 'We could not reach the provider',
+    expiredTitle: 'The charge expired',
+    settledTitle: 'Test charge confirmed',
+    settledBody: (amountLabel) =>
+      `Your shop can take payments. The ${amountLabel} stays in your account — ` +
+      'InfinitePay refunds are made in their own app.',
+    provenTitle: 'Test charge confirmed',
+    provenBody:
+      'Your shop has proved it can take money through this provider. We switched sales ' +
+      'on automatically — you can pause them with the button at the top whenever you like. ' +
+      'No further charge is needed.',
+    providerSaid: 'The provider answered:',
+    blockedTitle: 'Step 2 is still unconfirmed',
+    blockedBody:
+      'Confirm above that Checkout Integrado is enabled on your account. Without it the ' +
+      'provider creates no payment link at all, and this charge would fail.',
+  },
+  taxId: {
+    label: "Cardholder's CPF",
+    hint: 'PagBank requires it on every card charge.',
+    placeholder: '000.000.000-00',
+  },
+  charge: {
+    card: EN_US_CARD_COPY,
+    noTokenizer:
+      'Card tokenization is not implemented for {provider} yet, ' +
+      'so the verification charge cannot be made from here.',
+    chargeFailed: 'The test charge could not be completed.',
+    unreachable: 'Could not connect. Check your connection and try again.',
+  },
+  redirect: {
+    chargeExpired: 'The charge expired.',
+    confirmFailed: 'The test charge could not be confirmed.',
+    createFailed: 'The test charge could not be raised.',
+    confirmTimedOut:
+      'We could not confirm the payment in time. If you have already paid, the charge is ' +
+      'still valid — reload the page to check again.',
+  },
+};

package/src/activation/screens/copy-pt-BR.ts

@@ -0,0 +1,126 @@
+import { PT_BR_CARD_COPY } from '../../card';
+
+import type { ActivationStepCopy } from './copy';
+
+/**
+ * Everything step 3 says, in Portuguese (FUT-764).
+ *
+ * A pack, not a default. Nothing in this package reads it: `createActivationStep`
+ * still REQUIRES its copy, and a host that wants these words names them. That
+ * distinction is the one `copy.ts` and `settings-copy.ts` argue for — a default
+ * in the origin host's language reads as finished to the next host right up
+ * until an owner sees it — and it is why the eight packs already on
+ * `../../locales` are not a breach of it either.
+ *
+ * These sentences are here because they are the ACTIVATION STEP's vocabulary
+ * and not one product's voice: "a cobrança de teste é o que libera as vendas",
+ * "autenticado, mas não ativado", "última verificação há Ns". Every adopter
+ * would write them again, word for word, because they describe outcomes this
+ * package decides. They came from the first adopting host, where they had been
+ * maintained beside a screen that no longer lives there.
+ *
+ * ## What does NOT get translated, in either half
+ *
+ * **Checkout Integrado** is the exact label on PagBank's own console; an owner
+ * sent looking for "Integrated Checkout" is looking for a screen that does not
+ * exist. **CPF** and its `000.000.000-00` mask are a Brazilian document and a
+ * FORMAT — a translated mask shows a shape the field refuses. **PagBank** and
+ * **InfinitePay** are names. `{provider}` is this package's own placeholder,
+ * substituted after the sentence is chosen.
+ */
+export const PT_BR_ACTIVATION_STEP_COPY: ActivationStepCopy = {
+  intro: {
+    title: 'Passo 3 · Ative as vendas',
+    cardBody: (amountLabel) =>
+      `Faça uma cobrança de teste${amountLabel ? ` de ${amountLabel}` : ''} no seu próprio ` +
+      'cartão. Ela é estornada automaticamente e é o que comprova que sua loja consegue ' +
+      'receber de verdade.',
+    realCharge: (amountLabel) =>
+      `Geramos uma cobrança real de ${amountLabel} na sua própria conta. Pagar por ela é o que ` +
+      'comprova que sua loja consegue receber de verdade.',
+    payingYourself: (amountLabel) =>
+      `Você paga para si mesmo: os ${amountLabel} saem do seu meio de pagamento e caem na conta ` +
+      'que recebe as vendas desta loja. Não há estorno porque o valor não sai do seu controle.',
+  },
+  actions: {
+    chargeAndActivate: (amountLabel) => `Cobrar${amountLabel ? ` ${amountLabel}` : ''} e ativar`,
+    payAndActivate: (amountLabel) => `Pagar ${amountLabel} e ativar`,
+    testAgain: 'Testar novamente',
+    retry: 'Tentar novamente',
+    tryAgain: 'Tentar de novo',
+    restart: 'Já habilitei — recomeçar o Passo 3',
+    generateNewCharge: 'Gerar nova cobrança',
+    checkNow: 'Conferir agora',
+    alreadyPaidCheckNow: 'Já paguei — conferir agora',
+    setProviderOrder: 'Definir a ordem entre provedores',
+    seePublishedStore: 'Ver a loja publicada',
+  },
+  awaiting: {
+    receivedTitle: 'Pagamento recebido — confirmando',
+    receivedBody:
+      'Estamos confirmando seu pagamento com o provedor. Isso costuma levar poucos segundos.',
+    declinedTitle: 'O pagamento foi recusado',
+    waitingTitle: 'Aguardando o pagamento…',
+    waitingBody: (amountLabel) =>
+      `Geramos a cobrança de ${amountLabel} e abrimos a página do provedor em outra aba. ` +
+      'Pague por lá e volte aqui: conferimos sozinhos assim que o pagamento cair.',
+    lastChecked: (seconds) => `Última verificação há ${seconds}s`,
+    openPaymentPage: 'Abrir a página de pagamento',
+    copyLink: 'Copiar link',
+    linkCopied: 'Link copiado',
+    showLink: 'Ver o link',
+    hideLink: 'Esconder o link',
+  },
+  outcome: {
+    approvedTitle: 'Cobrança de teste aprovada',
+    refundedBody: (amountLabel) =>
+      `Sua loja já consegue receber pagamentos. O ${amountLabel} foi estornado automaticamente.`,
+    refundPendingBody: (amountLabel) =>
+      `Sua loja já consegue receber pagamentos. O estorno do ${amountLabel} não foi concluído — ` +
+      'ele aparecerá na sua fatura.',
+    someAmount: 'valor',
+    authenticatedNotActive: 'Autenticado, mas não ativado',
+    refusedTitle: (displayName) => `A ${displayName} recusou criar a cobrança`,
+    refusedBody: (displayName) =>
+      `A ${displayName} recusou criar a cobrança. Isso quase sempre significa que o ` +
+      'Checkout Integrado ainda está desligado na sua conta. Nada foi cobrado — ' +
+      'reabrimos o Passo 2 acima: habilite lá e volte aqui.',
+    unreachableTitle: 'Não conseguimos falar com o provedor',
+    expiredTitle: 'A cobrança expirou',
+    settledTitle: 'Cobrança de teste confirmada',
+    settledBody: (amountLabel) =>
+      `Sua loja já consegue receber pagamentos. O ${amountLabel} fica na sua conta — ` +
+      'estornos da InfinitePay são feitos no app dela.',
+    provenTitle: 'Cobrança de teste confirmada',
+    provenBody:
+      'Sua loja provou que consegue receber por este provedor. Ligamos as vendas ' +
+      'automaticamente — você pode pausar pelo botão no topo quando quiser. Nenhuma nova ' +
+      'cobrança é necessária.',
+    providerSaid: 'Resposta do provedor:',
+    blockedTitle: 'Falta confirmar o Passo 2',
+    blockedBody:
+      'Confirme acima que o Checkout Integrado está habilitado na sua conta. Sem ele o ' +
+      'provedor não cria nenhum link de pagamento, e esta cobrança falharia.',
+  },
+  taxId: {
+    label: 'CPF do titular',
+    hint: 'Exigido pelo PagBank em qualquer cobrança no cartão.',
+    placeholder: '000.000.000-00',
+  },
+  charge: {
+    card: PT_BR_CARD_COPY,
+    noTokenizer:
+      'Ainda não há tokenização de cartão implementada para {provider}, ' +
+      'então a cobrança de verificação não pode ser feita por aqui.',
+    chargeFailed: 'Não foi possível concluir a cobrança de teste.',
+    unreachable: 'Não foi possível conectar. Verifique sua conexão e tente novamente.',
+  },
+  redirect: {
+    chargeExpired: 'A cobrança expirou.',
+    confirmFailed: 'Não foi possível confirmar a cobrança de teste.',
+    createFailed: 'Não foi possível gerar a cobrança de teste.',
+    confirmTimedOut:
+      'Não conseguimos confirmar o pagamento a tempo. Se você já pagou, a cobrança continua ' +
+      'válida — recarregue a página para conferir de novo.',
+  },
+};

package/src/ledger/query.ts

@@ -55,11 +55,22 @@ export function ledgerSearchTerm(params: URLSearchParams): string {
   return params.get('q') ?? '';
 }
 
-/** A grid query mapped back onto the params a ledger URL owns. */
+/**
+ * A grid query mapped back onto the params a ledger URL owns.
+ *
+ * `dir` accepts `null` as well as absent, because that is what a real grid
+ * produces: a column can be in the sort list with no direction chosen yet, and
+ * a data-grid library spells that `null` rather than by leaving the key out.
+ * The runtime always treated the two the same — an unsorted column contributes
+ * no `sort` param — so this is the TYPE catching up with the behaviour rather
+ * than a change to it. Typed the other way, every adopter writes the same
+ * `?? undefined` mapping at the call site, which is exactly the boilerplate
+ * this module exists to delete.
+ */
 export function ledgerParams(query: {
   search: string;
   page: number;
-  sortBy: readonly { id: string; dir?: 'asc' | 'desc' }[];
+  sortBy: readonly { id: string; dir?: 'asc' | 'desc' | null }[];
 }): Record<string, string | undefined> {
   const sort = query.sortBy[0];
   return {

package/src/locales.ts

@@ -1,3 +1,6 @@
+import type { ActivationStepCopy } from './activation/screens/copy';
+import { EN_US_ACTIVATION_STEP_COPY } from './activation/screens/copy-en-US';
+import { PT_BR_ACTIVATION_STEP_COPY } from './activation/screens/copy-pt-BR';
 import type { CardCopy } from './card/copy';
 import { EN_US_CARD_COPY, PT_BR_CARD_COPY } from './card';
 import type { CheckoutPaymentCopy } from './components/checkout-payment-copy';
@@ -40,6 +43,17 @@ import { PT_BR_PAYMENTS_SETTINGS_COPY } from './components/settings-pt-BR';
  */
 type LocalePack<T> = { readonly 'pt-BR': T; readonly 'en-US': T };
 
+/**
+ * Step 3's words (FUT-764). `createActivationStep` still REQUIRES its copy and
+ * reads nothing from here — a host that wants these names them, which is the
+ * distinction between a pack and a default. They arrived from the first
+ * adopting host, where they had outlived the screen they belonged to.
+ */
+export const ACTIVATION_STEP_COPY = {
+  'pt-BR': PT_BR_ACTIVATION_STEP_COPY,
+  'en-US': EN_US_ACTIVATION_STEP_COPY,
+} as const satisfies LocalePack<ActivationStepCopy>;
+
 export const CARD_COPY = {
   'pt-BR': PT_BR_CARD_COPY,
   'en-US': EN_US_CARD_COPY,
@@ -88,6 +102,7 @@ export const PLATFORM_HOMOLOGACAO_COPY = {
  * key them — while the root keeps exporting the pt-BR names it always has, so
  * no existing import moves.
  */
+export { EN_US_ACTIVATION_STEP_COPY } from './activation/screens/copy-en-US';
 export { EN_US_CARD_COPY } from './card';
 export { EN_US_CHECKOUT_PAYMENT_COPY } from './components/checkout-payment-en-US';
 export {