@12-apps/payments-frontend 3.29.1 → 3.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.29.1",
+  "version": "3.30.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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.29.0",
+    "@12-apps/payments-backend": "^4.30.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/CredentialFieldStack.tsx

@@ -6,6 +6,7 @@ import type { PaymentEnvironment, ProviderDescriptor } from '@12-apps/payments-b
 
 import { CredentialField } from './CredentialFields';
 import { appliesIn, saveLabel } from './credential-rules';
+import { checksLocally } from './checks-locally';
 import { FormActions, ReverifyWarning } from './CredentialFormAlerts';
 import type { CredentialFormState } from './ProviderCredentialForm';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -58,6 +59,7 @@ export function CredentialFields({
         willTest={form.complete}
         disabled={form.nothingEdited || !form.valid}
         onSave={form.requestSave}
+        local={checksLocally(descriptor)}
       />
     </Stack>
   );

package/src/components/CredentialFields.tsx

@@ -116,9 +116,11 @@ export function CredentialField({ spec, state, value, onChange, check }: Credent
         sx={{ display: 'block', fontSize: '12px', fontWeight: 650, color: T.ink2, mb: '5px' }}
       >
         {spec.label}
-        {spec.advanced ? (
-          <Box component="span" sx={{ fontWeight: 500, color: T.ink4 }}>
-            {copy.advancedSuffix}
+        {spec.advanced || spec.optional ? (
+          // `ink3`, not `ink4`: "opcional" carries real information, and at 12px
+          // the lighter ink fell under AA contrast.
+          <Box component="span" sx={{ fontWeight: 500, color: spec.optional ? T.ink3 : T.ink4 }}>
+            {spec.advanced ? copy.advancedSuffix : copy.optionalSuffix}
           </Box>
         ) : null}
       </Typography>

package/src/components/CredentialFormAlerts.tsx

@@ -189,12 +189,20 @@ export function ReverifyWarning({ displayName }: { displayName: string }) {
  * Nothing is learned by separating them: the probe reads what was just stored,
  * so the only useful moment to run it is immediately after a save.
  */
+/** What the bar promises: testing now, what a save will do, or that it only writes down. */
+function barMessage(copy: CredentialFormCopy, verifying: boolean, willTest: boolean, local: boolean): string {
+  if (verifying) return (local ? copy.probeLocalRunning : undefined) ?? copy.probeRunning;
+  if (!willTest) return copy.probeIncompleteNote;
+  return (local ? copy.probeLocalSaveNote : undefined) ?? copy.probeSaveNote;
+}
+
 export function FormActions({
   busy,
   label,
   willTest,
   disabled,
   onSave,
+  local = false,
 }: {
   busy: string | null;
   label: string;
@@ -202,17 +210,14 @@ export function FormActions({
   willTest: boolean;
   disabled: boolean;
   onSave: () => void;
+  /** The "test" is a local check (`checksLocally`): nothing is sent to a provider. */
+  local?: boolean;
 }) {
   // The bar states what pressing it costs, which is the half a verb cannot
   // carry: a complete set is sent to the provider on save, and a partial one is
   // only written down. The owner reads the promise and the button in one line.
   const copy = usePaymentsSettingsCopy().credentials;
-  const message =
-    busy === 'verify'
-      ? copy.probeRunning
-      : willTest
-        ? copy.probeSaveNote
-        : copy.probeIncompleteNote;
+  const message = barMessage(copy, busy === 'verify', willTest, local);
 
   return (
     <Box sx={BAR_SX} data-testid="payments-form-bar">

package/src/components/ProviderPanel.tsx

@@ -226,12 +226,49 @@ function oauthWalkthrough(props: ActivePanelProps, path: 'oauth' | 'credentials'
  * a FUNCTION: which steps to show depends on the disclosure, whose state lives
  * in `OAuthPanel`.
  */
+/** The one environment a provider has, when it declares a single one. */
+function soleEnvironment(descriptor: ActivePanelProps['descriptor']): PaymentEnvironment | null {
+  // Read defensively: a host-built descriptor (and many fixtures) may carry no capabilities at all.
+  const declared = (descriptor.capabilities as typeof descriptor.capabilities | undefined)?.environments;
+  return declared && declared.length === 1 ? (declared[0] ?? null) : null;
+}
+
+/**
+ * The environment selector and its notice — full-bleed across the card, and
+ * inset for the manual disclosure, where it no longer spans anything (see
+ * `EnvironmentNotice`). A provider with ONE environment (no sandbox: every code
+ * is real money) gets neither: there is nothing to choose, and a "test
+ * environment" notice would promise that no money moves.
+ */
+function environmentChrome(
+  sole: PaymentEnvironment | null,
+  environment: PaymentEnvironment,
+  onChange: (next: PaymentEnvironment) => void,
+  active: PaymentEnvironment | null,
+): { selector: ReactNode; band: ReactNode; notice: ReactNode } {
+  // Nothing to choose with one environment. The notice goes only for a
+  // PRODUCTION-only provider (it would promise no money moves); a sandbox-only
+  // one keeps its truthful "nothing is real" notice.
+  if (sole === 'PRODUCTION') return { selector: null, band: undefined, notice: null };
+  if (sole) {
+    return {
+      selector: null,
+      band: <EnvironmentNotice environment={environment} active={active} />,
+      notice: <EnvironmentNotice environment={environment} active={active} band={false} />,
+    };
+  }
+  return {
+    selector: <EnvironmentSelector environment={environment} onChange={onChange} />,
+    band: <EnvironmentNotice environment={environment} active={active} />,
+    notice: <EnvironmentNotice environment={environment} active={active} band={false} />,
+  };
+}
+
 export function ActivePanel(props: ActivePanelProps) {
   const { descriptor, config, client, onChanged, reload, guide, verification } = props;
   const statusBar = <EnableBar {...props} />;
-  const [environment, setEnvironment] = useState<PaymentEnvironment>(
-    config?.environment ?? 'SANDBOX',
-  );
+  const sole = soleEnvironment(descriptor);
+  const [environment, setEnvironment] = useState<PaymentEnvironment>(sole ?? config?.environment ?? 'SANDBOX');
   const [editing, setEditing] = useState(false);
 
   const oauthConnect = oauthWithConnect(props);
@@ -251,12 +288,7 @@ export function ActivePanel(props: ActivePanelProps) {
     />
   );
 
-  const selector = <EnvironmentSelector environment={environment} onChange={setEnvironment} />;
-  // Full-bleed across the card, and the same notice inset for the manual
-  // disclosure, where it no longer spans anything. See `EnvironmentNotice`.
-  const active = config?.environment ?? null;
-  const band = <EnvironmentNotice environment={environment} active={active} />;
-  const notice = <EnvironmentNotice environment={environment} active={active} band={false} />;
+  const { selector, band, notice } = environmentChrome(sole, environment, setEnvironment, config?.environment ?? null);
 
   const storedHere = requiredStored(descriptor, config, environment);
 

package/src/components/ProviderStatusBar.tsx

@@ -5,6 +5,7 @@ import { Box, Stack, Switch, Tooltip, Typography } from '@mui/material';
 import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
 
 import { certificateExpiryProximity, isConnected } from './connection-state';
+import { checksLocally } from './checks-locally';
 import { T } from './panel-tokens';
 import type { ConnectionStatusCopy } from './settings-copy';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -54,7 +55,9 @@ export function statusBadge(
   if (config?.status === 'RECONNECT_REQUIRED') {
     return { label: copy.reconnectRequired, color: 'error' };
   }
-  if (isConnected(config)) return { label: copy.connectionOk, color: 'info' };
+  if (isConnected(config)) {
+    return { label: (checksLocally(descriptor) ? copy.detailsOk : undefined) ?? copy.connectionOk, color: 'info' };
+  }
   // A FAILED probe lands here, and it says NÃO VERIFICADO like every other
   // not-yet-connected state. `FALHOU` was a third word for the same fact — the
   // store cannot take money through this provider yet — and it was the only
@@ -125,7 +128,7 @@ function toggleGate(
   if (!lockedOff) return { lockedOff, hint: '' };
   return {
     lockedOff,
-    hint: provable ? copy.threeStepsAhead : copy.connectAndVerifyFirst,
+    hint: provable ? copy.threeStepsAhead : ((checksLocally(descriptor) ? copy.checkDetailsFirst : undefined) ?? copy.connectAndVerifyFirst),
   };
 }
 

package/src/components/SetupGuideSection.tsx

@@ -186,12 +186,25 @@ export function SetupGuideSection({
   // have to render: they are the credential form, and swallowing them left a
   // provider with a status chip, a pair of environment tabs and no way to type
   // anything in.
+  // They take the card's 20px inset themselves, as every block in its
+  // unpadded body does (`ProviderCard`) — a guide's step panel carries it for
+  // them, and without one the boxes ran into the card's edges.
   if (!guide) {
     return (
-      <>
+      // The save bar and the saved-details row carry their own inset for the
+      // guided layout; here the wrapper already supplies it, so theirs is zeroed
+      // and their rule, text and button line up with the fields.
+      <Box
+        data-testid="payments-setup-unguided"
+        sx={{
+          px: '20px',
+          '& [data-testid="payments-form-bar"]': { px: 0 },
+          '& [data-testid="payments-credential-summary"]': { mx: 0 },
+        }}
+      >
         {rows}
         {sectionFooter}
-      </>
+      </Box>
     );
   }
 

package/src/components/checks-locally.ts

@@ -0,0 +1,13 @@
+import type { ProviderDescriptor } from '@12-apps/payments-backend';
+
+/**
+ * Whether this provider's "test" is a LOCAL check — there is no provider to
+ * connect to (the store's own Pix key, `capabilities.confirmation: 'MANUAL'`).
+ * Its screen must not say keys are tested "no provedor" or call a passing
+ * check a CONNECTION. Read defensively: a host-built descriptor may carry no
+ * capabilities.
+ */
+export function checksLocally(descriptor: Pick<ProviderDescriptor, 'capabilities'> | undefined): boolean {
+  const capabilities = descriptor?.capabilities as ProviderDescriptor['capabilities'] | undefined;
+  return capabilities?.confirmation === 'MANUAL';
+}

package/src/components/credential-rules.ts

@@ -5,6 +5,7 @@ import type {
   ProviderDescriptor,
 } from '@12-apps/payments-backend';
 
+import { checksLocally } from './checks-locally';
 import type { PendingSave } from './ConfirmCredentialSave';
 import type { CredentialFormCopy } from './settings-copy';
 
@@ -49,7 +50,7 @@ export function credentialsComplete(
 ): boolean {
   const stored = config?.environments[environment] ?? {};
   return descriptor.credentialSchema.every((spec) => {
-    if (spec.advanced || !appliesIn(spec, environment)) return true;
+    if (spec.advanced || spec.optional || !appliesIn(spec, environment)) return true;
     const typed = values[spec.key];
     if (typed !== undefined && typed.trim() !== '') return true;
     return stored[spec.key]?.configured === true;
@@ -104,10 +105,15 @@ export function saveLabel(
 ): string {
   const required = descriptor.credentialSchema.filter((field) => field.required);
   const only = required.length === 1 ? required[0] : undefined;
-  if (!only) return complete ? copy.saveAndTest : copy.save;
+  if (!only) return complete ? saveAndTestLabel(copy, descriptor) : copy.save;
   return copy.saveOnly(only.label.replace(/\s*\([^)]*\)\s*$/, ''));
 }
 
+/** "Salvar e testar conexão", or "Salvar e conferir" where nothing leaves for a provider. */
+function saveAndTestLabel(copy: CredentialFormCopy, descriptor: ProviderDescriptor): string {
+  return (checksLocally(descriptor) ? copy.saveAndCheck : undefined) ?? copy.saveAndTest;
+}
+
 /**
  * The stored value of the field a finished step collapses around.
  *

package/src/components/settings-copy.ts

@@ -30,6 +30,12 @@ export interface ConnectionStatusCopy {
   unverified: string;
   /** The credential probe passed; no charge has been made. */
   connectionOk: string;
+  /**
+   * `connectionOk` for a provider there is nothing to connect to — the store's
+   * own Pix key, checked here (`checksLocally`). Optional: absent, the chip
+   * falls back to `connectionOk`.
+   */
+  detailsOk?: string;
   /**
    * A connection that WAS working and stopped — the one red chip, because it
    * is news rather than a step still to finish.
@@ -41,6 +47,8 @@ export interface ConnectionStatusCopy {
   threeStepsAhead: string;
   /** The same, when the store must connect and verify first. */
   connectAndVerifyFirst: string;
+  /** `connectAndVerifyFirst` for a provider checked locally. Optional, falls back to it. */
+  checkDetailsFirst?: string;
   /** Live: this provider is taking money. */
   receiving: { state: string; sub: string };
   /** Proven, and switched off by the owner. */
@@ -194,6 +202,8 @@ export interface CredentialFormCopy {
   configuredKeepBlank: string;
   /** The suffix on an `advanced` field most stores must leave empty. */
   advancedSuffix: string;
+  /** The suffix on an `optional` field: blank keeps its default. */
+  optionalSuffix: string;
   probeAction: string;
   /**
    * What replacing a PROVEN connection's credentials costs.
@@ -206,6 +216,13 @@ export interface CredentialFormCopy {
   reverifyWarning(displayName: string): string;
   probeRunning: string;
   probeSaveNote: string;
+  /**
+   * `probeRunning` / `probeSaveNote` for a provider checked locally: nothing is
+   * sent anywhere, so saying the keys are tested "no provedor" would be false.
+   * Optional; absent, the provider sentences are used.
+   */
+  probeLocalRunning?: string;
+  probeLocalSaveNote?: string;
   probeIncompleteNote: string;
   probeFailed(environmentName: string): string;
   /** The per-credential marks beside each field. */
@@ -219,6 +236,8 @@ export interface CredentialFormCopy {
    * only written down, and a one-field provider names its field instead.
    */
   saveAndTest: string;
+  /** `saveAndTest` for a provider checked locally (no connection to test). Optional. */
+  saveAndCheck?: string;
   save: string;
   saveOnly(fieldLabel: string): string;
   /** Reopen a finished credential step — unaccented, so only a reading found it. */

package/src/components/settings-en-US.ts

@@ -22,10 +22,12 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     verified: 'VERIFIED',
     unverified: 'NOT VERIFIED',
     connectionOk: 'CONNECTION OK',
+    detailsOk: 'DETAILS OK',
     reconnectRequired: 'RECONNECT',
     notConnected: 'Not connected',
     threeStepsAhead: 'This provider only starts taking sales after the 3 steps below.',
     connectAndVerifyFirst: 'Connect and verify the provider before switching sales on.',
+    checkDetailsFirst: 'Fill in and check the details before switching sales on.',
     receiving: {
       state: 'Taking sales',
       sub: 'Your store is being paid through this provider.',
@@ -131,12 +133,15 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     configuredKeepBlank: 'Configured — leave blank to keep the current value.',
     // Leading space: it is appended to a field label.
     advancedSuffix: ' · Connect platforms only',
+    optionalSuffix: ' · optional',
     probeAction: 'Test connection',
     reverifyWarning: (displayName) =>
       `This store is already verified. Changing the credentials **requires re-verification** ` +
       `and the store **stops taking payments** through ${displayName} until it finishes.`,
     probeRunning: 'Testing the connection…',
     probeSaveNote: 'We save and test the keys with the provider before going on.',
+    probeLocalRunning: 'Checking the details…',
+    probeLocalSaveNote: 'We check the details before saving.',
     probeIncompleteNote: 'We kept what you have filled in. Complete the fields to test.',
     probeFailed: (environmentName) =>
       `Could not connect in ${environmentName}. Check the credentials for this environment.`,
@@ -144,6 +149,7 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     checkFail: 'Fix',
     uncheckable: 'Not verifiable',
     saveAndTest: 'Save and test connection',
+    saveAndCheck: 'Save and check',
     save: 'Save',
     saveOnly: (fieldLabel) => `Save ${fieldLabel}`,
     changeAction: 'Change',

package/src/components/settings-pt-BR.ts

@@ -14,10 +14,12 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     verified: 'VERIFICADO',
     unverified: 'NÃO VERIFICADO',
     connectionOk: 'CONEXÃO OK',
+    detailsOk: 'DADOS OK',
     reconnectRequired: 'RECONECTAR',
     notConnected: 'Não conectado',
     threeStepsAhead: 'Este provedor só passa a receber vendas depois dos 3 passos abaixo.',
     connectAndVerifyFirst: 'Conecte e verifique o provedor antes de ativar as vendas.',
+    checkDetailsFirst: 'Preencha e confira os dados antes de ativar as vendas.',
     receiving: {
       state: 'Recebendo vendas',
       sub: 'Sua loja está recebendo por este provedor.',
@@ -119,12 +121,15 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
   credentials: {
     configuredKeepBlank: 'Configurado — deixe em branco para manter o valor atual.',
     advancedSuffix: ' · só para plataformas Connect',
+    optionalSuffix: ' · opcional',
     probeAction: 'Testar conexão',
     reverifyWarning: (displayName) =>
       `Esta loja já está verificada. Trocar as credenciais **exige uma nova verificação** ` +
       `e a loja **para de receber** pelo ${displayName} até que ela termine.`,
     probeRunning: 'Testando a conexão…',
     probeSaveNote: 'Salvamos e testamos as chaves no provedor antes de seguir.',
+    probeLocalRunning: 'Conferindo os dados…',
+    probeLocalSaveNote: 'Conferimos os dados antes de salvar.',
     probeIncompleteNote: 'Guardamos o que você já preencheu. Complete os campos para testar.',
     probeFailed: (environmentName) =>
       `Não foi possível conectar em ${environmentName}. Confira as credenciais deste ambiente.`,
@@ -132,6 +137,7 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
     checkFail: 'Corrigir',
     uncheckable: 'Não verificável',
     saveAndTest: 'Salvar e testar conexão',
+    saveAndCheck: 'Salvar e conferir',
     save: 'Salvar',
     saveOnly: (fieldLabel) => `Salvar ${fieldLabel}`,
     changeAction: 'Alterar',