@12-apps/payments-frontend 3.2.3 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.2.3",
+  "version": "3.3.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.5.0",
+    "@12-apps/payments-backend": "^4.12.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/activation/charge-copy.ts

@@ -0,0 +1,23 @@
+/**
+ * The three sentences the card activation charge has to put on screen itself
+ * (FUT-763).
+ *
+ * Same rule as `RedirectActivationCopy`, for the same reason: these states are
+ * reached inside the flow and carry no message from the provider, so something
+ * has to be shown — and a fallback string compiled into the package is how one
+ * product's voice reaches every adopter. No defaults, and the field is required.
+ */
+export interface ActivationChargeCopy {
+  /**
+   * No tokenizer is registered for this provider, so nothing can be encrypted
+   * and there is no charge to make.
+   *
+   * `{provider}` is substituted with the provider's name — the one word that
+   * makes the sentence actionable on a screen listing several.
+   */
+  noTokenizer: string;
+  /** The server refused the charge and sent no reason of its own. */
+  chargeFailed: string;
+  /** The request never got out — the browser's own fetch threw. */
+  unreachable: string;
+}

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

@@ -0,0 +1,267 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import type React from 'react';
+
+import {
+  detectBrand,
+  onlyDigits,
+  tokenizeCard,
+  tokenizerFor,
+  validateCardNumber,
+  validateCpf,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  type CardDetails,
+  type CardFieldErrors,
+} from '../card';
+
+import type { ActivationChargeCopy } from './charge-copy';
+
+/**
+ * The activation charge for a provider whose payer pays HERE (FUT-463, moved
+ * into the package by FUT-763).
+ *
+ * A connection is not a capability. An OAuth grant completing tells you the
+ * owner authorized us; it does not tell you the account can take money, and the
+ * gap between those two is where a store ships broken — connected, switched on,
+ * and every real shopper met an access error because the integration had never
+ * been homologated.
+ *
+ * So the owner puts their own card through the SAME path a shopper takes — same
+ * fields, same validation, same browser-side encryption — for one cent,
+ * refunded immediately. Whatever would break for a buyer breaks here, in front
+ * of the person who can fix it.
+ *
+ * The sibling of `useRedirectActivation`, for the other half of the same step:
+ * that one is for a provider whose payer leaves for its own page. Both prove
+ * the same fact and both leave the SCREEN to the host.
+ */
+
+const EMPTY_CARD: CardDetails = { number: '', holder: '', expiry: '', cvv: '' };
+
+export type ActivationChargeState =
+  | { kind: 'idle' }
+  | { kind: 'submitting' }
+  /**
+   * The charge did not go through — the provider's reason, verbatim enough to
+   * act on. `providerMessage` carries the provider's RAW refusal when `reason`
+   * is a rewording of it, so the screen can show both.
+   */
+  | { kind: 'failed'; reason: string; providerMessage?: string }
+  /** Money moved. The server has already enabled the provider. */
+  | { kind: 'passed'; refunded: boolean };
+
+export interface ActivationChargeOptions {
+  /**
+   * The host's verify-charge endpoint for this provider.
+   *
+   * `GET` answers the store's card public key; `POST` takes the tokenized card
+   * and makes the charge. A whole URL, not the parts of one — the route shape
+   * belongs to the host.
+   */
+  verifyChargeUrl: string;
+  /**
+   * Which provider is being activated.
+   *
+   * Named rather than derived from a capability: two providers can both declare
+   * `tokenization: 'PUBLIC_KEY'` while speaking different protocols, so
+   * choosing by capability would silently mint one vendor's blob with another's
+   * key and report the second's rejection as though the card were bad.
+   */
+  provider: string;
+  /** The signed-in owner's e-mail — the charge's customer record. */
+  email: string;
+  /** The charge landed; the caller refreshes so the provider shows as active. */
+  onVerified: () => void;
+  copy: ActivationChargeCopy;
+}
+
+export interface ActivationCharge {
+  card: CardDetails;
+  setCard: React.Dispatch<React.SetStateAction<CardDetails>>;
+  fieldErrors: CardFieldErrors;
+  setFieldErrors: React.Dispatch<React.SetStateAction<CardFieldErrors>>;
+  cpf: string;
+  setCpf: (value: string) => void;
+  cpfError: string | undefined;
+  state: ActivationChargeState;
+  submit: () => Promise<void>;
+  /** Back to the form from a settled state, to try another card. */
+  reset: () => void;
+}
+
+/**
+ * The store's own card public key, fetched through the VERIFICATION endpoint.
+ *
+ * Not the checkout one: that reads credentials through the enabled gate, and a
+ * provider being verified is by definition still disabled.
+ */
+function usePublicKey(verifyChargeUrl: string): string | null {
+  const [publicKey, setPublicKey] = useState<string | null>(null);
+
+  useEffect(() => {
+    const alive = { current: true };
+    void fetch(verifyChargeUrl)
+      .then((res) => (res.ok ? (res.json() as Promise<{ publicKey?: string | null }>) : null))
+      .then((body) => {
+        if (alive.current && body?.publicKey) setPublicKey(body.publicKey);
+      })
+      .catch(() => undefined);
+    return () => {
+      alive.current = false;
+    };
+  }, [verifyChargeUrl]);
+
+  return publicKey;
+}
+
+/** Local validation — nothing reaches the provider until the card is well-formed. */
+function validateAll(card: CardDetails, cpf: string) {
+  const brand = detectBrand(onlyDigits(card.number));
+  return {
+    fieldErrors: {
+      number: validateCardNumber(card.number),
+      holder: validateHolder(card.holder),
+      expiry: validateExpiry(card.expiry),
+      cvv: validateCvv(card.cvv, brand),
+    } satisfies CardFieldErrors,
+    cpfError: validateCpf(cpf),
+  };
+}
+
+interface ChargeRequest {
+  verifyChargeUrl: string;
+  provider: string;
+  card: CardDetails;
+  cpf: string;
+  publicKey: string | null;
+  email: string;
+  copy: ActivationChargeCopy;
+}
+
+/**
+ * Tokenize the owner's card and ask the server to charge the cent.
+ *
+ * Strict tokenization on purpose: with no public key there is no encryption, so
+ * there would be nothing for the provider to accept or refuse — and a mock
+ * token that "passed" would switch on a store that cannot charge.
+ */
+async function runCharge(request: ChargeRequest): Promise<ActivationChargeState> {
+  const tokenizer = tokenizerFor(request.provider);
+  if (!tokenizer) {
+    return {
+      kind: 'failed',
+      reason: request.copy.noTokenizer.replace('{provider}', request.provider),
+    };
+  }
+
+  const tokenized = await tokenizeCard(request.card, request.publicKey, tokenizer);
+  if (!tokenized.ok) return { kind: 'failed', reason: tokenized.error };
+
+  try {
+    const response = await fetch(request.verifyChargeUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        token: tokenized.data.token,
+        taxId: onlyDigits(request.cpf),
+        holderName: request.card.holder.trim(),
+        email: request.email,
+      }),
+    });
+    const body = (await response.json().catch(() => null)) as
+      | { ok?: boolean; refunded?: boolean; reason?: string; providerMessage?: string }
+      | null;
+
+    if (!body?.ok) {
+      return {
+        kind: 'failed',
+        reason: body?.reason ?? request.copy.chargeFailed,
+        providerMessage: body?.providerMessage,
+      };
+    }
+    return { kind: 'passed', refunded: body.refunded === true };
+  } catch {
+    return { kind: 'failed', reason: request.copy.unreachable };
+  }
+}
+
+/** The typed-in card + CPF and their validation messages. */
+function useCardForm() {
+  const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
+  const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
+  const [cpf, setCpf] = useState('');
+  const [cpfError, setCpfError] = useState<string | undefined>(undefined);
+
+  const clear = useCallback(() => {
+    setCard(EMPTY_CARD);
+    setCpf('');
+  }, []);
+
+  return { card, setCard, fieldErrors, setFieldErrors, cpf, setCpf, cpfError, setCpfError, clear };
+}
+
+export function useActivationCharge(options: ActivationChargeOptions): ActivationCharge {
+  const { verifyChargeUrl, provider, email, onVerified, copy } = options;
+  const publicKey = usePublicKey(verifyChargeUrl);
+  const form = useCardForm();
+  const [state, setState] = useState<ActivationChargeState>({ kind: 'idle' });
+  const { card, cpf, setFieldErrors, setCpfError, clear } = form;
+
+  const submit = useCallback(async () => {
+    const validation = validateAll(card, cpf);
+    setFieldErrors(validation.fieldErrors);
+    setCpfError(validation.cpfError);
+    if (Object.values(validation.fieldErrors).some(Boolean) || validation.cpfError) return;
+
+    setState({ kind: 'submitting' });
+    const next = await runCharge({
+      verifyChargeUrl,
+      provider,
+      card,
+      cpf,
+      publicKey,
+      email,
+      copy,
+    });
+
+    // The card is cleared only once it has served its purpose; a failure leaves
+    // it typed in so the owner can fix one field rather than start over.
+    if (next.kind === 'passed') clear();
+    setState(next);
+    if (next.kind === 'passed') onVerified();
+  }, [
+    card,
+    cpf,
+    publicKey,
+    verifyChargeUrl,
+    provider,
+    email,
+    copy,
+    onVerified,
+    setFieldErrors,
+    setCpfError,
+    clear,
+  ]);
+
+  const reset = useCallback(() => {
+    setState({ kind: 'idle' });
+    setFieldErrors({});
+    setCpfError(undefined);
+  }, [setFieldErrors, setCpfError]);
+
+  return {
+    card: form.card,
+    setCard: form.setCard,
+    fieldErrors: form.fieldErrors,
+    setFieldErrors: form.setFieldErrors,
+    cpf: form.cpf,
+    setCpf: form.setCpf,
+    cpfError: form.cpfError,
+    state,
+    submit,
+    reset,
+  };
+}

package/src/components/checkout/use-checkout-controller.ts

@@ -177,21 +177,40 @@ function handOverToProvider(
 /**
  * How long the resumed screen keeps asking, and how often.
  *
- * 180 polls at 5 s ≈ 15 minutes. Both halves are chosen against what actually
- * settles a hosted charge, which is the WEBHOOK: it lands seconds after the
- * payment, so a faster interval buys nothing, and by a quarter of an hour a
- * delivery that was ever coming has come. Past that the answer is not going to
- * change while the buyer watches — the scheduled reconciliation is what
- * rescues a genuinely late one, and it does that whether the tab is open or
- * not.
+ * TWO RATES, because one rate cannot serve this wait. The interval decides two
+ * things that pull opposite ways: how fast a buyer WHO PAID is told so, and
+ * what an abandoned checkout costs for the rest of the window. Every poll is a
+ * provider round trip, so a slow rate is cheap and leaves a paying buyer
+ * watching a spinner seconds longer than they need to — and the person on this
+ * screen has almost always paid. A single number picks one of them to lose;
+ * this shipped at a flat 5 s and picked the wrong one.
+ *
+ * So: 2.5 s for the first two minutes, which is where essentially every real
+ * webhook lands (it fires within seconds of the payment, and this rate matches
+ * what card and PIX already use), then 10 s for the remaining thirteen. A
+ * confirmation is at most 2.5 s late, and an abandoned checkout costs ~126
+ * polls instead of the 360 a flat 2.5 s would have.
+ *
+ * The three constants are ONE decision — 48 × 2.5 s + 78 × 10 s ≈ 15 min — so
+ * the cap is derived rather than typed, and cannot drift from the comment.
+ *
+ * Fifteen minutes because by then a webhook that was ever coming has come. Past
+ * that the answer will not change while the buyer watches: the scheduled
+ * reconciliation is what rescues a genuinely late one, and it does that whether
+ * the tab is open or not.
  *
  * The card wait is bounded at 90 s (`CARD_AWAITING_POLL_CAP`) because a card
  * authorises inline and a buyer is holding their phone. This leg is the other
  * shape: the buyer has already been off to another site and back, and may
  * legitimately still be finishing there.
  */
-const HOSTED_RESUME_POLL_MS = 5_000;
-const HOSTED_RESUME_POLL_CAP = 180;
+const HOSTED_RESUME_FAST_MS = 2_500;
+const HOSTED_RESUME_SLOW_MS = 10_000;
+/** Two minutes at the fast rate, before the wait is worth economising on. */
+const HOSTED_RESUME_FAST_POLLS = (2 * 60_000) / HOSTED_RESUME_FAST_MS;
+/** Thirteen more at the slow one — 15 minutes all told. */
+const HOSTED_RESUME_POLL_CAP =
+  HOSTED_RESUME_FAST_POLLS + (13 * 60_000) / HOSTED_RESUME_SLOW_MS;
 
 /**
  * The leg of checkout that resumes after a hosted provider sent the buyer back
@@ -218,7 +237,9 @@ function useHostedResume(tenantSlug?: string): {
   const [order] = useState(() => takeHostedOrder(tenantSlug));
   const { status, timedOut } = usePaymentPolling(order?.orderId ?? null, {
     enabled: Boolean(order),
-    intervalMs: HOSTED_RESUME_POLL_MS,
+    intervalMs: HOSTED_RESUME_FAST_MS,
+    slowAfterPolls: HOSTED_RESUME_FAST_POLLS,
+    slowIntervalMs: HOSTED_RESUME_SLOW_MS,
     maxHealthyPolls: HOSTED_RESUME_POLL_CAP,
   });
   return { order, status, timedOut };

package/src/components/checkout/use-payment-polling.ts

@@ -14,11 +14,45 @@ interface PollingOptions {
    * Undefined ⇒ unbounded, today's behavior (the PIX consumer passes no cap).
    */
   maxHealthyPolls?: number;
+  /**
+   * Opt-in BACKOFF: after this many healthy polls, keep asking at
+   * {@link slowIntervalMs} instead of {@link intervalMs}.
+   *
+   * A single interval cannot serve a long wait, because the two things it
+   * decides pull opposite ways. It is how fast a buyer WHO PAID learns that
+   * they did — every poll is a provider round trip, and the answer lands within
+   * seconds of the webhook — and it is also what an abandoned checkout costs
+   * for the rest of the window. Tuning one picks the other's loser: a slow
+   * interval taxes the common case (the person on this screen almost always
+   * paid) to subsidise the rare one.
+   *
+   * Splitting them costs neither. Both must be set for backoff to apply.
+   */
+  slowAfterPolls?: number;
+  slowIntervalMs?: number;
 }
 
 /** Consecutive poll errors tolerated before giving up (avoids an infinite spinner). */
 const MAX_POLL_ERRORS = 4;
 
+/**
+ * How long before the next ask, given how many healthy polls have happened.
+ *
+ * A pure function of the options, so it lives out here rather than inside the
+ * effect — the hook is at its size gate, and a scheduling RULE is easier to
+ * read (and to test) stated once than threaded through a closure.
+ *
+ * Reads the count AFTER the poll just made, so the slow phase begins on the
+ * poll FOLLOWING the threshold rather than one early: a wait described as "N
+ * fast polls" has to actually make N of them.
+ */
+function pollDelay(healthy: number, options: PollingOptions): number {
+  const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
+  const backingOff =
+    slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
+  return backingOff ? slowIntervalMs : intervalMs;
+}
+
 /**
  * Poll an order's payment status until it reaches a terminal state.
  *
@@ -29,7 +63,13 @@ const MAX_POLL_ERRORS = 4;
  */
 export function usePaymentPolling(
   orderId: string | null,
-  { intervalMs = 2500, enabled = true, maxHealthyPolls }: PollingOptions = {},
+  {
+    intervalMs = 2500,
+    enabled = true,
+    maxHealthyPolls,
+    slowAfterPolls,
+    slowIntervalMs,
+  }: PollingOptions = {},
 ): { status: OrderStatus | null; error: string | null; timedOut: boolean } {
   const [status, setStatus] = useState<OrderStatus | null>(null);
   const [error, setError] = useState<string | null>(null);
@@ -80,7 +120,7 @@ export function usePaymentPolling(
       }
       timer = setTimeout(() => {
         void tick();
-      }, intervalMs);
+      }, pollDelay(healthyCount, { intervalMs, slowAfterPolls, slowIntervalMs }));
     };
 
     void tick();
@@ -91,7 +131,7 @@ export function usePaymentPolling(
         clearTimeout(timer);
       }
     };
-  }, [orderId, intervalMs, enabled, maxHealthyPolls, client]);
+  }, [orderId, intervalMs, enabled, maxHealthyPolls, slowAfterPolls, slowIntervalMs, client]);
 
   return { status, error, timedOut };
 }

package/src/flows/screens-hosted.tsx

@@ -99,16 +99,22 @@ function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHando
 /**
  * How long this screen keeps asking, and how often — see the twin constants in
  * `use-checkout-controller.ts`, which bounds the same wait for the components
- * layer. 180 polls at 5 s ≈ 15 minutes.
+ * layer. 2.5 s for two minutes, then 10 s for thirteen: 126 polls, 15 minutes.
+ *
+ * Two rates because one cannot serve both ends of this wait — a paying buyer
+ * learns within 2.5 s, an abandoned checkout costs a third of what a flat fast
+ * rate would. The reasoning is on the twin constants.
  *
  * Stated here rather than imported because the two waits are the same DECISION
- * arrived at twice, not one shared implementation: this screen takes its
+ * arrived at twice, not one shared implementation: this screen takes its FAST
  * interval from the host's `polling` config when there is one, and a host that
  * tunes that must not have this package's cap silently mean a different
  * wall-clock window than the constant's comment claims.
  */
-const RETURN_POLL_MS = 5_000;
-const RETURN_POLL_CAP = 180;
+const RETURN_FAST_MS = 2_500;
+const RETURN_SLOW_MS = 10_000;
+const RETURN_FAST_POLLS = (2 * 60_000) / RETURN_FAST_MS;
+const RETURN_POLL_CAP = RETURN_FAST_POLLS + (13 * 60_000) / RETURN_SLOW_MS;
 
 function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn"] {
   function HostedReturnBody({
@@ -125,7 +131,9 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
     // watches until they close the tab.
     const { status, timedOut } = usePaymentPolling(parked?.orderId ?? null, {
       enabled: Boolean(parked),
-      intervalMs: runtime.config.polling?.intervalMs ?? RETURN_POLL_MS,
+      intervalMs: runtime.config.polling?.intervalMs ?? RETURN_FAST_MS,
+      slowAfterPolls: RETURN_FAST_POLLS,
+      slowIntervalMs: RETURN_SLOW_MS,
       maxHealthyPolls: RETURN_POLL_CAP,
     });
 

package/src/index.ts

@@ -242,3 +242,23 @@ export {
  * taking a direct dependency on the backend package.
  */
 export type { PaymentEnvironment } from '@12-apps/payments-backend';
+
+// ---------------------------------------------------------------------------
+// The ACTIVATION CHARGE (FUT-463, packaged by FUT-763) — proving a connection
+// can charge, for a provider whose payer pays HERE.
+//
+// A connection is not a capability: a completed grant says the owner authorized
+// us, not that the account can take money. The owner's own card goes through
+// the SAME path a shopper's does — same fields, same validation, same
+// browser-side encryption — for one cent, refunded immediately.
+//
+// The sibling of `useRedirectActivation` for the other half of the same step.
+// As there, the SCREEN stays the host's.
+// ---------------------------------------------------------------------------
+export {
+  useActivationCharge,
+  type ActivationCharge,
+  type ActivationChargeOptions,
+  type ActivationChargeState,
+} from './activation/use-activation-charge';
+export { type ActivationChargeCopy } from './activation/charge-copy';