@base44/app-plugin-commerce 0.10.5 → 0.10.6

package/base44/functions/commerce/seed-store/entry.ts

@@ -84,7 +84,10 @@ Deno.serve(async (req) => {
     const withSample = !!body.with_sample_data;
     const storeName = String(body.store_name ?? "").trim();
     const currencyCode = String(body.currency ?? "").trim().toUpperCase();
-    const currencyInfo = currencyCode ? CURRENCIES.find((c) => c.code === currencyCode) : undefined;
+    const currencyInfo = currencyCode
+      ? CURRENCIES.find((c) => c.code === currencyCode)
+        ?? (/^[A-Z]{3}$/.test(currencyCode) ? { code: currencyCode, name: currencyCode, symbol: currencyCode, decimals: 2 } : undefined)
+      : undefined;
     const WEIGHT_UNITS = ["kg", "g", "lbs", "oz"];
     const DIMENSION_UNITS = ["cm", "m", "mm", "in", "yd"];
     const weightUnit = String(body.weight_unit ?? "").trim().toLowerCase();
@@ -94,7 +97,7 @@ Deno.serve(async (req) => {
     //       or any write ──────────────────────────────────────────────────────
     const unitErrors: Array<{ path: string; error: string }> = [];
     if (currencyCode && !currencyInfo) {
-      unitErrors.push({ path: "currency", error: `"${currencyCode}" is not a known ISO currency code` });
+      unitErrors.push({ path: "currency", error: `"${currencyCode}" is not an ISO 4217 code — three letters, e.g. "EUR"` });
     }
     if (weightUnit && !WEIGHT_UNITS.includes(weightUnit)) {
       unitErrors.push({ path: "weight_unit", error: `must be one of: ${WEIGHT_UNITS.join(", ")}` });

package/base44/functions/commerce/seed-store/seed-catalog.ts

@@ -106,6 +106,12 @@ const ENUMS: Record<string, string[]> = {
   tax_status: ["taxable", "none"],
   discount_type: ["percent", "fixed_cart", "fixed_product"],
 };
+// What builds write for the coupon type before they read the enum.
+const DISCOUNT_TYPE_SYNONYMS: Record<string, string> = {
+  percentage: "percent", pct: "percent", percent_off: "percent",
+  fixed: "fixed_cart", flat: "fixed_cart", fixed_amount: "fixed_cart", amount: "fixed_cart", cart: "fixed_cart",
+  per_product: "fixed_product", product: "fixed_product",
+};
 
 const PRICE_KEYS = ["regular_price", "sale_price", "stock_quantity", "low_stock_amount", "weight"];
 
@@ -168,6 +174,10 @@ export function normalizeCatalogPayload(body: any): CatalogSpec | null {
     const path = `coupons[${i}]`;
     if (!c || typeof c !== "object") return err(path, "must be an object");
     if (!String(c.code ?? "").trim()) err(`${path}.code`, "is required");
+    if (typeof c.discount_type === "string") {
+      const k = c.discount_type.trim().toLowerCase();
+      c.discount_type = DISCOUNT_TYPE_SYNONYMS[k] ?? k;
+    }
     if (c.discount_type != null && !ENUMS.discount_type.includes(c.discount_type)) {
       err(`${path}.discount_type`, `must be one of: ${ENUMS.discount_type.join(", ")}`);
     }
@@ -355,7 +365,13 @@ function normalizeProduct(
   const name = String(spec.name ?? "").trim();
   if (!name) err(`${path}.name`, "is required");
 
+  // `brand` is what a merchant means by a "Brand" spec row; `on_sale` is derived from the sale window.
+  if (typeof spec.brand === "string" && spec.brand.trim()) {
+    const { brand, ...rest } = spec;
+    spec = { ...rest, meta_data: [...(Array.isArray(rest.meta_data) ? rest.meta_data : []), { key: "Brand", value: brand.trim() }] };
+  }
   for (const key of Object.keys(spec)) {
+    if (key === "on_sale") continue;
     if (!PRODUCT_KEYS.has(key)) err(`${path}.${key}`, "unknown key — not a product field the seeder accepts");
   }
   checkEnumsAndNumbers(spec, path, err);
@@ -500,6 +516,7 @@ function normalizeProduct(
   }
   if (fields.sku !== undefined) fields.sku = sku;
   fields.images = normalizeImages(spec.images, name, `${path}.images`, err);
+  if (fields.meta_data !== undefined) fields.meta_data = normalizeMetaData(fields.meta_data, `${path}.meta_data`, err);
 
   return {
     fields,
@@ -542,6 +559,25 @@ function strList(value: any, path: string, err: (p: string, e: string) => void):
 }
 
 /** `images` accepts plain URLs or { src, name?, alt? }; normalized to the entity shape. */
+// The entity field is string-typed. A number, boolean or list here is a value the seeder can
+// spell out — not a reason to roll the whole catalog back after every other write succeeded.
+function normalizeMetaData(value: any, path: string, err: (p: string, e: string) => void): any[] {
+  if (!Array.isArray(value)) {
+    err(path, "must be an array of { key, value } rows");
+    return [];
+  }
+  const rows: any[] = [];
+  value.forEach((row, i) => {
+    if (!row || typeof row !== "object") return err(`${path}[${i}]`, "must be { key, value }");
+    const key = String(row.key ?? "").trim();
+    if (!key) return err(`${path}[${i}].key`, "is required");
+    const v = row.value;
+    if (v == null || v === "") return;
+    rows.push({ key, value: Array.isArray(v) ? v.map(String).join(", ") : typeof v === "object" ? JSON.stringify(v) : String(v) });
+  });
+  return rows;
+}
+
 function normalizeImages(value: any, productName: string, path: string, err: (p: string, e: string) => void): any[] {
   if (value == null) return [];
   if (!Array.isArray(value)) {

package/base44/shared/commerce/data/currencies.ts

@@ -43,4 +43,38 @@ export const CURRENCIES: CurrencyInfo[] = [
   { code: "MYR", name: "Malaysian Ringgit", symbol: "RM", decimals: 2 },
   { code: "IDR", name: "Indonesian Rupiah", symbol: "Rp", decimals: 0 },
   { code: "VND", name: "Vietnamese Dong", symbol: "₫", decimals: 0 },
+  { code: "NGN", name: "Nigerian Naira", symbol: "₦", decimals: 2 },
+  { code: "KES", name: "Kenyan Shilling", symbol: "KSh", decimals: 2 },
+  { code: "GHS", name: "Ghanaian Cedi", symbol: "GH₵", decimals: 2 },
+  { code: "PKR", name: "Pakistani Rupee", symbol: "₨", decimals: 2 },
+  { code: "BDT", name: "Bangladeshi Taka", symbol: "৳", decimals: 2 },
+  { code: "NPR", name: "Nepalese Rupee", symbol: "रू", decimals: 2 },
+  { code: "LKR", name: "Sri Lankan Rupee", symbol: "Rs", decimals: 2 },
+  { code: "EGP", name: "Egyptian Pound", symbol: "E£", decimals: 2 },
+  { code: "MAD", name: "Moroccan Dirham", symbol: "MAD", decimals: 2 },
+  { code: "DZD", name: "Algerian Dinar", symbol: "DA", decimals: 2 },
+  { code: "TND", name: "Tunisian Dinar", symbol: "DT", decimals: 3 },
+  { code: "SAR", name: "Saudi Riyal", symbol: "﷼", decimals: 2 },
+  { code: "QAR", name: "Qatari Riyal", symbol: "QR", decimals: 2 },
+  { code: "KWD", name: "Kuwaiti Dinar", symbol: "KD", decimals: 3 },
+  { code: "BHD", name: "Bahraini Dinar", symbol: "BD", decimals: 3 },
+  { code: "OMR", name: "Omani Rial", symbol: "OMR", decimals: 3 },
+  { code: "JOD", name: "Jordanian Dinar", symbol: "JD", decimals: 3 },
+  { code: "IQD", name: "Iraqi Dinar", symbol: "IQD", decimals: 3 },
+  { code: "ARS", name: "Argentine Peso", symbol: "$", decimals: 2 },
+  { code: "COP", name: "Colombian Peso", symbol: "$", decimals: 2 },
+  { code: "PEN", name: "Peruvian Sol", symbol: "S/", decimals: 2 },
+  { code: "CLP", name: "Chilean Peso", symbol: "$", decimals: 0 },
+  { code: "UAH", name: "Ukrainian Hryvnia", symbol: "₴", decimals: 2 },
+  { code: "KZT", name: "Kazakhstani Tenge", symbol: "₸", decimals: 2 },
+  { code: "UZS", name: "Uzbekistani Som", symbol: "so'm", decimals: 2 },
+  { code: "KGS", name: "Kyrgyzstani Som", symbol: "с", decimals: 2 },
+  { code: "AZN", name: "Azerbaijani Manat", symbol: "₼", decimals: 2 },
+  { code: "GEL", name: "Georgian Lari", symbol: "₾", decimals: 2 },
+  { code: "ETB", name: "Ethiopian Birr", symbol: "Br", decimals: 2 },
+  { code: "TZS", name: "Tanzanian Shilling", symbol: "TSh", decimals: 2 },
+  { code: "UGX", name: "Ugandan Shilling", symbol: "USh", decimals: 0 },
+  { code: "RWF", name: "Rwandan Franc", symbol: "FRw", decimals: 0 },
+  { code: "XOF", name: "West African CFA Franc", symbol: "CFA", decimals: 0 },
+  { code: "XAF", name: "Central African CFA Franc", symbol: "FCFA", decimals: 0 },
 ];

package/package.json

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

@@ -114,7 +114,7 @@ Open a file when its work starts — not while planning.
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`installation/install.md`](./installation/install.md) | installing — all three stages: admin mount, storefront pages, then the seed payload | 52K |
+| [`installation/install.md`](./installation/install.md) | installing — all three stages: admin mount, storefront pages, then the seed payload | 53K |
 | [`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 |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond stage 03's recipe, taxes, day-2 edits | 8K |

package/skills/commerce/installation/install.md

@@ -51,7 +51,7 @@ lines and treat that stage as done — but keep reading this file, not re-fetchi
 
 Image generation is the slowest step and nothing depends on it until seed time; the storefront doesn't wait on live data either.
 
-1. **Start image generation first** — every product image, before anything else.
+1. **Start image generation first — in the same message as the install call**: one `generate_image` per product, before reading anything.
    ⚑ **The result already carries the real `image_url`** alongside a `placeholder_url`
    — use `image_url` and move on. Nothing is pending, there is nothing to poll, and a
    backend function calling `Core.GenerateImage` to "fetch the real URLs" is pure waste:
@@ -62,8 +62,10 @@ Image generation is the slowest step and nothing depends on it until seed time;
 2. **Mount the admin (below) and build the storefront** while images render. Every
    request and response shape the pages build against is written out in
    [stage 02 below](#02--storefront), so they are written from the docs,
-   not from live data.
-3. **Seed the moment the image URLs are back** — one `commerce/seed-store` call ([stage 03 below](#03--store-data)). Its writes run in parallel, so the call usually takes a few seconds — but don't idle on it either.
+   not from live data. Write `src/App.jsx` **last**, once every page it imports exists — an
+   earlier write warns `unresolved import` and buys a fix cycle. The platform validates the
+   build after every write; never run `npx vite build` or `npm run build`.
+3. **Seed the moment the image URLs are back — in the same message as a write batch**, never as a message of its own: one `commerce/seed-store` call ([stage 03 below](#03--store-data)); it runs alongside the writes and takes a few seconds — don't idle on it.
 4. **Converge**: open the finished pages against the live catalog.
 5. **Payments last, if at all** — cards are off by default; [stage 03 below](#03--store-data) decides it.
 
@@ -185,7 +187,7 @@ function StoreLayout() {
 
 **This file is the whole job** — every shape is in ["What each hook resolves to"](#what-each-hook-resolves-to). Rules marked ⚑ must survive whatever design you build.
 
-⚑ **Only some of what lives there is importable.** Hooks and helpers (`useProduct`, `useCart`, `productImages`, …) are named exports; reviews exist **only on the client** `useStorefront()` returns — `submitReview`, `getProductReviews`. Importing one by name throws `does not provide an export named …` and blanks the whole app: `const c = useStorefront(); await c.submitReview(…)`.
+⚑ **These are the only importable names — the list is complete, never open the barrels to check it.** `@/commerce/storefront`: StorefrontProvider, useStorefrontState, useStorefront, useStoreInfo, useFormatMoney, useCountries, useCart, useCheckout, CheckoutProvider, useCheckoutContext, useOrderReturn, orderReceivedUrl, ShippingMethodPicker, PaymentMethodPicker, AddressFields, CartUIProvider, useCartUI, REQUIRED_BILLING_FIELDS, missingBillingFields, shippingSlice, isShippingAddressComplete, useProductList, useCategories, useRibbons, useProduct, useAddToCart, useCartLine, CartLine, variantAxes, productPrice, productImages, imageIndex, productRibbons, productSpecs, findSpec, attributesLabel, cartTotalsLines, orderTotalsLines, addressFieldSpec, storefrontErrorCode, storefrontErrorMessage. `@/commerce/storefront-ui`: CartPage, MiniCart, CartButton, CheckoutPage, OrderReceivedPage — `CartButton` lives here, not in `storefront`. Everything else — `listProducts`, `getProduct`, `listCategories`, `listRibbons`, `getProductReviews`, `submitReview`, `getCart`, `applyCoupon`, `chooseShippingMethod`, `completeReturn` — is a **method on the client** `useStorefront()` returns; importing one by name throws `does not provide an export named …` and blanks the app: `const c = useStorefront(); await c.submitReview(…)`. Kit React files are `.jsx` (`src/commerce/admin/index.jsx`); there is no `.js` twin to read.
 
 ## Design language — once, before any page
 
@@ -366,7 +368,7 @@ Headings, CTAs and empty-state copy come in per component as `brand` (each overr
 
 Behavior options, all optional (defaults are the professional store): `CartPage`/`CheckoutPage` take `sections` — `notes: false`, and on checkout `phone: "optional"|"required"|"hidden"`, `shipToDifferent: true`, `termsCheckbox: false`, `layout: "two-column"|"single"`. `hrefs` (`checkoutHref`, `cartHref`, `continueHref`, `homeHref`) default to `/checkout`, `/cart`, `/`; pass `productHref={(item) => …}` so line names link to your product route. Full props, slots and recipes: [`../references/storefront-ui.md`](../references/storefront-ui.md).
 
-**A store language outside the six**: copy `src/commerce/storefront-ui/i18n/locales/en.js` to `<lang>.js`, translate the values (~2–3K chars), repoint the one `import active` line in `src/commerce/storefront-ui/i18n/index.js`. Same-language brand props alone don't need this.
+**A store language outside the six** — no file reads needed: copy `src/commerce/storefront-ui/i18n/locales/en.js` to `<lang>.js` and translate the values (~2–3K chars), then repoint the one `import active` line in `src/commerce/storefront-ui/i18n/index.js` with `find_replace`: `import active from "./locales/en.js";` → `import active from "./locales/<lang>.js";`. The admin has the same line in `src/commerce/admin/i18n/index.js`. Same-language brand props alone don't need this.
 
 ## Driving the storefront from a browser script?
 
@@ -399,11 +401,12 @@ A fresh install has **no settings and no catalog**. One admin-only, idempotent c
 | **Demo data** | `{ store_name, with_sample_data: true }` — 10 generic products; cannot combine with `products` (**400**) |
 | **No products** | `{ store_name }` — defaults only |
 
-**`store_name` is required on a first seed** — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). **`currency`** is an ISO code (`"EUR"`); formatting follows the viewer's locale, nothing else to set. Explicit values always win, first seed and re-runs alike.
+**`store_name` is required on a first seed** — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). **`currency`** is any ISO 4217 code (`"EUR"`, `"NGN"`); formatting follows the viewer's locale, nothing else to set. Explicit values always win, first seed and re-runs alike.
 
 The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, upsells…) lives in `api-admin.md` — open it only if the catalog needs one:
 
 ```js
+// `base44` is already in scope in exec_tool — never import or redeclare it
 try {
   const res = await base44.functions.invoke("commerce/seed-store", {
     store_name: "Aurora Threads",
@@ -447,7 +450,7 @@ try {
         ],
       },
     ],
-    coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],
+    coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],   // percent | fixed_cart | fixed_product
     //   redemption is the shipped cart/checkout's job
     // locations: [ … ],   // shipping — next section; passing any makes them the store's ONLY ones
   });
@@ -459,7 +462,7 @@ try {
 
 **Running this through a code-execution tool? Return `res.data`, never the raw response** — the raw response carries circular objects and fails `Converting circular structure to JSON` *even when the seed succeeded*; a thrown error needs `e.response?.data` for the same reason.
 
-Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface. **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written; per-call limits (≤100 products, ≤500 variations, ≤50 locations) and the full key list are in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store).
+Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface (`on_sale` is derived and ignored; `brand` becomes a `Brand` spec row). **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written; per-call limits (≤100 products, ≤500 variations, ≤50 locations) and the full key list are in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store).
 
 The response reports everything; these matter downstream: