@base44/app-plugin-commerce 0.8.0 → 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.0",
+  "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:
@@ -197,9 +199,10 @@ Build your layout from — all optional, **not one component style**:
 - **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). ⚑ **Both shapes are exact** — entity-style names (`content`, `reviewer_name`) throw on submit and render blank in the list:
 
   ```jsx
+  const client = useStorefront();               // submitReview is a CLIENT METHOD, not a barrel export
   p.reviews                                     // { items, page, per_page, has_next }
   p.reviews.items[0]                            // { id, reviewer, review, rating, verified, created_date }
-  await submitReview({ product_id, review, rating, reviewer, email })   // NOT content/reviewer_name/reviewer_email
+  await client.submitReview({ product_id, review, rating, reviewer, email })   // NOT content/reviewer_name/reviewer_email
   ```
 
   Text or stars — either alone submits. ⚑ **The form renders for every visitor by default** (guests supply an email; hide it when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every auto-approving store — and refresh the list after, or the review doesn't appear. Codes, policies, moderation: [`../references/reviews.md`](../references/reviews.md).
@@ -316,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/skills/commerce/references/catalog-rendering.md

@@ -93,7 +93,7 @@ Both lists are inventories of what the data supports — **not a layout and not
 
 **Card:** image, name, `price.label`, a sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `productSpecs`). Link the whole card through; the layout is yours.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `submitReview` off `useStorefront()`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `useStorefront().submitReview`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
 
 **Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` plus an inferred `type` — `"numeric"` / `"duration"` (with `number` and `unit` split out), `"location"`, `"list"` (with `items`), `"text"` — so the rendering branch is already made for you: a weight can be a figure, a composition bars, a provenance a place. ⚑ **Never `.map()` the whole list into one grey label/value table**; design the two or three rows this catalog is judged on and let the rest fall through to a plain row. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey table ([`../install/02-storefront.md`](../install/02-storefront.md)); §5's rules govern selector *behaviour*, never its form.
 

package/skills/commerce/references/reviews.md

@@ -17,7 +17,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
 
 - **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
-- **`submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. ⚑ **One set of names, both directions** — the payload above, rows back as `{ id, reviewer, review, rating, verified, created_date }`. Not the entity's columns: a near-miss (`content`, `reviewer_name`, `reviewer_email`, …) throws client-side rather than being aliased, since the same wrong names would render the list blank too. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
+- **`useStorefront().submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. ⚑ **A client method, never a barrel export** — importing the name itself from `@/commerce/storefront` throws `does not provide an export named …` and the whole app renders blank. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. ⚑ **One set of names, both directions** — the payload above, rows back as `{ id, reviewer, review, rating, verified, created_date }`. Not the entity's columns: a near-miss (`content`, `reviewer_name`, `reviewer_email`, …) throws client-side rather than being aliased, since the same wrong names would render the list blank too. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 

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