@base44/app-plugin-commerce 0.1.15 → 0.1.17

package/skills/commerce/references/online-payments.md

@@ -4,6 +4,8 @@ The store ships with a **Credit card** checkout option (`commerce.PaymentGateway
 
 What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
 
+**Does this store even need a provider?** Card payments are **optional and off by default**: `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code at all) and leaves the **`card`** gateway disabled. **Enable cards only if this file is implemented, or is about to be in the same stretch of work** — an enabled card option with no provider behind it answers `503 no_card_payment_provider` at checkout, so the gateway switch (seed `payment_methods`) and this file always move together. [`post-installation.md` §4.1](../post-installation.md#41-off-by-default--enable-only-with-a-provider-wired) has the rule and the timing (short version: a fine thing to add, but at the end of a build, not the start — nothing depends on it).
+
 | Function | Backs |
 |---|---|
 | `createCardPayment` | checkout + payment links: make a hosted payment page for `order.total`, return `{ url, reference }`, and attach `order.id`/`order.order_key` to the payment's metadata |
@@ -11,9 +13,9 @@ What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal
 | `refundCardPayment` | admin refunds through the provider (optional — leave the stub to keep refunds manual) |
 | `parseWebhook` | webhook validation: name the order a provider event is about (from the echoed metadata), and vouch `paid: true` **only** after verifying the request signature over the raw body bytes |
 
-**Wiring Stripe? Don't start here** — [`post-installation.md` §2.2](../post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference) has the complete implementation of all four functions to paste in, plus the secret and webhook-endpoint steps. This reference is for other providers and for webhook customization.
+**Wiring Stripe? Don't start here** — [`post-installation.md` §4](../post-installation.md#42-wiring-a-provider--one-file) has the complete implementation of all four functions to paste in, plus the secret and webhook-endpoint steps. This reference is for other providers and for webhook customization.
 
-Until the file is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
+The card option ships **disabled**, so on a default store none of this is customer-visible. Where the gateway has been enabled without the file, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods) — implement the file, or switch the option back off in Settings → Payments. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
 
 ## How the premade flow works
 
@@ -28,7 +30,7 @@ Until the file is implemented, picking Credit card at checkout answers `503 no_c
 
 - **Replace `card-payment.ts` whole** — one write of the full new file, never a `find_replace` into the shipped stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"); the fix is always to rewrite the file whole.
 - **Credentials** come from backend secrets/env (`Deno.env.get(...)`) — never from an entity, never from the client. On Base44, env vars are injected at deploy time; after adding a secret, redeploy the backend functions so they can see it.
-- **Which methods the store offers is seed data** — `commerce/seed-store`'s `payment_methods` (e.g. `["card"]`) enables the listed gateways and disables the rest; don't edit `commerce.PaymentGateway` records to turn methods on or off.
+- **Which methods the store offers is seed data** — `commerce/seed-store`'s `payment_methods` (e.g. `["offline", "card"]`) enables the listed gateways and disables the rest; don't edit `commerce.PaymentGateway` records to turn methods on or off. Omitting it means offline-only, cards off — so **enabling the card gateway is part of wiring a provider**, not a separate concern: a correct `card-payment.ts` is invisible at checkout until that call runs, and that call without the file gives customers a `503`.
 - **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. It should also check the payment **names this order** (compare the payment's metadata `order_id` to `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
 - **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` + `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
 - **`parseWebhook` never trusts a raw body.** Return `paid: false` (the verify-via-API nudge) unless you verified the provider's signature over the raw payload bytes; set `reference` only from a verified event, otherwise leave it unset so the premade flow uses the reference stored on the order at checkout.

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -207,7 +207,7 @@ export default function PaymentsSettings() {
               {/* The "card" option redirects to a provider-hosted payment page.
                   Wiring a provider means implementing the four functions in
                   shared/commerce/card-payment.ts (Stripe: paste-in in
-                  .agents/skills/commerce/post-installation.md §2.2; the payment
+                  .agents/skills/commerce/post-installation.md §4; the payment
                   webhook is premade). Until then, picking it at checkout answers
                   503 no_card_payment_provider. Deliberately not shown to the
                   store operator — it's developer guidance, not store

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -0,0 +1,216 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { createStorefront, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+
+/**
+ * StorefrontProvider — one client, one store-info cache, ONE shared cart.
+ *
+ * Mount it once, above every storefront page (product list, product page,
+ * cart, checkout, order-received):
+ *
+ *   import { base44 } from "@/api/base44Client";
+ *   <StorefrontProvider base44={base44}> ... </StorefrontProvider>
+ *
+ * or, if other modules also need the raw client, create it once and share it:
+ *
+ *   // src/lib/storefront.js
+ *   import { createStorefront } from "@/commerce/utils";
+ *   import { base44 } from "@/api/base44Client";
+ *   export const store = createStorefront(base44);
+ *
+ *   <StorefrontProvider store={store}> ... </StorefrontProvider>
+ *
+ * What lives here (and why it must not be duplicated per page):
+ * - the `createStorefront` instance — it owns the cart_token lifecycle;
+ * - store info — payment_gateways, currency, countries/currencies come from
+ *   `get-store-info` ONLY (never off a cart view), cached for the session;
+ * - the cart view — every mutation from any component funnels through one
+ *   serialized queue, so a slow response can never clobber a newer cart, and
+ *   a header badge, a cart drawer and the checkout all re-render from the
+ *   same state.
+ */
+
+const StorefrontContext = createContext(null);
+
+export function StorefrontProvider({ base44, store, children }) {
+  const client = useMemo(
+    () => store ?? createStorefront(base44),
+    [store, base44],
+  );
+
+  // ── store info (cached by the client; mirrored into state once) ─────────
+  const [info, setInfo] = useState(null);
+  const [infoError, setInfoError] = useState(null);
+  useEffect(() => {
+    let mounted = true;
+    client.getStoreInfo().then(
+      (i) => mounted && setInfo(i),
+      (e) => mounted && setInfoError(e),
+    );
+    return () => {
+      mounted = false;
+    };
+  }, [client]);
+
+  // ── shared cart state ────────────────────────────────────────────────────
+  // undefined = still loading, null = no cart yet, object = the priced view.
+  const [cart, setCart] = useState(undefined);
+  const [cartError, setCartError] = useState(null);
+  const queue = useRef(Promise.resolve());
+
+  /**
+   * Run one cart call at a time, in order, and publish its returned view.
+   * Serializing is what keeps rapid quantity clicks (or an address sync racing
+   * an add-to-cart) from applying responses out of order.
+   */
+  const runCart = useCallback((fn) => {
+    const next = queue.current.catch(() => {}).then(fn);
+    queue.current = next;
+    return next.then((view) => {
+      setCart(view ?? null);
+      setCartError(null);
+      return view ?? null;
+    });
+  }, []);
+
+  /** Forget the cart locally (used after checkout consumes it). */
+  const clearCart = useCallback(() => setCart(null), []);
+
+  useEffect(() => {
+    runCart(() => client.getCart()).catch((e) => {
+      setCart(null);
+      setCartError(e);
+    });
+  }, [client, runCart]);
+
+  const value = useMemo(
+    () => ({ client, info, infoError, cart, cartError, runCart, clearCart }),
+    [client, info, infoError, cart, cartError, runCart, clearCart],
+  );
+  return <StorefrontContext.Provider value={value}>{children}</StorefrontContext.Provider>;
+}
+
+/** Advanced escape hatch: the raw provider state. Prefer the hooks below. */
+export function useStorefrontState() {
+  const ctx = useContext(StorefrontContext);
+  if (!ctx) {
+    throw new Error(
+      "Storefront hooks need a <StorefrontProvider> above them — mount it once around your storefront routes.",
+    );
+  }
+  return ctx;
+}
+
+/** The shared `createStorefront` client — catalog calls go straight through it. */
+export function useStorefront() {
+  return useStorefrontState().client;
+}
+
+/**
+ * Store info: `{ info, settings, paymentGateways, countries, currencies,
+ * loading, error }`. `info` is null while loading. This hook is the ONLY
+ * place to read payment gateways and currency from.
+ */
+export function useStoreInfo() {
+  const { info, infoError } = useStorefrontState();
+  return {
+    info,
+    settings: info?.settings ?? null,
+    paymentGateways: info?.payment_gateways ?? null,
+    countries: info?.countries ?? null,
+    currencies: info?.currencies ?? null,
+    loading: !info && !infoError,
+    error: infoError,
+  };
+}
+
+/**
+ * `(amount) => "€19.99"` in the store's currency, per the viewer's locale.
+ * Falls back to a plain number while store info is still loading.
+ */
+export function useFormatMoney() {
+  const { info } = useStorefrontState();
+  const currency = info?.settings?.currency;
+  return useCallback(
+    (amount) => {
+      const n = Number(amount) || 0;
+      if (!currency) return n.toFixed(2);
+      try {
+        return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(n);
+      } catch {
+        return `${n.toFixed(2)} ${currency}`;
+      }
+    },
+    [currency],
+  );
+}
+
+/**
+ * The shared cart — state plus every cart mutation. All consumers see the
+ * same view; every action resolves to the fresh priced cart it published.
+ *
+ *   const { cart, loading, itemCount, addItem, updateItem, removeItem,
+ *           applyCoupon, removeCoupon, refresh } = useCart();
+ *
+ * - `cart` is `null` until something is added (render an empty state).
+ * - `addItem(view.addToCart, quantity)` — pass the resolved `addToCart` from
+ *   `resolveSelection`; a product with attributes is rejected without its
+ *   `variation_id` (`400 variation_required`).
+ * - `applyCoupon(code)` resolves to `{ ok, cart }` or `{ ok: false, code,
+ *   message }` — an invalid code is expected flow, not an exception.
+ * - Render `cart.coupon_notices` / `cart.removed_items` when present: they
+ *   say what auto-dropped and why.
+ */
+export function useCart() {
+  const { client, cart, cartError, runCart } = useStorefrontState();
+
+  const refresh = useCallback(() => runCart(() => client.getCart()), [client, runCart]);
+  const addItem = useCallback(
+    (item, quantity = 1) => runCart(() => client.addItem({ quantity, ...item })),
+    [client, runCart],
+  );
+  const updateItem = useCallback(
+    (itemKey, quantity) => runCart(() => client.updateItem(itemKey, quantity)),
+    [client, runCart],
+  );
+  const removeItem = useCallback(
+    (itemKey) => runCart(() => client.removeItem(itemKey)),
+    [client, runCart],
+  );
+  const applyCoupon = useCallback(
+    async (code) => {
+      try {
+        return { ok: true, cart: await runCart(() => client.applyCoupon(code)) };
+      } catch (e) {
+        return { ok: false, code: storefrontErrorCode(e), message: storefrontErrorMessage(e) };
+      }
+    },
+    [client, runCart],
+  );
+  const removeCoupon = useCallback(
+    (code) => runCart(() => client.removeCoupon(code)),
+    [client, runCart],
+  );
+
+  const items = cart?.items ?? [];
+  return {
+    cart: cart ?? null,
+    loading: cart === undefined,
+    error: cartError,
+    itemCount: items.reduce((n, i) => n + (i.quantity || 0), 0),
+    isEmpty: !items.length,
+    refresh,
+    addItem,
+    updateItem,
+    removeItem,
+    applyCoupon,
+    removeCoupon,
+  };
+}

package/src/commerce/storefront/address.js

@@ -0,0 +1,70 @@
+/**
+ * Address helpers for the guided checkout — framework-free (no React).
+ *
+ * Two different "complete" questions live here, and they are not the same:
+ *
+ * - `missingBillingFields` — what `place-order` will reject
+ *   (`400 billing_incomplete`). The backend requires first_name, last_name,
+ *   address_1, city, country and email on `billing`.
+ * - `isShippingAddressComplete` — when the address is filled in enough to be
+ *   worth sending to `set-shipping-address`. Shipping rates and taxes match on
+ *   **country + state only** (Shipping & Tax Location regions are
+ *   continent/country/state — no postcode or city filters), so technically a
+ *   country is enough to price the cart. Requiring the city too is the signal
+ *   that the customer has actually finished typing the address block rather
+ *   than being mid-form — that is what makes the recalculation *guided*
+ *   instead of a request per keystroke.
+ */
+
+/** The billing fields `place-order` rejects the order without. */
+export const REQUIRED_BILLING_FIELDS = [
+  "first_name",
+  "last_name",
+  "address_1",
+  "city",
+  "country",
+  "email",
+];
+
+/**
+ * The required billing fields that are still blank.
+ *
+ * @param {object} billing
+ * @param {string[]} [required]
+ * @returns {string[]} field names, in `required` order
+ */
+export function missingBillingFields(billing, required = REQUIRED_BILLING_FIELDS) {
+  return required.filter((f) => !String(billing?.[f] ?? "").trim());
+}
+
+/**
+ * The slice of an address that `set-shipping-address` stores and the pricing
+ * engine reads — exactly `{ country, state, postcode, city }`, trimmed. Two
+ * addresses with the same slice price identically, so this is also the
+ * "did the address change in a way that matters?" comparison key.
+ *
+ * @param {object} address
+ * @returns {{country: string, state: string, postcode: string, city: string}}
+ */
+export function shippingSlice(address) {
+  return {
+    country: String(address?.country ?? "").trim(),
+    state: String(address?.state ?? "").trim(),
+    postcode: String(address?.postcode ?? "").trim(),
+    city: String(address?.city ?? "").trim(),
+  };
+}
+
+/**
+ * Is the address filled in enough to (re)calculate shipping and tax?
+ * Default rule: country + city present (see the header for why city).
+ * `useCheckout` accepts a custom predicate via its `addressComplete` option
+ * when a store wants a stricter or looser gate.
+ *
+ * @param {object} address
+ * @returns {boolean}
+ */
+export function isShippingAddressComplete(address) {
+  const s = shippingSlice(address);
+  return Boolean(s.country && s.city);
+}

package/src/commerce/storefront/index.js

@@ -0,0 +1,51 @@
+/**
+ * Storefront React layer — hooks + headless helpers for the cart, checkout
+ * and order-received parts of the shopfront you build. Ships with the Base44
+ * Commerce Template next to the framework-free `@/commerce/utils` (which it
+ * builds on); needs React and nothing else. NO visual components ship here —
+ * every pixel stays yours. The hooks own the contracts that are easy to get
+ * subtly wrong; you own the markup.
+ *
+ * Setup (once, above every storefront route):
+ *
+ *   import { StorefrontProvider } from "@/commerce/storefront";
+ *   import { base44 } from "@/api/base44Client";
+ *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
+ *
+ * - `StorefrontProvider` / `useStorefront` / `useStoreInfo` / `useFormatMoney`
+ *     — one client, cached store info (the ONLY source of payment gateways,
+ *     currency, countries), money formatting in the store's currency.
+ * - `useCart` — the shared cart: state + every mutation, serialized so
+ *     responses never apply out of order; a header badge, a cart drawer and
+ *     the checkout all see the same view.
+ * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
+ *     checkout: address form state with automatic debounced shipping/tax
+ *     recalculation once the address is complete, shipping-method choice,
+ *     payment-method choice, a `canPlaceOrder` gate with named blockers, and
+ *     `placeOrder` with the online-payment redirect handled.
+ * - `ShippingMethodPicker` / `PaymentMethodPicker` — headless (render-prop)
+ *     wrappers over the two choices that are store data, never hardcoded.
+ * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
+ * - `address.js` — framework-free address-completeness rules (also exported).
+ *
+ * Catalog calls (product list, product page) intentionally stay thin — use
+ * `useStorefront()` for the client plus the variant helpers from
+ * `@/commerce/utils`; those views are where the design freedom lives.
+ */
+export {
+  StorefrontProvider,
+  useStorefrontState,
+  useStorefront,
+  useStoreInfo,
+  useFormatMoney,
+  useCart,
+} from "./StorefrontProvider";
+export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
+export { useOrderReturn } from "./useOrderReturn";
+export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
+export {
+  REQUIRED_BILLING_FIELDS,
+  missingBillingFields,
+  shippingSlice,
+  isShippingAddressComplete,
+} from "./address";

package/src/commerce/storefront/pickers.jsx

@@ -0,0 +1,90 @@
+import React from "react";
+import { useCheckoutContextOptional } from "./useCheckout";
+
+/**
+ * Headless pickers for the two checkout choices that are store data, never
+ * hardcoded. They render NOTHING themselves — your render-prop child is the
+ * whole UI — but they encode the branching every checkout must do, so a page
+ * can't skip a `shipping_status` state or invent a payment method.
+ *
+ * Both read the nearest <CheckoutProvider>, or take an explicit `checkout`
+ * prop when you called `useCheckout` yourself.
+ */
+
+function resolveCheckout(name, prop, ctx) {
+  const checkout = prop ?? ctx;
+  if (!checkout) {
+    throw new Error(`<${name}> needs a <CheckoutProvider> above it, or a checkout prop.`);
+  }
+  return checkout;
+}
+
+/**
+ * Shipping options. Renders null for a virtual cart (`not_needed`) and while
+ * the cart is loading; otherwise calls `children` with:
+ *
+ *   {
+ *     status,        // "missing_address" | "choice_required" | "chosen" | "auto_selected"
+ *     methods,       // [{ id, title, cost }] — what this address is offered
+ *     chosen,        // the chosen/auto-selected entry (title + cost), or null
+ *     choose,        // (id) => Promise — call with a method's id on pick
+ *     mustChoose,    // status === "choice_required" → render methods as a picker
+ *     syncing,       // an address edit is being repriced — show a subtle busy state
+ *     addressError,  // { code, message } | null — "we don't ship there" belongs
+ *   }                //   on the address fields
+ *
+ * Render rules the child should follow: `missing_address` → say the options
+ * appear once the address is entered; `mustChoose` → a picker of `methods`;
+ * otherwise display `chosen.title` + its cost (never the raw id).
+ */
+export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
+  const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
+  const {
+    shippingStatus: status,
+    shippingMethods: methods,
+    chosenShippingMethod: chosen,
+    chooseShippingMethod: choose,
+    shippingSyncing: syncing,
+    addressError,
+  } = checkout;
+  if (!status || status === "not_needed") return null;
+  return children({
+    status,
+    methods,
+    chosen,
+    choose,
+    mustChoose: status === "choice_required",
+    syncing,
+    addressError,
+  });
+}
+
+/**
+ * Payment methods — every gateway the admin has ENABLED, from store info
+ * (their only source). Renders null while store info loads; otherwise calls
+ * `children` with:
+ *
+ *   {
+ *     gateways,   // [{ slug, title, description, online }] — admin-owned data
+ *     value,      // the selected slug ("" while none)
+ *     select,     // (slug) => void
+ *     selected,   // the selected gateway entry, or null
+ *     single,     // exactly one gateway — pre-selected; skip the picker but
+ *   }             //   still show its title so the customer knows how they pay
+ *
+ * Render rules: several gateways → a picker labeled with the admin's
+ * title/description; `single` → just display it; zero gateways → say checkout
+ * is unavailable instead of rendering a dead place-order button.
+ */
+export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
+  const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());
+  const { paymentMethods: gateways, paymentMethod: value, setPaymentMethod: select, selectedGateway: selected } = checkout;
+  if (!gateways) return null;
+  return children({
+    gateways,
+    value,
+    select,
+    selected,
+    single: gateways.length === 1,
+  });
+}