# Black Bean Shop — Features

Lightweight digital commerce for WordPress — products, cart, checkout, licenses, and plugin updates — built on **Black Bean Tables** (no WooCommerce).

Current release: **v0.2.0**

Related: [GETTING-STARTED.md](./GETTING-STARTED.md) · [CHANGELOG.md](../CHANGELOG.md)

---

## Commerce

| Feature | Purpose |
|---------|---------|
| Products | Catalog stored in Black Bean tables (title, price, stock, digital flags) |
| Cart | Session cart with REST add/update/remove |
| Checkout | Customer details → PayPal and/or MoMo payment |
| Orders | Paid/pending status, fulfillment metadata, payment audit fields |
| Digital delivery | Tokenized download links + email on payment |

## Payments

| Feature | Purpose |
|---------|---------|
| PayPal | Optional gateway with sandbox/live credentials and webhook fulfillment |
| MoMo | Optional gateway v2 (`payWithMethod`) with sandbox/live credentials and IPN |
| Gateway toggles | Enable/disable each gateway independently; control visibility at checkout |
| USD → VND | MoMo charges in VND; store prices stay in USD (Open ExchangeRate-API + fallback) |
| Payment audit | Orders store gateway, provider ref, charged amount/currency, FX snapshot |

## Licensing

| Feature | Purpose |
|---------|---------|
| License keys | Generated per order line (`PREFIX-order-product-rand`) |
| Activation limits | Max sites per product |
| REST API | `activate` / `deactivate` / `check` for customer plugins |
| License client | Drop-in PHP client for themes/plugins |

## Auto-updates

| Feature | Purpose |
|---------|---------|
| Update registry | Map product → plugin/theme slug + version |
| Check endpoint | Licensed sites poll for newer versions |
| Download endpoint | Short-lived token streams the release ZIP |
| Public manifest | Version metadata without package URL |
| Shop → Versions | Compare code catalog vs published shop versions |

## Front-end routes

- `/products/` — catalog
- `/products/{slug}/` — product detail
- `/shop/cart/` — cart
- `/shop/checkout/` — checkout

## Search and sitemaps

- `/bb-shop-sitemap.xml` — catalog and all published product URLs
- Rank Math adds the shop sitemap to `/sitemap_index.xml`
- WordPress core registers the `bbshop` sitemap provider when core sitemaps are enabled
- Draft products are excluded; `updated_at` supplies each product's `lastmod`

## REST (namespace `blackbean/v1`)

- `GET /shop/products`
- `GET|POST /shop/cart`
- `POST /shop/license/{activate,deactivate,check}`
- `GET /shop/download`
- `POST /shop/paypal-webhook`
- `POST /shop/momo-ipn`
- `POST /updates/check`
- `GET /updates/download`
- `GET /updates/manifest/{slug}`

## Requirements

- WordPress **6.0+**, PHP **8.1+**
- **Black Bean Tables** active
- PayPal and/or MoMo credentials in Shop → Settings (for live checkout)
- MoMo requires USD or VND store currency; other currencies are not converted