@12-apps/payments-frontend 1.20.2 → 1.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.20.2",
+  "version": "1.21.1",
   "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": "^2.0.2",
+    "@12-apps/payments-backend": "^2.1.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/ConnectionProbe.tsx

@@ -7,7 +7,7 @@ import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments
 
 import type { PaymentsSettingsClient } from '../client';
 import { isConnected } from './connection-state';
-import { ProbeAlert, type VerifyProbe } from './CredentialFormAlerts';
+import { ProbeAlert, ProbeChecklist, type VerifyProbe } from './CredentialFormAlerts';
 
 /**
  * "Testar conexão" for a store whose connection is a GRANT, not a form.
@@ -73,6 +73,9 @@ export function ConnectionProbe({
       </Button>
       {error ? <Alert severity="error">{error}</Alert> : null}
       {probe ? <ProbeAlert probe={probe} busy={busy} onRetry={() => void verify()} /> : null}
+      {/* Shown on a pass too — see `ProbeChecklist`: what a green probe did
+          NOT check is the half an owner cannot otherwise find out. */}
+      {probe ? <ProbeChecklist probe={probe} /> : null}
     </Stack>
   );
 }

package/src/components/CredentialFormAlerts.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Alert, Button, CircularProgress, Stack, Typography } from '@mui/material';
+import { Alert, Box, Button, CircularProgress, Stack, Typography } from '@mui/material';
 
 import type { VerifiedProviderConfig } from '@12-apps/payments-backend';
 
@@ -78,6 +78,72 @@ export function ProbeAlert({
   );
 }
 
+/**
+ * Off-screen but read aloud. Inline rather than `@mui/utils`'s `visuallyHidden`,
+ * which is not a dependency of this package — one style object is not worth a
+ * new one on a package that ships to every host.
+ */
+const SCREEN_READER_ONLY = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  overflow: 'hidden',
+  clip: 'rect(0 0 0 0)',
+  whiteSpace: 'nowrap',
+} as const;
+
+/** How each verdict reads at a glance — the mark, and what it is called. */
+const CHECK_MARKS = {
+  PASS: { mark: '✓', color: 'success.main', label: 'Verificado' },
+  FAIL: { mark: '✕', color: 'error.main', label: 'Corrigir' },
+  UNCHECKED: { mark: '–', color: 'text.secondary', label: 'Não verificável' },
+} as const;
+
+/**
+ * What the probe established, credential by credential (FUT-796).
+ *
+ * Rendered on a PASS as well as a failure, which is the point. One boolean over
+ * a four-field form told an owner their connection was fine when only the
+ * secret key had been checked — the publishable key and the signing secret
+ * failed later, at a buyer's card and at a payment that never confirmed, where
+ * neither looks like a credential problem.
+ *
+ * The `UNCHECKED` row is the one that earns this component. It says a
+ * credential could NOT be verified and why, which a green tick would deny and a
+ * red cross would misattribute — and it tells the owner precisely which part of
+ * a passing result not to lean on.
+ */
+export function ProbeChecklist({ probe }: { probe: VerifyProbe }) {
+  if (!probe.checks?.length) return null;
+  return (
+    <Stack spacing={0.5} data-testid="payments-probe-checks">
+      {probe.checks.map((check) => {
+        const { mark, color, label } = CHECK_MARKS[check.status];
+        return (
+          <Stack
+            key={check.key}
+            direction="row"
+            spacing={1}
+            alignItems="flex-start"
+            data-testid={`payments-probe-check-${check.key}`}
+            data-status={check.status}
+          >
+            <Typography component="span" sx={{ color, fontWeight: 700, lineHeight: 1.5 }}>
+              <span aria-hidden>{mark}</span>
+              {/* The mark alone is colour-only information; the state has to be
+                  readable to anyone not seeing the colour. */}
+              <Box component="span" sx={SCREEN_READER_ONLY}>{` ${label}: `}</Box>
+            </Typography>
+            <Typography variant="body2" color="text.secondary">
+              {check.message}
+            </Typography>
+          </Stack>
+        );
+      })}
+    </Stack>
+  );
+}
+
 /**
  * Changing the tag on a store that has ALREADY proved it can receive.
  *

package/src/components/ProviderConnection.tsx

@@ -163,9 +163,22 @@ function ConnectionSummary(props: {
           />
         </Stack>
       ) : null}
+      {/*
+        The connected sentence names NO platform. It used to open with one
+        adopter's product name, hard-coded — so every other host installing this
+        package told its own merchants that somebody else's product was creating
+        their charges, with no prop to change it. The tell that it was an
+        oversight rather than a decision is the branch right below, which already
+        templates the provider from props.
+
+        Nothing was lost by removing it. The sentence exists to answer ONE
+        question — why no API key had to be copied — and the answer is the OAuth
+        grant, not whose logo is on the page. The subject is the connection
+        itself, which is true for every host and needs no new configuration.
+      */}
       <Typography variant="body2" color="text.secondary">
         {props.connected
-          ? 'Sua conta está conectada. O Future Pay cria as cobranças em seu nome — nenhuma chave precisa ser copiada.'
+          ? 'Sua conta está conectada. As cobranças são criadas em seu nome — nenhuma chave precisa ser copiada.'
           : `Conecte sua conta ${props.displayName} autorizando o acesso no site do provedor. Nenhuma chave precisa ser copiada.`}
       </Typography>
       {props.connected && props.connectedAccount ? (

package/src/components/ProviderCredentialForm.tsx

@@ -25,6 +25,7 @@ import {
 import {
   FormActions,
   ProbeAlert,
+  ProbeChecklist,
   ReverifyWarning,
   type VerifyProbe,
 } from './CredentialFormAlerts';
@@ -375,6 +376,11 @@ export function ProviderForm(props: ProviderFormProps) {
       {form.probe ? (
         <ProbeAlert probe={form.probe} busy={form.busy !== null} onRetry={form.verify} />
       ) : null}
+      {/* The pasted-key path, and the one FUT-796 is about: this form is where
+          the credentials the probe reports on were typed, so its findings
+          belong beside them — including on a pass, where the unchecked rows are
+          the only place an owner learns what was NOT established. */}
+      {form.probe ? <ProbeChecklist probe={form.probe} /> : null}
 
       <ConfirmCredentialSave
         pending={form.pending}

package/src/components/checkout/hosted-return.ts

@@ -18,7 +18,31 @@ import type { CheckoutOrder } from "./types";
  * unrelated session.
  */
 
-const KEY = "futurepay.checkout.hostedOrder";
+/**
+ * Where the parked order lives, namespaced to this PACKAGE.
+ *
+ * It used to carry one adopter's brand as its namespace, written into every
+ * adopter's browser. A storage key is not a private detail: it is observable
+ * surface, asserted on by `@12-apps/payments-e2e` and visible in devtools to
+ * anyone running the host. The sibling handover in this same folder already got
+ * this right with a `payments:` prefix; this one did not.
+ *
+ * Exported so a host or a spec names it rather than retyping it.
+ */
+export const HOSTED_ORDER_STORAGE_KEY = "payments.checkout.hostedOrder";
+
+/**
+ * The key before the rename, READ ONLY.
+ *
+ * A buyer who left for the provider's page on the old bundle comes back to the
+ * new one with their order parked under the old name. Without this they land on
+ * the plain return screen — the order still settles, because the webhook does
+ * that and never depended on any of this, but the confirmation they were
+ * promised is missing for a reason they could not possibly understand.
+ *
+ * Delete once no session can still be mid-redirect across that deploy.
+ */
+const LEGACY_KEY = "futurepay.checkout.hostedOrder";
 
 /**
  * What a hosted provider appends to the return URL. InfinitePay sends the
@@ -46,7 +70,7 @@ function isReturnTrip(): boolean {
 /** Park the raised order before handing the buyer to the provider's page. */
 export function rememberHostedOrder(order: CheckoutOrder): void {
   try {
-    window.sessionStorage?.setItem(KEY, JSON.stringify(order));
+    window.sessionStorage?.setItem(HOSTED_ORDER_STORAGE_KEY, JSON.stringify(order));
   } catch {
     // Storage disabled or full. The redirect must still happen: the webhook
     // settles the order either way, and refusing to send the buyer to pay
@@ -62,15 +86,37 @@ export function rememberHostedOrder(order: CheckoutOrder): void {
  * of resuming one they never paid. Read-and-clear for the same reason: the
  * resumed view belongs to exactly one return.
  */
-export function takeHostedOrder(): CheckoutOrder | null {
-  if (!isReturnTrip()) return null;
-  let raw: string | null = null;
+/**
+ * The raw parked payload under either key, cleared as it is read.
+ *
+ * Split out from {@link takeHostedOrder} so the storage handling and the
+ * parsing stay separately readable — reading two keys and clearing both put the
+ * combined function over the complexity gate, and the two halves fail for
+ * unrelated reasons anyway (storage disabled vs. a value that is not an order).
+ *
+ * BOTH keys are cleared whichever one answered: this is read-and-clear, and a
+ * legacy entry left behind would let a later return trip resume an order that
+ * was already consumed.
+ */
+function takeParkedPayload(): string | null {
   try {
-    raw = window.sessionStorage?.getItem(KEY) ?? null;
-    window.sessionStorage?.removeItem(KEY);
+    const raw =
+      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
+      window.sessionStorage?.getItem(LEGACY_KEY) ??
+      null;
+    window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
+    window.sessionStorage?.removeItem(LEGACY_KEY);
+    return raw;
   } catch {
+    // Storage disabled or unavailable — the same "no parked order" as an empty
+    // slot, and the webhook still settles the order regardless.
     return null;
   }
+}
+
+export function takeHostedOrder(): CheckoutOrder | null {
+  if (!isReturnTrip()) return null;
+  const raw = takeParkedPayload();
   if (!raw) return null;
   try {
     const parsed: unknown = JSON.parse(raw);

package/src/index.ts

@@ -87,6 +87,13 @@ export {
 export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
 export { PaymentsUnavailable } from './components/checkout/payments-unavailable';
 export { fetchCheckoutConfig } from './components/checkout/client';
+/**
+ * The `sessionStorage` key the hosted-checkout return leg parks the raised
+ * order under. Public because it is already observable — a spec asserting the
+ * handover, or a host clearing storage on sign-out, otherwise retypes the
+ * literal and silently drifts when it changes.
+ */
+export { HOSTED_ORDER_STORAGE_KEY } from './components/checkout/hosted-return';
 // ---------------------------------------------------------------------------
 // Digital wallets (FUT-471/472) — the Google-branded button and the capability
 // read it is gated on. `CheckoutFlow` wires these automatically; they are