@flopay/react 1.9.8 → 1.9.10

package/README.md

@@ -902,6 +902,29 @@ SDK shows exactly one required fallback pane after approval and resumes with
 the collected values. A checkout that supplied buyer details up front keeps its
 existing request bodies and callbacks.
 
+**In-app presentation and recovery:** Direct PayPal classifies the browser once
+per mount into a bounded app family; it never records the raw user agent.
+`approvalPresentation` selects the bounded `app_switch` mode only for a
+one-time Order in an in-app browser. When the backend advertises
+`gateways.paypal.approvalPresentation: 'app_switch'`, that mode enables PayPal's
+`appSwitchWhenAvailable` Buttons option.
+Ordinary browsers, legacy sessions, subscriptions, and setup tokens preserve
+the popup flow. The PayPal button stays visible in every environment as a
+result of this choice. If an in-app popup is blocked and no supported non-popup
+mode is available, `onTechnicalFailure` receives `popupBlocked: true` with
+fixed guidance to open the page in the system browser; ordinary browsers keep
+the existing allow-popups guidance, and PayPal remains visible for retry.
+
+`approvalPresentation` is a bounded mode, not a URL. Merchant code cannot
+inject a return URL or resume token. Although the shared response type reserves
+`'redirect'`, the classic Buttons adapter does not activate it: deterministic
+redirect remains gated on the backend-issued signed resume contract and a
+proven PayPal adapter that captures before merchant-success navigation. Until
+both land, a redirect advertisement safely preserves popup behavior. This
+instrumentation explains where approval attempts stop; it does not by itself
+attribute the historical conversion drop to a particular browser or provider
+failure.
+
 **Flo-owned subscription continuations:** `gateways.paypal.providerObjectType`
 selects the direct PayPal operation. `'order'` loads the PayPal SDK with
 `intent=capture` and invokes `createOrder`, even when the checkout session mode
@@ -916,20 +939,27 @@ legacy sessions continue to derive Order versus Subscription from
 `isSubscription` and keep the released `paypal` requests byte-identical. See
 the full [channel-selection and cutover contract](../../docs/PAYPAL_FLO_SUBSCRIPTION_CONTINUATIONS.md).
 
-**Direct PayPal initialization recovery:** PayPal's own cross-window bridge owns
-its 10-second `postMessage init()` acknowledgement deadline; FloPay does not
-change that upstream timeout. If the exact acknowledgement timeout is reported,
-or if `Buttons.render()` is still unsettled after 11 seconds, the SDK hides
-Direct PayPal, waits one second, and makes exactly one background render retry.
-The retry uses a fresh render generation, and callbacks or promise settlements
-from the superseded generation are ignored.
+**Direct PayPal initialization recovery:** Any active-generation technical
+failure before PayPal becomes ready — script rejection, a namespace without a
+usable `Buttons` factory, an eligible pre-ready `onError`, a `render()`
+rejection, or the SDK's 11-second render watchdog — hides Direct PayPal, waits
+one second, and makes exactly one background remount. Recovery is based on
+lifecycle state, not provider error text. The retry uses a fresh render
+generation, and callbacks or promise settlements from the superseded generation
+are ignored. Startup remount does not create a checkout session, intent, or
+charge; the first recovered buyer click creates at most one intent under the
+existing per-click idempotency contract.
 
 In a mixed checkout, card, wallets, APMs, and any other eligible methods remain
-interactive throughout recovery. If both Direct PayPal attempts fail, PayPal
-stays hidden for that component configuration; the SDK emits one sanitized
-console diagnostic and calls neither `onError` nor `onDecline`. Deterministic
-configuration failures and `isEligible() === false` are not automatically
-retried.
+interactive throughout recovery. If Direct PayPal is configured alongside
+Stripe-rendered PayPal, the Stripe-rendered path activates while Direct PayPal
+is retrying or exhausted. If both Direct PayPal attempts fail, PayPal stays
+hidden for that component configuration; the SDK emits one sanitized console
+diagnostic and calls neither `onError` nor `onDecline`. Empty configuration,
+`isEligible() === false`, cancellation, supersession, unmount, and recognized
+lifecycle teardown are not automatically retried. Ineligibility still notifies
+the parent that PayPal is unavailable so a fallback can appear, without
+technical telemetry.
 
 In a PayPal-only checkout, `FloPayCheckout` shows an accessible retrying status
 instead of a blank surface. After automatic recovery is exhausted, it shows safe
@@ -945,7 +975,7 @@ The SDK exposes the relevant pieces in three ways:
 
 - **`FloPayProvider`** (manual composition): accepts an optional `paypalFlopay` prop used to drive Stripe's PayPal redirect leg. Load a second `FloPay` instance yourself only if you need to render PayPal manually. `usePayPalFloPay()` exposes it to descendants.
 
-- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, `isSubscription`, and the backend-advertised `providerObjectType` when present. `isSubscription` remains the compatibility fallback when the field is absent.
+- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, `isSubscription`, and the backend-advertised `providerObjectType` and `approvalPresentation` when present. The backing session is authoritative; `isSubscription` remains the compatibility fallback when the object type is absent.
 
 ### Using Hooks
 
@@ -1052,6 +1082,22 @@ Stripe and PayPal SDK load/runtime failures emit `provider_runtime`. Inline
 `validation_rejected` / `payment_declined` outcomes and never carry
 `failureCategory`.
 
+If Stripe.js cannot initialize after `FloPayCheckout` resolves a full session,
+the checkout no longer hides a provider-independent payment surface. A
+vault-capable session continues with the hosted card form, and Direct PayPal
+continues when the session advertises it; Stripe wallets and APMs are omitted.
+The degraded surface exposes one **Retry payment methods** action. It retries
+only provider initialization and never repeats session read/create/claim,
+automatic checkout, intent creation, or payment processing. A failed retry is
+not offered again during that mount, and cards or Direct PayPal remain usable.
+
+When neither the hosted card form nor Direct PayPal can render, `onError` and
+the `error` render prop receive a `FloPayError` with code
+`CheckoutInitializationFailed`. The default error surface uses fixed buyer-safe
+copy. Raw provider messages are never placed in the DOM or merchant callback.
+Existing-session transport and malformed-response failures are separately
+reported at `session_read`; expected session outcomes remain non-alerting.
+
 Direct PayPal script and unusable-namespace failures remain
 `PROVIDER_LOAD_FAILED` at `provider_load`. Once PayPal reports the button as
 eligible, a pre-ready `onError` or rejected `render()` is instead