@cartbase/storefront 0.21.0 → 0.22.0

package/src/checkout/use-checkout-orchestration.ts

@@ -40,7 +40,11 @@ import {
   type StoreCustomer,
   type UpdateCustomerInput,
 } from "../api/customers"
-import { isStripeLike } from "../lib/payment-constants"
+import { envStripeAccountId, envStripeKey } from "../lib/stripe-env"
+import type { PickupPointKeys } from "../api/integrations"
+import { resolveCardOffer } from "./card-offer"
+import { pickupOptionOf } from "./pickup-option"
+import type { PickupPoint } from "./pickup-point-selector"
 import { clearCartCookie } from "../lib/cookie-names"
 import { useCartDrawer } from "../cart-drawer/context"
 import compareAddresses from "./compare-addresses"
@@ -48,7 +52,11 @@ import { translateAddressError } from "./address-error-copy"
 import { translatePaymentError } from "./payment-error-copy"
 import { useCheckoutLabels, useOrderConfirmedPath } from "./context"
 import type { EcontOffice } from "./econt-office-selector"
-import type { BoxNowLocker } from "../api/integrations"
+import type { BoxNowLocker, PigeonOffice } from "../api/integrations"
+import { fulfillmentOptionId } from "./fulfillment-option"
+import { useCheckoutFunnel } from "./use-checkout-funnel"
+import { amountDueAfterTender, isNothingToPay } from "./summary-math"
+import { forgetFiredEvents } from "../tracking/once"
 
 /**
  * useCheckoutOrchestration — single source of truth for checkout-page
@@ -165,6 +173,20 @@ export type UseCheckoutOrchestrationOptions = {
    * add your own sink; fire-and-forget either way.
    */
   logError?: CheckoutLogError
+  /**
+   * The checkout funnel: begin_checkout on arrival, add_shipping_info when
+   * the address is complete, add_payment_info when the tender is chosen,
+   * each once per cart, to every tag the store configured; the ad
+   * platforms' identity signals as they are typed; and the ad-click ids
+   * captured on the landing page written onto the cart so they reach the
+   * order (see `useCheckoutFunnel`).
+   *
+   * ON by default, like the checkout error log: the helpers all lived in
+   * this package and every checkout built on it fired none of them,
+   * because calling them was the store's job. Pass `false` in a store that
+   * fires its own, so nothing is counted twice.
+   */
+  trackFunnel?: boolean
   /**
    * Verbose [buy-click] console output for local debugging. OFF by default:
    * the unguarded dumps used to print the full prepare-checkout payload —
@@ -203,6 +225,13 @@ const REQUIRED_ADDRESS_FIELDS = [
  */
 const ADDRESS_AUTO_SAVE_DEBOUNCE_MS = 600
 
+/**
+ * Where the typed checkout form is kept for the tab's lifetime, so a
+ * refresh or a walk back to the cart does not empty it. One key per app:
+ * a storefront is mounted for a single store.
+ */
+const FORM_STORAGE_KEY = "cartbase:checkout-form"
+
 /** The offline tab's tender: a merchant METHOD entry (pp_* kill). The COD
  * method (kind 'cod') wins; any manual method serves as the offline tab
  * when no COD switch is on. The entry carries its own fee for prediction. */
@@ -269,6 +298,7 @@ export function useCheckoutOrchestration({
   onOrderPlaced,
   resolveTrackingMetadata,
   logError: logErrorProp,
+  trackFunnel = true,
   debug = false,
 }: UseCheckoutOrchestrationOptions) {
   // The store's language, for the sentences a shopper reads when a save
@@ -321,6 +351,17 @@ export function useCheckoutOrchestration({
     [cart]
   )
 
+  // A cart that was completed somewhere else (the other tab, the back
+  // button) is no cart: the browser forgets it here too, so the shopper's
+  // next Add starts a new one instead of being refused by a placed order.
+  // The order that was placed already cleared this in its own tab; this is
+  // the copy that never heard (store-package card, 2026-09-18).
+  useEffect(() => {
+    if (!cartIsCompleted) return
+    clearCartCookie()
+    void forgetCart()
+  }, [cartIsCompleted, forgetCart])
+
   // ── Address form ────────────────────────────────────────────────────
   const [addressError, setAddressError] = useState<string | null>(null)
   const [, setAddressSaving] = useState(false)
@@ -369,6 +410,55 @@ export function useCheckoutOrchestration({
       : true
   )
 
+  // ── The typed form survives a refresh ───────────────────────────────
+  // A shopper who reloads, or comes back from the cart, used to find every
+  // field empty and start again (store-package card, 2026-09-18). The form
+  // is kept for the tab's lifetime in the shopper's own browser and never
+  // leaves it: sessionStorage dies with the tab, and nothing here is sent
+  // anywhere the address was not already going.
+  //
+  // Restore runs AFTER mount, never in the state initializer: that
+  // initializer also runs on the server, where there is no storage, and
+  // hydration would keep the server's empty seed. A ref gates the autosave
+  // so the seed cannot overwrite what is stored before it is read.
+  const formRestoredRef = useRef(false)
+
+  useEffect(() => {
+    if (formRestoredRef.current) return
+    try {
+      const stored = window.sessionStorage.getItem(FORM_STORAGE_KEY)
+      if (stored) {
+        const parsed = JSON.parse(stored) as Record<string, string>
+        setFormData((prev) => {
+          const merged = { ...prev }
+          for (const [key, value] of Object.entries(parsed)) {
+            // Only fill what is EMPTY. What the server already knows (the
+            // cart's own address, a signed-in customer's) always wins over
+            // something typed in an older shopping session.
+            if (typeof value === "string" && value && !merged[key]) {
+              merged[key] = value
+            }
+          }
+          return merged
+        })
+      }
+    } catch {
+      // Private mode, a full quota, a corrupt value: a checkout never dies
+      // for a convenience.
+    } finally {
+      formRestoredRef.current = true
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!formRestoredRef.current) return
+    try {
+      window.sessionStorage.setItem(FORM_STORAGE_KEY, JSON.stringify(formData))
+    } catch {
+      // as above
+    }
+  }, [formData])
+
   /**
    * The store's own country list, fetched when the app did not pass one.
    *
@@ -760,9 +850,17 @@ export function useCheckoutOrchestration({
   const [optimisticShippingCost, setOptimisticShippingCost] = useState<
     number | null
   >(null)
+  // A method already on the cart wins, because that one is booked; failing
+  // that, the courier the shopper picked before the page reloaded
+  // (2026-09-18). Without the second the checkout forgot the choice on every
+  // refresh, since nothing is booked until Buy.
   const [selectedShippingMethod, setSelectedShippingMethod] = useState<
     string | null
-  >(cart?.shipping_methods?.at(-1)?.shipping_option_id || null)
+  >(
+    cart?.shipping_methods?.at(-1)?.shipping_option_id ||
+      (cart?.metadata?._checkout_shipping_option as string | undefined) ||
+      null
+  )
 
   // Every listed option is offerable: the Medusa-era pickup filter read an
   // embedded fulfillment_set the Cartbase API never sends (it never fired),
@@ -875,17 +973,74 @@ export function useCheckoutOrchestration({
     []
   )
 
+  // Pigeon Express keeps offices and lockers in ONE catalogue, told apart by
+  // which id key the order carries (`pigeon_office_id` here; the platform's
+  // destination registry owns both names).
+  const [selectedPigeonOffice, setSelectedPigeonOffice] =
+    useState<PigeonOffice | null>(
+      cart?.metadata?.pigeon_office_id
+        ? ({
+            id: cart.metadata.pigeon_office_id as string,
+            name: (cart.metadata.pigeon_point_name as string) ?? "",
+            type: "office",
+            city: (cart.metadata.pigeon_point_city as string) ?? "",
+            address: (cart.metadata.pigeon_point_address as string) ?? "",
+          } as PigeonOffice)
+        : null
+    )
+
+  const handleSelectPigeonOffice = useCallback(
+    (office: PigeonOffice | null) => {
+      setSelectedPigeonOffice(office)
+    },
+    []
+  )
+
+  /**
+   * THE pickup point, whatever the carrier (2026-09-18).
+   *
+   * The three states above are one state per carrier, written into one
+   * hardcoded metadata key each, which is why Speedy had no picker: adding a
+   * carrier meant a fourth copy of all of it. This one holds the chosen point
+   * AND the key names the carrier's own booking reads, which arrive with the
+   * point from the platform's destination registry, so nothing here knows
+   * what any carrier calls anything.
+   *
+   * It restores from the cart, because the choice is written to the cart when
+   * it is made (`persistPickupPoint` below): a shopper who reloads the
+   * checkout keeps the office they picked.
+   */
+  const [selectedPickupPoint, setSelectedPickupPoint] =
+    useState<PickupPoint | null>(
+      (cart?.metadata?._checkout_pickup_point as PickupPoint | undefined) ?? null
+    )
+  const [pickupKeys, setPickupKeys] = useState<PickupPointKeys | null>(
+    (cart?.metadata?._checkout_pickup_keys as PickupPointKeys | undefined) ?? null
+  )
+
   // ── Payment ─────────────────────────────────────────────────────────
   const [paymentError, setPaymentError] = useState<string | null>(null)
 
-  const hasCard = !!effectiveAvailablePaymentMethods?.some(
-    (m) => "id" in m && isStripeLike(m.id)
+  // ONE row answers both "is there a card?" and "how do we reach it?"
+  // (2026-09-18). The processor entry carries its own publishable key and,
+  // under Connect, the merchant's account, so the card tab and the Stripe
+  // mount can never disagree about which Stripe this is. Reading them apart
+  // was the old failure: a store could offer a card it had no way to charge.
+  const cardOffer = useMemo(
+    () =>
+      resolveCardOffer(
+        effectiveAvailablePaymentMethods as ReadonlyArray<
+          Record<string, unknown>
+        > | null,
+        { key: envStripeKey, accountId: envStripeAccountId }
+      ),
+    [effectiveAvailablePaymentMethods]
   )
-  const cardId = (
-    effectiveAvailablePaymentMethods?.find(
-      (m) => "id" in m && isStripeLike(m.id)
-    ) as { id: string } | undefined
-  )?.id
+  const cardEntry = cardOffer.entry
+  const cardPublishableKey = cardOffer.publishableKey
+  const cardStripeAccountId = cardOffer.accountId
+  const hasCard = !!cardEntry && cardOffer.mountable
+  const cardId = hasCard ? cardEntry?.id : undefined
   // The offline tab = a merchant METHOD (the COD switch, else the first
   // manual method) — sessions initiate by payment_method_id, provider NULL.
   const offlineMethod = findOfflineMethod(effectiveAvailablePaymentMethods)
@@ -893,6 +1048,21 @@ export function useCheckoutOrchestration({
   const codMethodId = offlineMethod?.payment_method_id
   const offlineIsCodKind = offlineMethod?.kind === "cod"
 
+  // The store offers a card it cannot mount: reported once, to the merchant,
+  // because the shopper must never be the one who discovers it. Pre-2026-09-18
+  // storefronts read the key from their own env, so this also names the one
+  // thing an un-upgraded store has to do.
+  const cardUnmountableReported = useRef(false)
+  useEffect(() => {
+    if (!cardEntry || cardOffer.mountable || cardUnmountableReported.current) return
+    cardUnmountableReported.current = true
+    logError(
+      "card_unmountable",
+      "The store offers a card processor but no publishable key reached the browser, so the card option is hidden.",
+      { provider_id: cardEntry.id }
+    )
+  }, [cardEntry, cardOffer.mountable, logError])
+
   // Default tab: card when available, else COD. The eager-session model
   // used to seed from the cart's pending session provider; in the
   // deferred-intent model there is no session at mount.
@@ -949,15 +1119,42 @@ export function useCheckoutOrchestration({
     [cart.id, client, cardId, codMethodId, offlineMethod]
   )
 
-  // Shipping selection is client state only. No addShippingMethod call,
-  // no metadata-clear updateCart — all of those wrote to the cart
-  // between toggles and produced the stale-data bug class. The shipping
-  // method ID is sent to the backend exactly once at Buy click via
-  // prepareCheckout.
+  /**
+   * REMEMBER WHAT THE SHOPPER CHOSE, across a reload (2026-09-18, evoo).
+   *
+   * Every choice on this page lived in React state until Buy, so a refresh,
+   * a phone waking up, or a tab restored the next morning threw away the
+   * courier and the office and left the shopper staring at an empty form
+   * they had already filled in once.
+   *
+   * It is written under OUR OWN names (`_checkout_*`), never the carrier's.
+   * The carrier's real keys are still written exactly once, at Buy, by
+   * `prepareCheckout`, which is what keeps the stale-data bug class dead: an
+   * eager write of `econt_office_code` beside a cart that had since moved to
+   * BoxNow is what caused it, and nothing here writes a carrier's key. These
+   * are the checkout's own notes to itself, and prepare-checkout overwrites
+   * the real ones from them.
+   */
+  const rememberChoice = useCallback(
+    (patch: Record<string, unknown>) => {
+      void updateCart(client, cart.id, { metadata: patch }).catch(() => {
+        // Best effort: forgetting a choice on reload is a worse checkout,
+        // never a broken one, so a failure here must not reach the shopper.
+      })
+    },
+    [client, cart.id]
+  )
+
+  // Shipping selection stays client state for the ORDER (no
+  // addShippingMethod call, no metadata-clear updateCart: those wrote to the
+  // cart between toggles and produced the stale-data bug class; the id is
+  // sent once at Buy via prepareCheckout). What is remembered is the
+  // CHOICE, under our own key, so a reload restores it.
   const handleSelectShipping = useCallback(
     (id: string) => {
       setShippingError(null)
       setSelectedShippingMethod(id)
+      rememberChoice({ _checkout_shipping_option: id })
 
       // Optimistic shipping cost — paint the totals row immediately so
       // the customer sees the right number before any network call.
@@ -973,23 +1170,58 @@ export function useCheckoutOrchestration({
 
       // Switching shipping invalidates any previously-selected carrier-
       // specific destination (e.g. picking direct address after BoxNow
-      // locker). All client state — no eager metadata-clear updateCart.
+      // locker). The carrier's own keys are never eagerly written, so only
+      // our own note is cleared beside the state.
       setSelectedBoxnowLocker(null)
       setSelectedEcontOffice(null)
+      setSelectedPickupPoint(null)
+      setPickupKeys(null)
+      rememberChoice({
+        _checkout_shipping_option: id,
+        _checkout_pickup_point: null,
+        _checkout_pickup_keys: null,
+      })
     },
-    [shippingMethods, calculatedPricesMap]
+    [shippingMethods, calculatedPricesMap, rememberChoice]
+  )
+
+  /**
+   * The chosen pickup point, remembered the moment it is chosen. The keys
+   * ride with it because they are what `prepareCheckout` writes the carrier's
+   * real metadata from, and a reloaded page has no picker mounted yet to
+   * fetch them again.
+   */
+  const handleSelectPickupPoint = useCallback(
+    (point: PickupPoint | null, keys: PickupPointKeys | null) => {
+      setSelectedPickupPoint(point)
+      setPickupKeys(keys)
+      rememberChoice({
+        _checkout_pickup_point: point,
+        _checkout_pickup_keys: keys,
+      })
+    },
+    [rememberChoice]
   )
 
   // ── Delivery readiness ──────────────────────────────────────────────
   const selectedFulfillmentOptionId = useMemo(() => {
-    const data = selectedShippingOption?.data as
-      | { id?: string }
-      | undefined
-      | null
-    return typeof data?.id === "string" ? data.id : null
+    return fulfillmentOptionId(selectedShippingOption)
   }, [selectedShippingOption])
   const selectedIsBoxnow = selectedFulfillmentOptionId === "boxnow-locker"
   const selectedIsEcont = selectedFulfillmentOptionId === "econt-office"
+  const selectedIsPigeon = selectedFulfillmentOptionId === "pigeon-office"
+
+  /**
+   * WHICH carrier and WHICH kind of point this option delivers to, read from
+   * the option's own id (2026-09-18). Every carrier names its options the
+   * same way, `<carrier>-<mode>`, because the platform's registry declares
+   * them that way, so a carrier connected tomorrow is understood here without
+   * a line being added. `address` is the door and has no point to pick.
+   */
+  const selectedPickup = useMemo(
+    () => pickupOptionOf(selectedFulfillmentOptionId),
+    [selectedFulfillmentOptionId]
+  )
 
   // Defensive: trust cart.metadata for locker/office IDs in addition to
   // local React state. On mobile the BoxNow locker selector was seen
@@ -1000,12 +1232,24 @@ export function useCheckoutOrchestration({
   // ghost — even though the cart server-side knew the locker was set.
   const hasBoxnowLockerInCart = !!cart?.metadata?.boxnow_locker_id
   const hasEcontOfficeInCart = !!cart?.metadata?.econt_office_code
+  const hasPigeonOfficeInCart = !!cart?.metadata?.pigeon_office_id
+
+  // An option that delivers to a point is not ready until the point is
+  // named, whatever the carrier. The three lines under it are the same rule
+  // written per carrier, kept for stores still mounting the old components;
+  // a store on the shared picker is answered by the first.
+  const pickupSatisfied =
+    !selectedPickup ||
+    (!!selectedPickupPoint && selectedPickupPoint.provider === selectedPickup.provider)
 
   const deliveryReady =
     (!!selectedShippingMethod ||
       (cart?.shipping_methods?.length ?? 0) > 0) &&
-    (!selectedIsBoxnow || !!selectedBoxnowLocker || hasBoxnowLockerInCart) &&
-    (!selectedIsEcont || !!selectedEcontOffice || hasEcontOfficeInCart)
+    (pickupSatisfied ||
+      // The legacy pickers answer for their own carriers.
+      (selectedIsBoxnow && (!!selectedBoxnowLocker || hasBoxnowLockerInCart)) ||
+      (selectedIsEcont && (!!selectedEcontOffice || hasEcontOfficeInCart)) ||
+      (selectedIsPigeon && (!!selectedPigeonOffice || hasPigeonOfficeInCart)))
 
   // Reconcile paymentTab with currently-available methods. When the
   // store's paymentMethodFilter strips a method in response to a shipping
@@ -1051,6 +1295,17 @@ export function useCheckoutOrchestration({
     // cart instead of being refused by the completed one.
     clearCartCookie()
     await forgetCart()
+    // The typed form goes with the cart: the next shopper on this browser,
+    // or this one starting another order, begins on an empty form.
+    try {
+      window.sessionStorage.removeItem(FORM_STORAGE_KEY)
+    } catch {
+      // storage unavailable — nothing to clear
+    }
+    // The funnel guards for this cart go too. They are keyed by cart, so a
+    // second order would fire its own events anyway; this keeps the store
+    // from carrying a key for every cart the session ever bought.
+    forgetFiredEvents(cart.id)
 
     if (onOrderPlaced) {
       onOrderPlaced(order)
@@ -1202,6 +1457,42 @@ export function useCheckoutOrchestration({
     optimisticMethodFee,
   ])
 
+  // ── Nothing left to pay ─────────────────────────────────────────────
+  // A cart a promotion covered entirely, or one whose gift cards cover the
+  // whole total, asks the shopper for no money. The platform already knows
+  // this: prepare-checkout works out the charge as the collection's amount
+  // minus the gift-card tender and, at zero, mints no provider session at
+  // all, so the answer comes back with no client secret and no provider
+  // and the cart completes on what is already on it (Stripe refuses a
+  // zero-amount intent anyway).
+  //
+  // The checkout used to ignore that and put a card form in front of a
+  // shopper with nothing to pay. The same arithmetic here, on the numbers
+  // the shopper is looking at, so the payment section can stand down and
+  // the Buy click can skip Stripe entirely.
+  const amountDue = useMemo(
+    () => amountDueAfterTender(optimisticTotal, cart?.gift_card_total),
+    [optimisticTotal, cart?.gift_card_total]
+  )
+  const nothingToPay = isNothingToPay(amountDue)
+
+  // ── The funnel ──────────────────────────────────────────────────────
+  // Every store on this hook reports the same three steps to the same
+  // tags, writes the same identity signals and carries the same ad-click
+  // ids onto the order, without wiring anything.
+  useCheckoutFunnel({
+    client,
+    cart,
+    enabled: trackFunnel,
+    value: optimisticTotal,
+    allRequiredFilled,
+    addressReady,
+    deliveryReady,
+    shippingTier: selectedShippingOption?.name ?? undefined,
+    paymentTab,
+    formData,
+  })
+
   // ── Optimistic total in cents (for Stripe Elements deferred-intent) ─
   // Stripe's deferred-intent <Elements> needs `amount` + `currency` at
   // mount time (no PaymentIntent on the backend yet). Same value as
@@ -1244,15 +1535,51 @@ export function useCheckoutOrchestration({
         carrierMetadata.boxnow_locker_postal =
           selectedBoxnowLocker.postalCode ?? ""
       }
+      if (selectedPigeonOffice) {
+        // The platform's destination registry owns these names: the id key
+        // says office or locker, and the three label keys are what the order
+        // page and the waybill read back (src/lib/shipping/destinations.ts).
+        carrierMetadata.pigeon_office_id = String(selectedPigeonOffice.id)
+        carrierMetadata.pigeon_point_name = selectedPigeonOffice.name
+        carrierMetadata.pigeon_point_city = selectedPigeonOffice.city ?? ""
+        carrierMetadata.pigeon_point_address = selectedPigeonOffice.address ?? ""
+      }
+      // The carrier-agnostic pickup point (2026-09-18). The names come from
+      // the platform's destination registry with the point itself, so this
+      // writes what THIS carrier's booking reads without knowing which
+      // carrier it is. The three blocks above are the same write done four
+      // times by hand, kept for stores still mounting the old components;
+      // this one is what a new carrier arrives through.
+      if (selectedPickupPoint && pickupKeys) {
+        carrierMetadata[pickupKeys.point] = selectedPickupPoint.id
+        if (pickupKeys.name) carrierMetadata[pickupKeys.name] = selectedPickupPoint.name
+        if (pickupKeys.city) carrierMetadata[pickupKeys.city] = selectedPickupPoint.city
+        if (pickupKeys.address)
+          carrierMetadata[pickupKeys.address] = selectedPickupPoint.address
+        if (pickupKeys.phone) carrierMetadata[pickupKeys.phone] = selectedPickupPoint.phone
+        if (pickupKeys.postal)
+          carrierMetadata[pickupKeys.postal] = selectedPickupPoint.postal_code
+      }
 
       const shippingMethodId = selectedShippingMethod
       if (!shippingMethodId) {
         throw new Error("No shipping method selected")
       }
-      // The tender: card tab → the processor; offline tab → the merchant
-      // method (provider-less session, pp_* kill).
-      const tender =
-        paymentTab === "card"
+      // The tender. On the card tab it is the processor, on the offline tab
+      // the merchant method (a provider-less session, pp_* kill).
+      //
+      // With nothing left to pay the shopper was asked for no tender, so we
+      // name whichever the store has: prepare-checkout requires exactly one
+      // of the two even when the charge is zero, and at zero it mints no
+      // session from either, so which one is named changes nothing. The
+      // processor is preferred because a method could carry a fee.
+      const tender = nothingToPay
+        ? cardId
+          ? { payment_provider: cardId }
+          : codMethodId
+            ? { payment_method_id: codMethodId }
+            : null
+        : paymentTab === "card"
           ? cardId
             ? { payment_provider: cardId }
             : null
@@ -1283,9 +1610,11 @@ export function useCheckoutOrchestration({
       selectedShippingMethod,
       selectedEcontOffice,
       selectedBoxnowLocker,
+      selectedPigeonOffice,
       paymentTab,
       cardId,
       codMethodId,
+      nothingToPay,
     ])
 
   // ── Buy click ───────────────────────────────────────────────────────
@@ -1350,7 +1679,13 @@ export function useCheckoutOrchestration({
 
       await flushAddressSave()
 
-      if (paymentTab === "card") {
+      // Nothing to pay: no card form was ever shown, so there is no Stripe
+      // form to validate and nothing to confirm. The prepare below writes
+      // the address, the delivery and the tender, answers with no session,
+      // and the cart completes on what already covers it.
+      const cardPath = paymentTab === "card" && !nothingToPay
+
+      if (cardPath) {
         if (!stripeBundle) {
           // eslint-disable-next-line no-console
           console.error("[buy-click] card path but no stripe bundle")
@@ -1399,7 +1734,7 @@ export function useCheckoutOrchestration({
       const zeroRemainderGiftPath =
         prep.client_secret === null && prep.provider_id === null
 
-      if (paymentTab === "card" && !zeroRemainderGiftPath) {
+      if (cardPath && !zeroRemainderGiftPath) {
         if (!stripeBundle || !prep.client_secret) {
           // eslint-disable-next-line no-console
           console.error(
@@ -1522,11 +1857,13 @@ export function useCheckoutOrchestration({
       selectedShippingMethod,
       selectedEcontOffice,
       selectedBoxnowLocker,
+      selectedPigeonOffice,
       flushAddressSave,
       buildPrepareCheckoutPayload,
       placeOrder,
       formData,
       logError,
+      nothingToPay,
     ]
   )
 
@@ -1559,6 +1896,7 @@ export function useCheckoutOrchestration({
     selectedFulfillmentOptionId,
     selectedIsBoxnow,
     selectedIsEcont,
+    selectedIsPigeon,
     shippingLoading,
     shippingError,
     optimisticShippingCost,
@@ -1570,12 +1908,24 @@ export function useCheckoutOrchestration({
     handleSelectEcontOffice,
     selectedBoxnowLocker,
     handleSelectBoxnowLocker,
+    selectedPigeonOffice,
+    handleSelectPigeonOffice,
+    /** The pickup point, whatever the carrier, and which carrier and kind of
+     * point the chosen option asks for. Null on a door delivery. */
+    selectedPickupPoint,
+    handleSelectPickupPoint,
+    selectedPickup,
 
     // Payment
     paymentTab,
     hasCard,
     hasCod,
     cardId,
+    /** The store's own Stripe, off the card entry — what `PaymentWrapper`
+     * loads Stripe.js with. Undefined on a store that still sets the env
+     * pair, or on a platform that has not been upgraded. */
+    cardPublishableKey,
+    cardStripeAccountId,
     /** The offline tab's method (the COD switch or a manual method). */
     codMethodId,
     offlineMethod,
@@ -1586,6 +1936,10 @@ export function useCheckoutOrchestration({
     setOptimisticMethodFee,
     handlePaymentTab,
     handlePaymentElementChange,
+    /** What is still to be paid after any gift-card tender. */
+    amountDue,
+    /** True when the order asks the shopper for no money at all. */
+    nothingToPay,
 
     // Amount sync + recovery (SDK-wrapped)
     syncPaymentAmount,

package/src/lib/stripe-env.ts

@@ -0,0 +1,25 @@
+/**
+ * The storefront's own Stripe, from env — the FALLBACK, not the source.
+ *
+ * A Cartbase store's card credentials come from the store: the `pp_stripe`
+ * entry of `GET /api/store/payment-providers` carries the publishable key
+ * and, under Connect, the merchant's account id, because under Connect the
+ * key is Cartbase's and only the platform knows the pairing. Connecting
+ * Stripe in the admin is the entire setup; nothing is configured here.
+ *
+ * These two variables are what the Medusa storefronts we ported from used
+ * (`NEXT_PUBLIC_STRIPE_KEY` in mindpages' payment-wrapper), and they are
+ * right for a storefront that IS one shop with one Stripe account. They stay
+ * supported for a store that runs its own Stripe outside the platform, and
+ * so that a storefront which already set them keeps working.
+ *
+ * Read at module load, like any `NEXT_PUBLIC_*` value: Next inlines them at
+ * build time, so they cannot be read dynamically anyway.
+ */
+
+export const envStripeKey = process.env.NEXT_PUBLIC_STRIPE_KEY
+
+export const envStripeAccountId = process.env.NEXT_PUBLIC_STRIPE_ACCOUNT_ID
+
+/** True when the storefront carries its own Stripe key in env. */
+export const hasEnvStripeKey = (): boolean => !!envStripeKey