@base44/app-plugin-commerce 0.8.1 → 0.8.2

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

@@ -39,7 +39,6 @@
  * `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";
 
 /** Stripe's REST API, called directly — no SDK to bundle in the function. */
@@ -63,8 +62,13 @@ export interface CardPaymentPage {
  * checkout instead of failing to boot every commerce function that imports it.
  */
 const secret = (name: string): string => {
+  // Deno.env, never `secrets` from "base44:runtime": that specifier resolves
+  // only in the Deno function runtime, and this file lives under shared/ where
+  // a client bundler can reach it — the static import fails the Vite build of
+  // the whole storefront. Base44 publishes app secrets into the function
+  // environment, so Deno.env.get reads the same values.
   try {
-    return String(secrets.get(name) ?? "");
+    return String(Deno.env.get(name) ?? "");
   } catch {
     return "";
   }
@@ -100,7 +104,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 = (): string => secret("BASE44_APP_ID");
 
 /**
  * One Stripe REST call. A body makes it a POST (form-encoded, with an

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

@@ -34,9 +34,11 @@
  * 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, read with `Deno.env.get("...")` —
+ * never in an entity, never in the code, never from the client. Do NOT import
+ * `secrets` from `base44:runtime` here: that specifier resolves only in the
+ * Deno function runtime, and a static import of it in this shared file fails
+ * the client bundle of the whole storefront. 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.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "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