# Black Bean Shop — Getting started

## 1. Prerequisites

1. Install and activate **Black Bean Tables**
2. Seed + sync shop tables if prompted (Tables → Settings / Structure)
3. Activate **Black Bean Shop**
4. Flush permalinks (**Settings → Permalinks → Save**)

## 2. Configure payments

### PayPal (optional)

1. Open **Shop → Settings**
2. Enable **PayPal Checkout** and **Show PayPal at checkout** as needed
3. Enter PayPal client ID / secret (sandbox or live)
4. Save and register the webhook URL shown in settings (live mode):
   - `POST /wp-json/blackbean/v1/shop/paypal-webhook`
   - Subscribe to `CHECKOUT.ORDER.APPROVED` and `PAYMENT.CAPTURE.COMPLETED`

### MoMo (optional)

1. Open **Shop → Settings → MoMo**
2. Enable **MoMo Checkout** and **Show MoMo at checkout** as needed
3. Enter Partner Code, Access Key, and Secret Key (sandbox or live)
4. Set a **USD → VND fallback rate** (used when the exchange-rate API is unavailable)
5. Register the IPN URL in the MoMo merchant portal:
   - `POST /wp-json/blackbean/v1/shop/momo-ipn`

You can enable PayPal only, MoMo only, or both. Checkout shows a selector when more than one gateway is enabled and visible.

Store prices remain in USD. MoMo checkout converts the order total to integer VND using [Open ExchangeRate-API](https://open.er-api.com/) (cached 12 hours) with admin fallback.

## 3. Create a product

1. **Shop → Products → Add product**
2. Set title, price, digital flag
3. Attach a download file (Media ID) or external download URL
4. Optional license: prefix + max activations
5. For plugin updates: fill **Auto-updates** (slug, version, requires WP/PHP)

## 4. Test the storefront

1. Visit `/products/` on the front end
2. Add to cart → checkout
3. Choose PayPal or MoMo (if both are enabled)
4. Complete payment in sandbox
5. Confirm order email includes license key + download link

## 5. License a customer site

1. Copy the license key from the order email or **Shop → Licenses**
2. On the customer WordPress site, open the product’s **License** settings
3. Activate the key
4. **Dashboard → Updates** will show new versions when you publish them

## 6. Publish a new plugin version

```bash
# Build ZIP
npm run release:full --prefix wp-content/plugins/blackbean-forms

# Publish to shop registry (optional automation)
node scripts/publish-release.mjs blackbean-forms --product-id=N --apply
```

Or manually: upload ZIP to Media → set product Download file → bump **Latest version** under Auto-updates.

## 7. Verify versions

- **Shop → Versions** — code vs shop registry
- Or: `composer versions` / `composer versions:diff` from the site root

## 8. Verify product indexing

1. Open `/bb-shop-sitemap.xml` and confirm the catalog and published products are listed
2. With Rank Math active, open `/sitemap_index.xml` and confirm it references `/bb-shop-sitemap.xml`
3. After deploying a new sitemap rewrite, save **Settings → Permalinks** once
4. If Rank Math still serves a cached index, save **Rank Math → Sitemap Settings**

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| 404 on `/products/` | Flush permalinks |
| 404 on `/bb-shop-sitemap.xml` | Save Settings → Permalinks to refresh rewrite rules |
| Shop sitemap missing from Rank Math | Ensure Rank Math's Sitemap module is enabled, then save its Sitemap Settings to clear the cache |
| Shop won’t load | Activate Black Bean Tables first |
| No payment methods at checkout | Enable and configure at least one gateway in Shop → Settings |
| MoMo checkout fails with rate error | Check outbound HTTPS to open.er-api.com or set a fallback USD→VND rate |
| Updates not showing | Customer license inactive, or shop version ≤ installed version |
| Download fails | Attach Media ID on the product, re-fulfill order if needed |