@base44/app-plugin-commerce 0.8.1 → 0.8.3

package/base44/functions/commerce/admin-refunds/entry.ts

@@ -5,6 +5,9 @@
  * Actions: create | delete
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
 import { refundCardOrder } from "../../../shared/commerce/payments.ts";
 import { round2 } from "../../../shared/commerce/money.ts";
@@ -64,6 +67,7 @@ async function create(sr: any, payload: any, actor: string): Promise<any> {
   let gatewayRefund: Awaited<ReturnType<typeof refundCardOrder>> = null;
   if (payload.refund_payment) {
     gatewayRefund = await refundCardOrder(sr, order, {
+      secrets,
       amount,
       reason: payload.reason,
     });

package/base44/functions/commerce/payment-webhook/entry.ts

@@ -27,6 +27,9 @@
  * 400 `webhook_not_implemented`.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { confirmCardPayment } from "../../../shared/commerce/payments.ts";
@@ -41,7 +44,7 @@ Deno.serve(async (req: Request) => {
   try {
     const payload = await req.text();
 
-    const event = await parseWebhook(req, payload);
+    const event = await parseWebhook(req, payload, secrets);
     // Not about one of this store's orders — acknowledge so the provider
     // doesn't retry.
     if (!event || !event.order_id) {
@@ -62,6 +65,7 @@ Deno.serve(async (req: Request) => {
 
     const settings = await getSettings(sr);
     const result = await confirmCardPayment(sr, order, {
+      secrets,
       reference: event.reference,
       trustedPaid: event.paid,
       settings,

package/base44/functions/commerce/payments/entry.ts

@@ -25,6 +25,9 @@
  * order without a key. Entity access is service-role throughout.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, getCallerUser, isAdmin } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { serializeOrderForCustomer } from "../../../shared/commerce/orders.ts";
@@ -112,6 +115,7 @@ Deno.serve(async (req: Request) => {
           returnPath: settings.general?.order_received_path,
         });
         const link = await startCardPayment(sr, order, {
+      secrets,
           successUrl,
           cancelUrl,
           customerEmail: order.billing?.email || undefined,
@@ -134,6 +138,7 @@ Deno.serve(async (req: Request) => {
         const order = await authorizeOrder(sr, payload, admin);
         const settings = await getSettings(sr);
         const result = await confirmCardPayment(sr, order, {
+      secrets,
           settings,
           actor: admin ? (user?.email ?? "admin") : "customer-return",
         });
@@ -154,6 +159,7 @@ Deno.serve(async (req: Request) => {
               returnPath: settings.general?.order_received_path,
             });
             paymentLink = await startCardPayment(sr, result.order, {
+      secrets,
               successUrl,
               cancelUrl,
               customerEmail: result.order.billing?.email || undefined,
@@ -195,6 +201,7 @@ Deno.serve(async (req: Request) => {
         const order = await authorizeOrder(sr, payload, admin);
         const settings = await getSettings(sr);
         const result = await confirmCardPayment(sr, order, {
+      secrets,
           settings,
           actor: admin ? (user?.email ?? "admin") : "customer-return",
         });

package/base44/functions/commerce/storefront-checkout/entry.ts

@@ -12,6 +12,9 @@
  * Checkout is open to guests; order_key possession is the guest bearer credential.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+// The only layer that may reach the runtime: shared/ is client-bundleable,
+// so the secret store is read here and handed down per call.
+import { secrets } from "base44:runtime";
 import { HttpError, getCallerUser, ownsEmail } from "../../../shared/commerce/auth.ts";
 import { getSetting, getSettings } from "../../../shared/commerce/settings.ts";
 import { calculateTotals } from "../../../shared/commerce/totals.ts";
@@ -290,6 +293,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
       returnPath: settings.general?.order_received_path,
     });
     const link = await startCardPayment(sr, order, {
+      secrets,
       successUrl,
       cancelUrl,
       customerEmail: billing.email,
@@ -357,6 +361,7 @@ async function confirmPayment(sr: any, payload: any): Promise<any> {
 
   const settings = await getSettings(sr);
   const result = await confirmCardPayment(sr, order, {
+      secrets,
     settings,
     actor: "customer-return",
   });

package/base44/shared/commerce/card-payment.stripe.ts

@@ -39,9 +39,19 @@
  * `card-payment.<provider>.ts` next to the stub. `references/online-payments.md`
  * has the rules; this file is the worked model.
  */
-import { secrets } from "base44:runtime";
 import { HttpError } from "./auth.ts";
 
+/**
+ * The app's secret store, handed in per call by the function layer:
+ * `import { secrets } from "base44:runtime"` there, never in this file —
+ * that specifier resolves only in the Deno function runtime, and `shared/` is
+ * reachable by the client bundler, so importing it here fails the storefront's
+ * build. `Deno.env` would leak the same runtime assumption.
+ */
+export interface SecretStore {
+  get(name: string): unknown;
+}
+
 /** Stripe's REST API, called directly — no SDK to bundle in the function. */
 const STRIPE_API = "https://api.stripe.com/v1";
 /** Pinned, so a Stripe API release can never change the shapes read below. */
@@ -62,9 +72,9 @@ export interface CardPaymentPage {
  * store that has the file but not yet the secret answers a clean 503 at
  * checkout instead of failing to boot every commerce function that imports it.
  */
-const secret = (name: string): string => {
+const secret = (secrets: SecretStore, name: string): string => {
   try {
-    return String(secrets.get(name) ?? "");
+    return String(secrets?.get(name) ?? "");
   } catch {
     return "";
   }
@@ -77,9 +87,9 @@ const secret = (name: string): string => {
  */
 const STRIPE_KEY_SECRETS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
 
-const stripeKey = (): string => {
+const stripeKey = (secrets: SecretStore): string => {
   for (const name of STRIPE_KEY_SECRETS) {
-    const value = secret(name);
+    const value = secret(secrets, name);
     if (value) return value;
   }
   // The client is told only that cards are unavailable — which secret is
@@ -100,7 +110,7 @@ const stripeKey = (): string => {
  * as `base44_app_id`, which is how the platform attributes a Stripe payment
  * back to this app — send it on every call that creates money movement.
  */
-const base44AppId = (): string => secret("BASE44_APP_ID") || String(Deno.env.get("BASE44_APP_ID") ?? "");
+const base44AppId = (secrets: SecretStore): string => secret(secrets, "BASE44_APP_ID");
 
 /**
  * One Stripe REST call. A body makes it a POST (form-encoded, with an
@@ -109,9 +119,9 @@ const base44AppId = (): string => secret("BASE44_APP_ID") || String(Deno.env.get
  * Stripe's own error text stays in the log: it describes backend configuration
  * (keys, account state, API parameters), so the caller gets a flat message.
  */
-async function stripeCall(path: string, body?: URLSearchParams): Promise<any> {
+async function stripeCall(secrets: SecretStore, path: string, body?: URLSearchParams): Promise<any> {
   const headers: Record<string, string> = {
-    "Authorization": `Bearer ${stripeKey()}`,
+    "Authorization": `Bearer ${stripeKey(secrets)}`,
     "Stripe-Version": STRIPE_VERSION,
   };
   if (body) {
@@ -152,7 +162,7 @@ export async function createCardPayment(
     order_id: String(order.id),
     order_key: String(order.order_key),
   };
-  const appId = base44AppId();
+  const appId = base44AppId(opts.secrets);
   if (appId) metadata.base44_app_id = appId;
 
   const params = new URLSearchParams();
@@ -170,7 +180,7 @@ export async function createCardPayment(
     params.set(`payment_intent_data[metadata][${key}]`, value);
   }
 
-  const session = await stripeCall("/checkout/sessions", params);
+  const session = await stripeCall(opts.secrets, "/checkout/sessions", params);
   if (!session?.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
   return { url: session.url, reference: String(session.id) };
 }
@@ -180,8 +190,8 @@ export async function createCardPayment(
  * caller. Runs on the customer-return page, the webhook's unverified path and
  * the admin's "Check payment" button.
  */
-export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
-  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(reference)}`);
+export async function checkCardPaymentPaid(_sr: any, order: any, reference: string, secrets: SecretStore): Promise<boolean> {
+  const session = await stripeCall(secrets, `/checkout/sessions/${encodeURIComponent(reference)}`);
   // The payment must be for THIS order — stops a reference to some other
   // (genuinely paid) session being replayed against a different order.
   return session?.payment_status === "paid" && session?.metadata?.order_id === String(order.id);
@@ -196,20 +206,21 @@ export async function refundCardPayment(_sr: any, _order: any, opts: {
   amount: number;
   currency: string;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string }> {
   // The stored reference is the Checkout Session; the refundable object is the
   // payment intent behind it, which only exists once the session was paid.
-  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(opts.reference)}`);
+  const session = await stripeCall(opts.secrets, `/checkout/sessions/${encodeURIComponent(opts.reference)}`);
   if (!session?.payment_intent) {
     throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
   }
   const params = new URLSearchParams();
   params.set("payment_intent", String(session.payment_intent));
   params.set("amount", String(minorUnits(opts.amount, opts.currency)));
-  const appId = base44AppId();
+  const appId = base44AppId(opts.secrets);
   if (appId) params.set("metadata[base44_app_id]", appId);
 
-  const refund = await stripeCall("/refunds", params);
+  const refund = await stripeCall(opts.secrets, "/refunds", params);
   return { refund_id: String(refund.id) };
 }
 
@@ -242,7 +253,7 @@ export interface CardWebhookEvent {
  * null for anything that isn't a payment event for one of this store's orders;
  * the premade function answers 200 so Stripe stops retrying.
  */
-export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
+export async function parseWebhook(_req: Request, payload: string, secrets: SecretStore): Promise<CardWebhookEvent | null> {
   let event: any;
   try { event = JSON.parse(payload); } catch { return null; }
   const metadata = event?.data?.object?.metadata;

package/base44/shared/commerce/card-payment.ts

@@ -34,14 +34,25 @@
  * Until implemented, the Credit Card checkout option answers
  * 503 `no_card_payment_provider`.
  *
- * Credentials belong in Base44 secrets (`secrets.get("...")` from
- * `base44:runtime`) — never in an entity, never in the code, never from the
- * client. When one is missing, log which one and answer the caller with the
+ * Credentials belong in Base44 secrets — but this file never reaches for them
+ * itself. Every function below is handed a `SecretStore` by the function that
+ * called it, the one layer that may `import { secrets } from "base44:runtime"`.
+ * Neither that import nor `Deno.env` belongs here: `shared/` is reachable by
+ * the client bundler, so either one fails the storefront's build and pins this
+ * file to a single runtime. Never an entity, never the code, never the client. When one is missing, log which one and answer the caller with the
  * flat 503 below: the storefront must not learn the names of the app's
  * secrets.
  */
 import { HttpError } from "./auth.ts";
 
+/**
+ * The app's secret store, handed in per call by the function layer:
+ * `import { secrets } from "base44:runtime"` there, never here.
+ */
+export interface SecretStore {
+  get(name: string): unknown;
+}
+
 /** A hosted payment page for one order. */
 export interface CardPaymentPage {
   /** Where the customer goes to pay. */
@@ -65,7 +76,7 @@ export interface CardPaymentPage {
 export async function createCardPayment(
   _sr: any,
   _order: any,
-  _opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+  _opts: { successUrl: string; cancelUrl: string; customerEmail?: string; secrets: SecretStore },
 ): Promise<CardPaymentPage> {
   throw new HttpError(
     503,
@@ -80,7 +91,7 @@ export async function createCardPayment(
  * a claim from the client. Called by the customer-return page, the webhook's
  * unsigned path, and the admin's "Check payment" button.
  */
-export async function checkCardPaymentPaid(_sr: any, _order: any, _reference: string): Promise<boolean> {
+export async function checkCardPaymentPaid(_sr: any, _order: any, _reference: string, _secrets: SecretStore): Promise<boolean> {
   return false;
 }
 
@@ -95,6 +106,7 @@ export async function refundCardPayment(_sr: any, _order: any, _opts: {
   amount: number;
   currency: string;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string }> {
   throw new HttpError(
     501,
@@ -138,7 +150,7 @@ export interface CardWebhookEvent {
  * aren't about a payment for one of this store's orders (answered 200 so the
  * provider doesn't retry).
  */
-export async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
+export async function parseWebhook(_req: Request, _payload: string, _secrets: SecretStore): Promise<CardWebhookEvent | null> {
   throw new HttpError(
     400,
     "This store's payment webhook is not implemented.",

package/base44/shared/commerce/payments.ts

@@ -19,7 +19,7 @@
 import { HttpError } from "./auth.ts";
 import { round2 } from "./money.ts";
 import { transitionOrder } from "./orders.ts";
-import { checkCardPaymentPaid, createCardPayment, refundCardPayment } from "./card-payment.ts";
+import { checkCardPaymentPaid, createCardPayment, refundCardPayment, type SecretStore } from "./card-payment.ts";
 
 /** The one `commerce.PaymentGateway` slug that pays online; all others are manual. */
 export const CARD_GATEWAY_SLUG = "card";
@@ -182,6 +182,8 @@ export async function startCardPayment(sr: any, order: any, opts: {
   successUrl: string;
   cancelUrl: string;
   customerEmail?: string;
+  // Handed down from the function entry — shared/ may not read secrets itself.
+  secrets: SecretStore;
 }): Promise<{ url: string; reference: string }> {
   if (isOrderPaid(order)) {
     throw new HttpError(409, "This order is already paid.", "already_paid");
@@ -210,12 +212,13 @@ export async function confirmCardPayment(sr: any, order: any, opts: {
   settings?: Record<string, any>;
   actor?: string;
   trustedPaid?: boolean;
-} = {}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
+  secrets: SecretStore;
+}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
   if (isOrderPaid(order)) return { paid: true, already_confirmed: true, order };
 
   const reference = opts.reference || orderMeta(order, REFERENCE_META_KEY) || String(order?.transaction_id ?? "");
   const paid = opts.trustedPaid === true ||
-    (reference ? await checkCardPaymentPaid(sr, order, reference) : false);
+    (reference ? await checkCardPaymentPaid(sr, order, reference, opts.secrets) : false);
   if (!paid) return { paid: false, already_confirmed: false, order };
 
   if (reference) {
@@ -242,10 +245,12 @@ export async function confirmCardPayment(sr: any, order: any, opts: {
 export async function refundCardOrder(sr: any, order: any, opts: {
   amount: number;
   reason?: string;
+  secrets: SecretStore;
 }): Promise<{ refund_id: string } | null> {
   const reference = order?.transaction_id || orderMeta(order, REFERENCE_META_KEY);
   if (!isCardGateway(order?.payment_method) || !reference) return null;
   return await refundCardPayment(sr, order, {
+    secrets: opts.secrets,
     reference,
     amount: round2(opts.amount),
     currency: String(order.currency || "USD"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -123,7 +123,7 @@ batch (above).
 | Topic | Open when | Size |
 |---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 37K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 38K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |

package/skills/commerce/install/02-storefront.md

@@ -25,6 +25,8 @@ One split decides everything here: **the logic is premade, the UI never is.** Th
 
 **One import path: `@/commerce/storefront`.** Each section opens with its page's exact import line — copy it verbatim, then delete unused names. Everything a page needs is re-exported there, so a React page never imports `@/commerce/utils` directly. `useStoreInfo` is the name most often left out.
 
+⚑ **Only some of what lives there is importable.** Hooks and helpers (`useProduct`, `useCart`, `productImages`, …) are named exports; a few operations exist **only on the client** `useStorefront()` returns — `submitReview`, `getProductReviews`, `listProducts`, `getProduct`, `applyCoupon`, `chooseShippingMethod`, `completeReturn`. Importing one by name throws `does not provide an export named …` and blanks the whole app: `const c = useStorefront(); await c.submitReview(…)`.
+
 ## Setup — once
 
 Nearly every store has shared chrome, so **start from a pathless layout route** — it also keeps the admin outside the storefront's provider:
@@ -317,7 +319,7 @@ function CheckoutForm() {
 
 **`<AddressFields>` is the one shipped component — use it, never hand-roll the address form.** It owns what hand-rolled forms get wrong: the state/province field appears with the right options once a country is picked (shipping rates and taxes match on country *plus* state, so a form without it mis-prices US/CA/AU orders with no error anywhere), every field keeps its `autoComplete` token (what makes browser autofill work), required marks arm on first blur, and the server's "we don't ship there" lands on the country field. `which="shipping"` renders null until `shipToDifferent` is on — the deliver-elsewhere checkbox itself is yours, wired to `c.shipToDifferent` / `c.setShipToDifferent`.
 
-It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (false), `includePhone` (true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}`, `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is missing, for your own per-field marks.
+⚑ **Pass `classes.control`** — an unstyled `<input>` still reads as deliberate; a `<select>` does not, so skipping this one prop leaves the checkout looking broken on exactly one field. It ships **no CSS** bar a `max-width:100%` cap on the selects (an unstyled checkout must not scroll sideways): every element carries `data-part` (`address-fields`, `field`, `label`, `control`, `required`, `error`) plus `data-key` (the field) and `data-span` (1 or 2 — the field's natural width in a two-column grid), so style it in your `index.css` via `[data-part]` selectors or pass `className`/`classes={{ field, label, control, error }}`. ⚑ **`data-part` sits on the element, not a wrapper** — `select[data-part="control"]`, never `[data-part="control"] input`: the descendant form matches nothing and ships the form unstyled. Props: `includeCompany` (false), `includePhone` (true), `omit={["…"]}`, `labels={{ postcode: "ZIP code" }}`, `selectPlaceholder`, and two escape hatches — `inputRender` swaps the control only (spread the handed `dom` props onto your input), `fieldRender` replaces the whole labeled block. `c.missingBillingFields` stays the live list of what is missing, for your own per-field marks.
 
 ⚑ **The `stage === "submitted"` guard goes above the empty-cart branch** — placing an order clears the cart before the browser navigates, and without the guard the page flashes an empty bag over a just-placed order.
 

package/skills/commerce/install/03-data.md

@@ -5,7 +5,7 @@ skip_when: "commerce/seed-store has already returned success for this store and
 forget_when: "The seed response is received and recorded (slugs + warnings), and the checklist at the bottom passes."
 carry_forward:
   - "Product slugs come from the seed response's catalog.products[] — link pages by slug, never by a client-side map."
-  - "Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer."
+  - "Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer. Shipping the Stripe file is not a Stripe connection; only the user can authorise that."
   - "Turning card payments on or off later is one more seed call: { payment_methods: [\"offline\", \"card\"] }."
   - "Seed-time `locations` is THE shipping path; patching commerce.ShippingTaxLocation is the day-2 route."
 ---
@@ -131,7 +131,7 @@ Online card payments are **off by default**: the seeded store takes the manual `
 | Paid another way (transfer, COD, invoice, pickup) | nothing to do — the default is exactly this |
 | Payments not mentioned | leave the default, **state it at handover** |
 
-*Cards only:* **if it is Stripe the code is already written** — copy `base44/shared/commerce/card-payment.stripe.ts` over `base44/shared/commerce/card-payment.ts` **whole** (`fs.copyFileSync`; a partial edit breaks every function's deploy), then enable via `payment_methods`. Nothing needs filling in. Any other provider: [`../references/online-payments.md`](../references/online-payments.md).
+*Cards only:* **if it is Stripe the code is already written** — copy `base44/shared/commerce/card-payment.stripe.ts` over `base44/shared/commerce/card-payment.ts` **whole** (`fs.copyFileSync`; a partial edit breaks every function's deploy), then enable via `payment_methods`. Nothing needs filling in. ⚑ **That is the code, not a connection** — the app is not connected to Stripe until the user authorises it and its secret key reaches the app's secrets, which only they can do. Say the card path is *ready* and ask them to connect Stripe; never report it as connected, and never ask for a key in chat. Any other provider: [`../references/online-payments.md`](../references/online-payments.md).
 
 ## Done — forget this file
 

package/src/commerce/storefront/pickers.jsx

@@ -125,6 +125,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *   value      the selected slug ("" while none)
  *   select     (slug) => void
  *   selected   the selected gateway entry, or null
+ *   mustChoose more than one gateway → render them as a picker
  *   single     exactly one gateway — already selected
  *   hint       { code: "none_available", severity, serverMessage } | null —
  *              no gateways at all: say checkout is unavailable, in your words
@@ -160,6 +161,10 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
     value,
     select,
     selected: decorated.find((g) => g.selected) ?? null,
+    // Symmetrical with ShippingMethodPicker: a checkout that gates its radios
+    // on `mustChoose` renders NOTHING when the field is missing, and a payment
+    // picker that renders nothing is a checkout no one can complete.
+    mustChoose: gateways.length > 1,
     single: single ?? (gateways.length === 1), // fallback: a hand-built checkout object
     hint,
   });

package/src/commerce/utils/storefront.js

@@ -65,6 +65,15 @@ export function storefrontErrorMessage(e) {
 }
 
 export function createStorefront(base44, { storageKey = "cart_token", storage } = {}) {
+  // Fail at construction, not four calls later. Without this the first symptom
+  // is "Cannot read properties of undefined (reading 'functions')" thrown from
+  // inside a cart call, which reads as a kit bug rather than a missing prop.
+  if (!base44 || typeof base44.functions?.invoke !== "function") {
+    throw new Error(
+      "StorefrontProvider requires the base44 client: <StorefrontProvider base44={base44}> " +
+      '(import { base44 } from "@/api/base44Client").',
+    );
+  }
   const bag = storage ?? (typeof localStorage !== "undefined" ? localStorage : null);
 
   // Every function returns the envelope { success, data }; with the SDK the