@base44/app-plugin-commerce 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 base44
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Base44 Commerce Template
+
+A **Commerce backend + admin UI** for [Base44](https://base44.com) apps, delivered as a copyable file set. Drop `base44/` and `src/commerce/` into an existing Base44 app to add a full store: catalog, orders, coupons, customers, reviews, tax, shipping, webhooks, reports and transactional emails — plus a public storefront API for building your own shopfront.
+
+It provides a full-featured **commerce data model and behavior** (product types, order lifecycle, coupon rules, tax priority/compound math, shipping zones) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).
+
+## What's included
+
+- **24 entities** — Products (simple/grouped/external/variable), variations, categories, tags, attributes + terms, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, tax classes/rates, shipping zones/methods, payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
+- **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store`.
+- **Online card payments, implemented** — hosted payment page, payment links for unpaid orders, two idempotent confirmation paths (customer return + signed webhook) and refunds through the provider. Wired to **Stripe** out of the box behind a provider-neutral payment utility, so the store takes cards as soon as the connector is connected — no charge flow to write — and moving to another provider means implementing one adapter. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, payments utility + Stripe adapter, plus static country/currency/continent data.
+- **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, full settings, webhooks. Admin-role gated.
+- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variable-product price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
+- **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
+- **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app so agents pick it up natively.
+
+## Repo map
+
+```
+base44-commerce-template/
+├── base44/
+│   ├── entities/     24 .jsonc entity schemas (commerce.*.jsonc)
+│   ├── functions/
+│   │   └── commerce/ 16 Deno functions (entry.ts each), invoked as "commerce/<name>"
+│   ├── agents/
+│   │   └── commerce/ StoreAdmin.jsonc — AI admin copilot ("commerce/StoreAdmin")
+│   └── shared/
+│       └── commerce/ commerce engine + static data (bundled into every function)
+├── src/
+│   └── commerce/
+│       ├── admin/    React admin UI (copy into your app's src/commerce/)
+│       └── utils/    storefront helpers — variant selection, shipping promos
+├── scripts/
+│   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
+├── skills/
+│   └── commerce/          commerce skill — copied into the app's skills/ so agents
+│       │                  know the store natively
+│       ├── SKILL.md       the map: short overview + links to everything below
+│       ├── installation-guidelines.md   installing into an app (scripted or manual)
+│       ├── post-installation.md         embedding the admin pages + AGENTS.md registration
+│       ├── references/    per-topic guides (product rendering, product page & variants,
+│       │                  Stripe, scheduled work, emails, webhooks, media & downloads,
+│       │                  limits, security)
+│       └── docs/
+│           ├── api-admin.md       admin function/entity reference
+│           └── api-storefront.md  storefront function reference (build your own shopfront)
+└── README.md
+```
+
+## Get it from npm
+
+The template is published as **`@base44/app-plugin-commerce`** — a source-only package whose tarball is exactly the `base44/`, `scripts/`, `skills/` and `src/` folders of this repo, with no build or bundling step. Unpack it into your app at `examples/commerce/` and the install flow below works unchanged:
+
+```bash
+npm pack @base44/app-plugin-commerce      # → base44-app-plugin-commerce-<version>.tgz
+mkdir -p examples/commerce
+tar -xzf base44-app-plugin-commerce-*.tgz --strip-components=1 -C examples/commerce
+node examples/commerce/scripts/install.js
+```
+
+`scripts/install.js` resolves the app root relative to its own location (`<app>/examples/commerce/scripts/`), so run it from the unpacked copy rather than from inside `node_modules/`.
+
+## Quick start (Base44 CLI)
+
+From your existing Base44 app:
+
+1. **Copy the files** — either copy this whole repo into your app at `examples/commerce/` and run `node examples/commerce/scripts/install.js`, or merge `entities/`, `functions/`, `shared/` into your app's `base44/` directory by hand (see [`skills/commerce/installation-guidelines.md`](./skills/commerce/installation-guidelines.md)). Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders.
+2. **Push the schema, functions and agent:**
+   ```bash
+   npx base44 entities push
+   npx base44 functions deploy
+   npx base44 agents push
+   ```
+3. **Copy the UI files:** `src/commerce/admin/` → `src/commerce/admin/` and `src/commerce/utils/` → `src/commerce/utils/`.
+4. **Confirm UI deps** — `sonner`, `recharts` and `react-markdown` all ship with the default Base44 template and are the only ones the admin needs; install any that are missing:
+   ```bash
+   npm i sonner recharts
+   ```
+   See [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) for the exact shadcn component list.
+5. **Mount the admin router** in your app:
+   ```jsx
+   import AdminApp from "@/commerce/admin";
+   // inside your <Routes>:
+   <Route path="/admin/*" element={<AdminApp />} />
+   ```
+6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
+7. **Seed the store.** Either open `/admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus a sample catalog when `with_sample_data: true` and the store is empty. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. If an agent is installing this, it should **ask which data the user wants** first — a generated catalog for their actual business, the generic demo data, or nothing: see [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
+
+## Quick start (Base44 MCP / hosted apps)
+
+If you build on Base44's hosted platform, use the Base44 agent/MCP to write the files instead of the CLI:
+
+1. Copy this whole repo into the target app at `examples/commerce/` (e.g. download + extract a tarball with `run_command`), then run `node examples/commerce/scripts/install.js` via `run_command` — or use `write_file` to copy every file under `base44/` and `src/commerce/` individually (use `list_directory`/`read_file` to adapt to the app's actual layout — e.g. the `@/api/base44Client` path and your router file).
+2. Wait for the app to build (`get_app_status`), then confirm entities exist (`list_entity_schemas`).
+3. Grant your user the `admin` role, then settle the store's data with the user — generate a real starter catalog via `commerce/seed-store` + `commerce/admin-products`, seed the demo catalog, or leave it to the admin's first-run **Initialize store defaults** screen ([`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2).
+
+## What's NOT included
+
+- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variable-product price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
+- **No payment credentials** — the card integration itself *is* included (see above), but a store can only charge once someone connects a payment provider's connector for the app. Until then the card option stays hidden from customers and the manual gateways (bank transfer / cheque / COD) carry checkout.
+- **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
+
+## Next steps
+
+- **Install into your app:** [`skills/commerce/installation-guidelines.md`](./skills/commerce/installation-guidelines.md)
+- **Operate & extend:** the commerce skill — [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md)
+- **Build a storefront:** [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md)
+- **Admin automation / alternative admin:** [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md)
+
+## Releasing (maintainers)
+
+Publishing is manual: **Actions → Manual Package Publish → Run workflow** ([`.github/workflows/manual-publish.yml`](./.github/workflows/manual-publish.yml)).
+
+Inputs: `version` (`patch`/`minor`/`major` or an explicit `0.1.0`), `npm_tag` (`latest`, `beta`, …) and `dry_run`. The workflow bumps `package.json`, prints the tarball contents, runs `npm publish`, then commits the bump, tags `v<version>` and cuts a GitHub release. A dry run publishes nothing and leaves no tag or commit.
+
+The first release needs an explicit version (the repo sits at `0.0.0`). Requirements: the repo secret/org secret **`NPM_TOKEN`** (an npm automation token with publish rights on the `@base44` scope), plus the org's `BASE44_GITHUB_ACTIONS_APP_ID` variable and `BASE44_GITHUB_ACTIONS_APP_PRIVATE_KEY` secret used to push the release commit.

package/base44/agents/commerce/StoreAdmin.jsonc

@@ -0,0 +1,64 @@
+// StoreAdmin — AI copilot for the Base44 Commerce Template admin.
+// Referenced as "commerce/StoreAdmin" (the folder namespaces the agent, like functions).
+//
+// The commerce/* backend functions are attached directly as tools. Tool calls
+// run with the chatting user's credentials, so requireAdmin() in every admin
+// function still applies — the agent has no entity tools and no service-role
+// shortcut. NOTE: no "model" field on purpose — the platform default model
+// path handles slash-namespaced tool names; explicitly setting a model
+// currently rejects them (tool name pattern ^[a-zA-Z0-9_-]{1,128}$).
+{
+  "name": "StoreAdmin",
+  "description": "Store administration copilot for the commerce template: manage products, orders, refunds, coupons, customers, reviews, reports and maintenance.",
+  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {with_sample_data?} with no action key) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, tax rates, shipping zones, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Tax](admin:settings/tax)`. The chat resolves that to wherever the admin is mounted, so never write `/admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, store name/address, coupon & tax toggles | Settings → General | admin:settings/general |\n| Catalog defaults, review settings | Settings → Products | admin:settings/products |\n| Stock thresholds, hold minutes, inventory recipient | Settings → Inventory | admin:settings/inventory |\n| Tax classes, tax rates, price display | Settings → Tax | admin:settings/tax |\n| Shipping zones, methods, shipping classes | Settings → Shipping | admin:settings/shipping |\n| Enabling a gateway, bank/BACS details | Settings → Payments | admin:settings/payments |\n| From-name, admin notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Creating or deleting a webhook (you CAN test and redeliver) | Webhooks | admin:webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live in the store's tax settings. Open [Settings → Tax](admin:settings/tax) to add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, tags, attributes and attribute terms yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — only link to admin:products/categories, admin:products/tags or admin:products/attributes if they want to review or reorder them by hand.\n\n## Product variants — be careful\nProducts of type \"variable\" are sold as variations, and every variation can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a variable product, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for variable products; the backend rejects a bare product_id for them.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
+  "tool_configs": [
+    {
+      "function_name": "commerce/admin-products",
+      "description": "Product & variation management, plus category/tag terms. Actions: save {product, variations?} (upsert + derived price/stock, SKU/slug uniqueness), delete {id}, batch {create?,update?,delete?}, duplicate {id}, set-stock {id, variation_id?, quantity}, search {q?, category_id?, type?, stock_status?, status?, sort?, limit?, skip?} → {rows, has_next}, list-terms {taxonomy, q?, attribute_id?, limit?, skip?} → {rows, has_next}, save-term {taxonomy, term: {...}} (upsert; slug auto-derived and made unique), delete-term {taxonomy, id, detach?}. taxonomy is \"category\" | \"tag\" | \"attribute\" | \"attribute-term\"; term fields per taxonomy: category {id?, name, slug?, description?, parent_id?, image?, menu_order?}, tag {id?, name, slug?, description?}, attribute {id?, name, slug?, type?, order_by?, has_archives?}, attribute-term {id?, attribute_id (required), name, slug?, description?, menu_order?}. Create these yourself with save-term — do NOT tell the operator to create them by hand. list-terms first and reuse a match before creating a duplicate. Deleting an attribute deletes its terms. A variable product needs a ProductAttribute (+ its terms) to exist before product.attributes[].options can reference it, so create the attribute and terms first, then save the product."
+    },
+    {
+      "function_name": "commerce/admin-orders",
+      "description": "Order lifecycle. Actions: create-draft, create {items, ...}, update {order_id, patch}, update-status {order_id, status, note?}, bulk-status {ids, status}, status-counts, search {q?, status?, date_min?, date_max?, sort?, limit?, skip?}, recalculate {order_id}, apply-coupon/remove-coupon {order_id, code}, add-note {order_id, note, is_customer_note?}, delete-note {note_id}, send-email {order_id, type}, grant-download {order_id, product_id}, revoke-download {permission_id}, delete {order_id}, release-expired-holds. Item specs: {product_id, variation_id?, quantity, price_override?} — variation_id REQUIRED for variable products (ask the operator which variation; never auto-pick). Statuses: pending, processing, on-hold, completed, cancelled, refunded, failed."
+    },
+    {
+      "function_name": "commerce/admin-refunds",
+      "description": "Refunds. Actions: create {order_id, amount, reason?, line_items? [{line_id, quantity, refund_total, refund_tax?}], restock_items?, refund_payment?} (validates against remaining refundable; full refund transitions order to refunded), delete {refund_id}."
+    },
+    {
+      "function_name": "commerce/admin-coupons",
+      "description": "Coupons. Actions: save {coupon} (unique lowercased code), delete {id}, batch {create?,update?,delete?}, search {q?, limit?, skip?} → {rows, has_next}."
+    },
+    {
+      "function_name": "commerce/admin-customers",
+      "description": "Customers. Actions: save {customer} (unique email), delete {id, reassign_orders_to_guest?}, search {q?, limit?, skip?} → {rows, has_next}, invite {email}, recalculate-stats {id}."
+    },
+    {
+      "function_name": "commerce/admin-reviews",
+      "description": "Product reviews moderation. Actions: set-status {id, status: approved|hold|spam|trash}, update {id, rating?, review?}, delete {id}. Each recomputes the product's average_rating/rating_count."
+    },
+    {
+      "function_name": "commerce/admin-webhooks",
+      "description": "Webhook diagnostics. Actions: test {webhook_id} (sends sample payload, returns {delivery_id, response_code, success, duration_ms}), redeliver {delivery_id}."
+    },
+    {
+      "function_name": "commerce/admin-reports",
+      "description": "Reports (computed from orders on demand). Actions: summary, sales {date_min?, date_max?, interval?: day|week|month}, top-sellers {date_min?, date_max?, limit?}, stock, orders-totals, products-totals, customers-totals, coupons-totals, reviews-totals, categories-totals, tags-totals, attributes-totals."
+    },
+    {
+      "function_name": "commerce/admin-tools",
+      "description": "System status & maintenance. Actions: status (template_version, seeded, entity counts, health checks), recount-terms, recount-coupon-usage, recalculate-customer-stats-all, prune-webhook-deliveries {keep_days}, clear-abandoned-carts {older_than_days}, regenerate-download-permissions {order_id}."
+    },
+    {
+      "function_name": "commerce/seed-store",
+      "description": "Initialize store defaults (idempotent; canary schema check first). Body: {with_sample_data?: boolean} — no action key. Sample catalog only created when the store has zero products."
+    },
+    {
+      "function_name": "commerce/payments",
+      "description": "Online payment for an order. Actions: status {} → {provider, connected, gateway_slug} (is a payment provider connected?), create-link {order_id} → {url} (provider-hosted payment page for an UNPAID online order — the link to send a customer; 409 already_paid, 400 not_an_online_payment, 503 payment_provider_unavailable), verify {order_id} → {paid, status} (re-ask the provider and move the order on if paid; idempotent)."
+    },
+    {
+      "function_name": "commerce/storefront-catalog",
+      "description": "Read-only public catalog browsing — use get-product BEFORE putting a variable product on an order, to list its variations and ask the operator which one. Actions: get-store-info, list-products {q?, category_id?, tag_id?, featured?, on_sale?, min_price?, max_price?, sort?, page?, per_page?}, get-product {id | slug} → {product, variations, ...}, list-categories, list-tags, list-reviews {product_id, page?, per_page?}."
+    }
+  ]
+}

package/base44/entities/commerce.Cart.jsonc

@@ -0,0 +1,73 @@
+{
+  "name": "commerce.Cart",
+  "type": "object",
+  "description": "Storefront cart session (a self-contained cart + checkout-draft). Access is exclusively via commerce/storefront-cart using the cart_token bearer credential; items store no prices — pricing is resolved at read time.",
+  "properties": {
+    "cart_token": {
+      "type": "string",
+      "description": "Random uuid; the guest bearer credential. Treat as a secret."
+    },
+    "customer_email": {
+      "type": "string",
+      "description": "Set when the caller is known (login or checkout); used for cart merge"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "item_key": { "type": "string", "description": "Stable key within the cart" },
+          "product_id": { "type": "string" },
+          "variation_id": { "type": "string" },
+          "quantity": { "type": "integer" },
+          "attributes": {
+            "type": "array",
+            "description": "Chosen variation attributes for display",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "option": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "coupon_codes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "shipping_address": {
+      "type": "object",
+      "description": "Destination used for zone matching and tax preview",
+      "properties": {
+        "country": { "type": "string" },
+        "state": { "type": "string" },
+        "postcode": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    },
+    "chosen_shipping_method": {
+      "type": "string",
+      "description": "ShippingZoneMethod id"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "converted", "abandoned"],
+      "default": "active"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "now + 48h, refreshed on touch; expired carts cleared via commerce/admin-tools clear-abandoned-carts"
+    }
+  },
+  "required": ["cart_token"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.Coupon.jsonc

@@ -0,0 +1,113 @@
+{
+  "name": "commerce.Coupon",
+  "type": "object",
+  "description": "Discount coupon with full-featured restrictions and usage limits. Validation happens server-side in shared/coupons.",
+  "properties": {
+    "code": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Coupon code, stored lowercase, unique (enforced in commerce/admin-coupons)"
+    },
+    "discount_type": {
+      "type": "string",
+      "enum": ["percent", "fixed_cart", "fixed_product"],
+      "default": "fixed_cart"
+    },
+    "amount": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Discount value (percentage for percent type)"
+    },
+    "description": {
+      "type": "string"
+    },
+    "date_expires": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "free_shipping": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enables the free_shipping method when it requires a coupon"
+    },
+    "individual_use": {
+      "type": "boolean",
+      "default": false,
+      "description": "Cannot be combined with other coupons"
+    },
+    "exclude_sale_items": {
+      "type": "boolean",
+      "default": false
+    },
+    "product_ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Apply only to these products"
+    },
+    "excluded_product_ids": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "product_category_ids": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Apply only to items in these categories"
+    },
+    "excluded_product_category_ids": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "minimum_amount": {
+      "type": "number",
+      "description": "Minimum items subtotal to qualify"
+    },
+    "maximum_amount": {
+      "type": "number",
+      "description": "Maximum items subtotal to qualify"
+    },
+    "email_restrictions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Allowed billing emails; *@domain.com wildcards supported"
+    },
+    "usage_limit": {
+      "type": "integer",
+      "description": "Max uses across all customers; null/absent = unlimited"
+    },
+    "usage_limit_per_user": {
+      "type": "integer",
+      "description": "Max uses per customer email; null/absent = unlimited"
+    },
+    "limit_usage_to_x_items": {
+      "type": "integer",
+      "description": "Max items the coupon applies to (fixed_product); null/absent = all"
+    },
+    "usage_count": {
+      "type": "integer",
+      "default": 0,
+      "description": "Derived. Maintained by shared/coupons countUsage/uncountUsage."
+    },
+    "used_by": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Customer emails, one entry per counted use. Maintained by shared/coupons."
+    },
+    "meta_data": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["code", "amount"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.Customer.jsonc

@@ -0,0 +1,96 @@
+{
+  "name": "commerce.Customer",
+  "type": "object",
+  "description": "Store customer, supporting guests (no linked user) and registered users. Self-service access is mediated by commerce/storefront-account.",
+  "properties": {
+    "email": {
+      "type": "string",
+      "format": "email",
+      "description": "Unique (enforced in commerce/admin-customers / checkout upsert)"
+    },
+    "first_name": {
+      "type": "string"
+    },
+    "last_name": {
+      "type": "string"
+    },
+    "username": {
+      "type": "string"
+    },
+    "user_id": {
+      "type": "string",
+      "description": "Base44 User id when registered; empty = guest"
+    },
+    "is_guest": {
+      "type": "boolean",
+      "description": "Maintained by checkout/admin-customers: true when no linked Base44 user"
+    },
+    "billing": {
+      "type": "object",
+      "properties": {
+        "first_name": { "type": "string" },
+        "last_name": { "type": "string" },
+        "company": { "type": "string" },
+        "address_1": { "type": "string" },
+        "address_2": { "type": "string" },
+        "city": { "type": "string" },
+        "state": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string" },
+        "email": { "type": "string", "format": "email" },
+        "phone": { "type": "string" }
+      }
+    },
+    "shipping": {
+      "type": "object",
+      "properties": {
+        "first_name": { "type": "string" },
+        "last_name": { "type": "string" },
+        "company": { "type": "string" },
+        "address_1": { "type": "string" },
+        "address_2": { "type": "string" },
+        "city": { "type": "string" },
+        "state": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string" },
+        "phone": { "type": "string" }
+      }
+    },
+    "is_paying_customer": {
+      "type": "boolean",
+      "default": false,
+      "description": "Derived from paid orders. Maintained by order lifecycle / commerce/admin-customers recalculate-stats."
+    },
+    "orders_count": {
+      "type": "integer",
+      "default": 0,
+      "description": "Derived. Maintained by order lifecycle / commerce/admin-customers recalculate-stats."
+    },
+    "total_spent": {
+      "type": "number",
+      "default": 0,
+      "description": "Derived. Maintained by order lifecycle / commerce/admin-customers recalculate-stats."
+    },
+    "avatar_url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "meta_data": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string" },
+          "value": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["email"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.DownloadPermission.jsonc

@@ -0,0 +1,54 @@
+{
+  "name": "commerce.DownloadPermission",
+  "type": "object",
+  "description": "Grants a customer download access to a purchased file. Granted/revoked by the order lifecycle; served and decremented via commerce/storefront-account get-download.",
+  "properties": {
+    "order_id": {
+      "type": "string"
+    },
+    "order_key": {
+      "type": "string",
+      "description": "Copied from the order for guest access checks"
+    },
+    "customer_email": {
+      "type": "string",
+      "format": "email"
+    },
+    "product_id": {
+      "type": "string"
+    },
+    "variation_id": {
+      "type": "string"
+    },
+    "download_name": {
+      "type": "string",
+      "description": "File display name"
+    },
+    "file_url": {
+      "type": "string",
+      "format": "uri"
+    },
+    "downloads_remaining": {
+      "type": "integer",
+      "default": -1,
+      "description": "-1 = unlimited"
+    },
+    "access_expires": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Absent/null = never expires"
+    },
+    "download_count": {
+      "type": "integer",
+      "default": 0,
+      "description": "Total downloads served"
+    }
+  },
+  "required": ["order_id", "customer_email", "product_id"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.EmailLog.jsonc

@@ -0,0 +1,43 @@
+{
+  "name": "commerce.EmailLog",
+  "type": "object",
+  "description": "Log of transactional emails sent via shared/emails.",
+  "properties": {
+    "email_type": {
+      "type": "string",
+      "description": "e.g. new_order, processing, completed, refunded, customer_note"
+    },
+    "recipient": {
+      "type": "string"
+    },
+    "target": {
+      "type": "string",
+      "enum": ["admin", "customer"],
+      "description": "Who the email was addressed to. Stock notifications count as admin."
+    },
+    "subject": {
+      "type": "string"
+    },
+    "order_id": {
+      "type": "string",
+      "description": "Order id as presented to users (order_number)"
+    },
+    "order_record_id": {
+      "type": "string",
+      "description": "Internal Order record id, for linking back to the order"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "error": {
+      "type": "string",
+      "description": "Error message when success is false"
+    }
+  },
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}