@blamejs/blamejs-shop 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.1.x
 
+- v0.1.17 (2026-05-25) — **Admin console — an inventory screen.** Inventory joins the admin console. `/admin/inventory` lists stock per SKU — on hand, held, and available — with a low-stock filter, restocks a SKU, sets or clears its per-SKU low-stock threshold, and tracks a new SKU, all from a signed-in browser. As with the other console screens, the same path serves the existing JSON API to a bearer-token client unchanged. **Added:** *Inventory management screen* — `/admin/inventory` renders the inventory table (SKU, on-hand, held, available) with a low-stock filter (`?low=1`) that surfaces SKUs at or below their threshold, when opened in a signed-in browser; the same path serves a new JSON list to a bearer-token client. Each row's form restocks (add quantity) and sets the low-stock threshold (blank clears it) in one submit, and a form below tracks a new SKU. The create / restock JSON API is unchanged for tooling; the browser forms post and redirect (PRG), and a bad SKU is a no-op notice rather than a 500. · *catalog.inventory.list* — `catalog.inventory.list({ limit, low_only })` returns inventory rows (SKU ascending), optionally only those at or below their configured low-stock threshold — the read backing the console list and the JSON endpoint. **Changed:** *Console nav gains Inventory* — The signed-in admin nav now includes Inventory alongside Products, Orders, Returns, and Reviews. The `/admin/inventory` list and the create / restock endpoints content-negotiate like the other screens: a bearer-token client gets the JSON API, a signed-in browser gets HTML. A request without the bearer token on these paths now returns the sign-in form on a GET and redirects on a write, matching the other console screens.
+
+- v0.1.16 (2026-05-25) — **PayPal express checkout — the on-page button.** PayPal checkout is now usable from the storefront. When PayPal is configured, the checkout page shows a native PayPal button (distinct from PayPal-through-Stripe): it opens a PayPal order for the current cart, the buyer approves in the PayPal popup, and the order is captured and marked paid. A verified PayPal webhook is the asynchronous backstop. This completes the native PayPal integration on top of the adapter and checkout orchestration shipped in the previous two releases. Card / Stripe checkout is unchanged. **Added:** *PayPal button + create/capture routes on the storefront* — The checkout page renders a PayPal button when `PAYPAL_CLIENT_ID` is configured. Its create step posts to `POST /checkout/paypal/create` (prices the cart, opens a PayPal order, persists the local order pending) and its approve step posts to `POST /checkout/paypal/capture` (captures and advances the order to paid, then redirects to the order page). Both validate input and never 500 on a missing cart or id. The buttons collect the same shipping fields as the card form. · *PayPal webhook endpoint* — `POST /api/webhooks/paypal` is the asynchronous backstop for captures completed or refunded out of band. The container verifies each event server-to-server through PayPal's verify-webhook-signature API (no edge HMAC pre-check, unlike Stripe), then advances the order; re-deliveries are idempotent. Point a PayPal webhook at `/api/webhooks/paypal`. **Changed:** *PayPal listed as configurable; CSP note* — The integrations status page and README document PayPal as a first-class checkout option once configured. As with the Stripe pay page's `js.stripe.com`, operators must allow `www.paypal.com` in their Content-Security-Policy `script-src` / `frame-src` for the PayPal SDK and approval popup.
+
 - v0.1.15 (2026-05-25) — **PayPal checkout orchestration.** Checkout can now run a PayPal order end to end, building on the adapter from the previous release. The orchestrator prices the cart, opens a PayPal order and persists the local order as pending, captures it after the buyer approves and advances the order to paid, and has a webhook backstop for captures completed or refunded out of band. Wired in when a PayPal app's credentials are present, and surfaced on the integrations status page. The storefront button and routes that drive this from the pay page come next; card / Stripe checkout is unchanged. **Added:** *checkout PayPal methods* — With a PayPal adapter wired (`paypal` dep), checkout gains three methods. `createPaypalOrder({ cart_id, ship_to, selected_shipping_id, customer, idempotency_key, return_url?, cancel_url? })` prices the cart, opens a PayPal Orders-v2 order, persists the local order in `pending` with the PayPal order id linked, and marks the cart converted. `capturePaypalOrder(paypalOrderId)` captures the approved order and advances the local order to `paid` (idempotent — a retry or a webhook that beat it won't double-transition). `handlePaypalEvent({ headers, rawBody })` is the asynchronous backstop: it verifies the event through PayPal, then maps `PAYMENT.CAPTURE.COMPLETED` → paid and `PAYMENT.CAPTURE.REFUNDED` → refunded, idempotent across re-deliveries. · *PayPal wired from configuration* — When `PAYPAL_CLIENT_ID` + `PAYPAL_SECRET` are set (with `PAYPAL_ENV` and `PAYPAL_WEBHOOK_ID`), the server builds the PayPal adapter and passes it to checkout; the integrations status page lists PayPal as action-needed once card checkout is also live. Off until configured; the existing checkout flow is untouched.
 
 - v0.1.14 (2026-05-25) — **PayPal payment adapter (Orders v2).** `payment.create({ adapter: "paypal", … })` is a new native PayPal adapter alongside the Stripe one — a from-scratch Orders-v2 client over the framework's SSRF-gated HTTP client, with no PayPal SDK dependency. It exchanges an OAuth2 client-credentials token (cached until it nears expiry), creates and captures orders, fetches and refunds them, and verifies inbound webhooks through PayPal's verify-webhook-signature API. This ships the adapter only; wiring it into the checkout flow and a storefront button comes next. Card / Stripe checkout is unchanged. **Added:** *PayPal Orders-v2 adapter* — `payment.create({ adapter: "paypal", clientId, secret, sandbox?, webhookId?, apiBase? })` returns `{ createOrder, captureOrder, getOrder, refund, verifyWebhook }`. `createOrder({ amount_minor, currency, order_id?, return_url?, cancel_url? })` opens a CAPTURE-intent order (amounts converted to PayPal's decimal-string major units, including 0-decimal currencies); `captureOrder(id)` finalizes it; `refund({ capture_id, amount_minor?, currency? })` refunds full or partial; `getOrder(id)` reads status. Every call carries an OAuth2 bearer token exchanged once and cached until ~2 minutes before expiry, and a `PayPal-Request-Id` for idempotency (plus the shared idempotency cache when a `query` handle is wired). `verifyWebhook(headers, rawBody, { webhookId })` confirms an inbound event through PayPal's verify-webhook-signature API and returns `{ ok, event }`. Outbound HTTP goes through `b.httpClient` — no `paypal` npm dependency. Off until the operator supplies credentials; the Stripe adapter and existing checkout are unchanged.

package/README.md

@@ -57,9 +57,9 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/pricing.js`** | Pure-function money math — `lineTotal`, `subtotal`, `totals`, `format`. Multi-currency refused, banker's-style rounding, locale-aware via `Intl.NumberFormat`. |
 | **`lib/tax.js`** | Operator-table adapter. Country / state / postal_prefix → rate_bps. Most-specific-first match, banker's rounding. Pluggable adapter shape for future Stripe Tax / TaxJar / Avalara. |
 | **`lib/shipping.js`** | Operator-table adapter. Services with zones (flat or per-gram + base + min/max), free-over-threshold, `digital_only` flag. |
-| **`lib/payment.js`** | Stripe adapter — verify webhook (HMAC-SHA256 via upstream `b.webhook.verify` alg `hmac-sha256-stripe`), create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains (Apple Pay + Google Pay enablement for the Express Checkout Element). No `stripe` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
+| **`lib/payment.js`** | Payment adapters — **Stripe** (verify webhook HMAC-SHA256 via upstream `b.webhook.verify`, create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains for Apple/Google Pay) and **PayPal** (`adapter: "paypal"` — OAuth2 client-credentials token, create / capture / get / refund Orders v2, webhook verify via PayPal's verify-webhook-signature API). No `stripe` / `paypal` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
 | **`lib/order.js`** | FSM-driven post-checkout record via upstream `b.fsm`. States: pending → paid → fulfilling → shipped → delivered (+ refunded / cancelled). Every transition appends to `order_transitions`. |
-| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` creates PaymentIntent + persists order in pending; `handleStripeEvent()` verifies webhook + fires the FSM transition (idempotent on re-delivery). |
+| **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` creates a Stripe PaymentIntent + persists order pending; `handleStripeEvent()` verifies webhook + fires the FSM transition. PayPal path: `createPaypalOrder()` opens a PayPal order + persists pending, `capturePaypalOrder()` captures → paid, `handlePaypalEvent()` is the webhook backstop. All idempotent on re-delivery. |
 | **`lib/email.js`** | Transactional templates — order receipt, ship notification, refund confirmation. Strict `{{var}}` renderer with HTML escape + refusal of unknown / unused placeholders. Composed on `b.mail` (DKIM/SPF/DMARC/BIMI upstream). |
 | **`lib/storefront.js`** | Server-rendered HTML — utility bar + sticky header + dark hero with code-preview card + primitives marquee + featured-product callout + collections grid + framework feature band + designed catalog grid + newsletter band + four-column footer. Designed surfaces also for PDP, cart, checkout, pay, order, account login / register / dashboard, search results, `/admin` API landing, 404. Image-bearing cards on the home + search grids pull from `catalog.media`. The default theme stylesheet is external (R2-served `themes/default/assets/css/main.css`) and CSP-compliant — operators override by uploading a replacement at the same key, by passing `opts.theme_css` to renderers, or by registering a named theme through the `theme` primitive. |
 | **`lib/customers.js`** | Customer accounts — passkey (WebAuthn) + **Sign in with Google / Apple** (OIDC). Email is stored hash-only (`b.crypto.namespaceHash` namespace `customer-email`); the raw address never lands in D1. Passkey credentials carry CBOR-encoded public keys, transport hints, and SHA3-512-fingerprinted attestation. `signInWithOIDC` keys federated accounts on the provider `(provider, subject)` and links an existing account only on a provider-verified email (never on an unverified one). `mintAppleClientSecret` produces Apple's required ES256 client-secret JWT from a Services-ID `.p8` key (the one classical signature the protocol mandates; the PQC default doesn't apply to an external IdP's wire format). Account routes (`/account/login`, `/account/register`, `/account`, `/account/login/google`, `/account/login/apple`) ship as designed cards on the storefront. |
@@ -72,7 +72,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline. The Returns and Reviews links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), with a persistent nav across every signed-in page. A guided **setup wizard** at `/admin/setup` writes shop identity to config; **Products** (`/admin/products`) browses the catalog and creates / archives / restores; **Inventory** (`/admin/inventory`) lists stock per SKU (on-hand / held / available) with a low-stock filter, restocks, sets per-SKU thresholds, and tracks new SKUs; **Orders** (`/admin/orders`) lists recent orders with status filters, opens an order's items, totals, and shipping address, and drives the lifecycle (mark paid → fulfil → ship → deliver, cancel — Refund goes through the payment provider) through the order FSM; **Returns** (`/admin/returns`) is the RMA moderation queue — filter by status, open a request's items and reason, and approve (with refund amount) → mark received → refund, or reject with a reason, over the return FSM; **Reviews** (`/admin/reviews`) is the review moderation queue — filter by status and publish, reject (with a reason), or take down each submission inline. The Returns and Reviews links appear only when those primitives are wired. Each console path content-negotiates: a bearer-token client still gets the JSON API unchanged, a signed-in browser gets HTML. Reachable by the cookie or the bearer token. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 
@@ -163,10 +163,10 @@ variables. A signed-in operator can see the live on/off status of each at
 | **Apple Pay & Google Pay** | One-tap wallet buttons (Express Checkout Element) on the pay page. | Stripe (above) **+** register each web domain: `POST /admin/payment-method-domains {"domain_name":"shop.example.com"}` | Stripe performs Apple merchant validation and hosts the association file — **no Apple Developer account needed**. Apex, `www`, and each subdomain register separately; a live-mode registration also covers sandbox. |
 | **Sign in with Google** | A *Continue with Google* button on `/account/login` (OIDC). | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `SHOP_ORIGIN` (e.g. `https://shop.example.com`) | Create a Google Cloud **OAuth 2.0 Web** client; add `<SHOP_ORIGIN>/account/auth/google/callback` as an Authorized redirect URI; consent-screen scopes `openid email profile`. The button appears only when all three are set. |
 | **Sign in with Apple** | A *Continue with Apple* button on `/account/login` (OIDC). | `APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_CLIENT_ID` (your **Services ID**), `APPLE_PRIVATE_KEY` (the `.p8` key contents), `SHOP_ORIGIN` | Needs an **Apple Developer Program** membership. Create a Services ID, enable Sign in with Apple, add `<SHOP_ORIGIN>/account/auth/apple/callback` as a Return URL, and create a Sign-in-with-Apple key (`.p8`). The shop mints Apple's ES256 client secret from the key at boot (re-minted each deploy, inside Apple's 6-month window). The button appears only when all five are set. |
+| **PayPal checkout** | A native PayPal button on `/checkout` (PayPal Orders v2 — create / approve / capture), distinct from PayPal-through-Stripe. | `PAYPAL_CLIENT_ID`, `PAYPAL_SECRET` (a PayPal REST app), `PAYPAL_WEBHOOK_ID`, `PAYPAL_ENV` (`sandbox`\|`live`); Stripe checkout must also be live | The shop exchanges the OAuth2 token and creates / captures orders server-side; the button drives `/checkout/paypal/create` + `/checkout/paypal/capture`. Point a PayPal webhook at `/api/webhooks/paypal` (verified through PayPal's API). Allow `www.paypal.com` in your CSP `script-src` / `frame-src` (as you would `js.stripe.com`). |
 
 **Planned / not available:**
 
-- **PayPal** — a separate adapter (Orders v2 + its own webhook); planned.
 - **Shop Pay / "Sign in with Shop"** — **not available** to a self-hosted,
   non-Shopify store: the credentials only issue from a Shopify Admin and payment
   flows through Shopify Payments. There is no path to enable it here.

package/lib/admin.js

@@ -400,22 +400,90 @@ function mount(router, deps) {
 
   // ---- inventory ------------------------------------------------------
 
-  router.post("/admin/inventory", W("inventory.create", async function (req, res) {
-    var body = req.body || {};
-    if (!body.sku) throw new TypeError("admin.inventory.create: body.sku required");
-    var inv = await catalog.inventory.create(body.sku, body);
-    _json(res, 201, inv);
-    return Object.assign({ id: body.sku }, inv);
-  }));
+  // Inventory list — JSON for the bearer token, HTML console for a signed-in
+  // browser. `?low=1` filters to SKUs at/below their low-stock threshold.
+  router.get("/admin/inventory", _pageOrApi(true,
+    R(async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var page = await catalog.inventory.list({ low_only: !!(url && url.searchParams.get("low")), limit: 500 });
+      _json(res, 200, page);
+    }),
+    async function (req, res) {
+      var url = req.url ? new URL(req.url, "http://localhost") : null;
+      var low = !!(url && url.searchParams.get("low"));
+      var page = await catalog.inventory.list({ low_only: low, limit: 500 });
+      _sendHtml(res, 200, renderAdminInventory({
+        shop_name: deps.shop_name, nav_available: navAvailable,
+        inventory: page.rows || [], low: low,
+        notice: url && url.searchParams.get("err") ? "That SKU wasn't found — nothing was changed." : null,
+        updated: !!(url && url.searchParams.get("updated")),
+        created: !!(url && url.searchParams.get("created")),
+      }));
+    },
+  ));
 
-  router.post("/admin/inventory/:sku/restock", W("inventory.restock", async function (req, res) {
-    var qty = parseInt((req.body || {}).qty, 10);
-    if (!Number.isFinite(qty)) throw new TypeError("admin.inventory.restock: body.qty required (integer)");
-    var inv = await catalog.inventory.restock(req.params.sku, qty);
-    if (!inv) return _problem(res, 404, "inventory-not-found");
-    _json(res, 200, inv);
-    return Object.assign({ id: req.params.sku }, inv);
-  }));
+  router.post("/admin/inventory", _pageOrApi(false,
+    W("inventory.create", async function (req, res) {
+      var body = req.body || {};
+      if (!body.sku) throw new TypeError("admin.inventory.create: body.sku required");
+      var inv = await catalog.inventory.create(body.sku, body);
+      _json(res, 201, inv);
+      return Object.assign({ id: body.sku }, inv);
+    }),
+    async function (req, res) {
+      var body = req.body || {};
+      try {
+        if (!body.sku) throw new TypeError("sku required");
+        await catalog.inventory.create(body.sku, { stock_on_hand: parseInt(body.stock_on_hand, 10) || 0 });
+      } catch (e) {
+        if (e instanceof TypeError || /exists|duplicate|UNIQUE/i.test(e.message || "")) {
+          var page = await catalog.inventory.list({ limit: 500 });
+          return _sendHtml(res, 400, renderAdminInventory({
+            shop_name: deps.shop_name, nav_available: navAvailable, inventory: page.rows || [],
+            notice: (e && e.message) || "Couldn't create that SKU.",
+          }));
+        }
+        throw e;
+      }
+      b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.create", outcome: "success", metadata: { sku: body.sku } });
+      _redirect(res, "/admin/inventory?created=1");
+    },
+  ));
+
+  router.post("/admin/inventory/:sku/restock", _pageOrApi(false,
+    W("inventory.restock", async function (req, res) {
+      var qty = parseInt((req.body || {}).qty, 10);
+      if (!Number.isFinite(qty)) throw new TypeError("admin.inventory.restock: body.qty required (integer)");
+      var inv = await catalog.inventory.restock(req.params.sku, qty);
+      if (!inv) return _problem(res, 404, "inventory-not-found");
+      _json(res, 200, inv);
+      return Object.assign({ id: req.params.sku }, inv);
+    }),
+    async function (req, res) {
+      // Browser row form: restock by qty (when > 0) and/or set the low-stock
+      // threshold (when the field is non-empty; blank clears it). A bad sku is
+      // a no-op notice, never a 500.
+      var body = req.body || {};
+      var sku = req.params.sku;
+      var changed = false;
+      try {
+        var qty = parseInt(body.qty, 10);
+        if (Number.isFinite(qty) && qty > 0) { if (await catalog.inventory.restock(sku, qty)) changed = true; }
+        if (Object.prototype.hasOwnProperty.call(body, "threshold")) {
+          var raw = String(body.threshold).trim();
+          var threshold = raw === "" ? null : parseInt(raw, 10);
+          if (threshold === null || (Number.isInteger(threshold) && threshold >= 0)) {
+            if (await catalog.inventory.setThreshold(sku, threshold)) changed = true;
+          }
+        }
+      } catch (e) { if (!(e instanceof TypeError)) throw e; }
+      // restock / setThreshold return null for an unknown SKU — don't report
+      // success on a stale/tampered form to a non-existent SKU.
+      if (!changed) return _redirect(res, "/admin/inventory?err=1");
+      b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".inventory.restock", outcome: "success", metadata: { sku: sku } });
+      _redirect(res, "/admin/inventory?updated=1");
+    },
+  ));
 
   // Per-SKU low-stock threshold. Body `{ threshold }` — null clears.
   router.patch("/admin/inventory/:sku/threshold", W("inventory.set_threshold", async function (req, res) {
@@ -1497,6 +1565,9 @@ var DASHBOARD_LAYOUT =
   "    .review-stars { color:#c9821f; letter-spacing:.1em; }\n" +
   "    .review-reject { display:inline-flex; gap:.4rem; align-items:center; }\n" +
   "    .review-reject input { padding:.45rem .6rem; border:1px solid var(--hair); border-radius:6px; font-size:.82rem; }\n" +
+  "    .inv-row-form { display:flex; gap:.4rem; align-items:center; }\n" +
+  "    .inv-row-form input { padding:.4rem .5rem; border:1px solid var(--hair); border-radius:6px; font-size:.82rem; }\n" +
+  "    tr.row--low td { background:#fff8e1; }\n" +
   "    .nav-cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(14rem,1fr)); gap:1rem; }\n" +
   "    .nav-card { display:block; background:var(--paper); border:1px solid var(--hair); border-radius:8px; padding:1.4rem; text-decoration:none; color:var(--ink); }\n" +
   "    .nav-card:hover { border-color:var(--accent); box-shadow:0 8px 20px -12px rgba(0,0,0,.25); }\n" +
@@ -1677,6 +1748,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "home",         href: "/admin",              label: "Home" },
   { key: "dashboard",    href: "/admin/dashboard",    label: "Dashboard" },
   { key: "products",     href: "/admin/products",     label: "Products" },
+  { key: "inventory",    href: "/admin/inventory",    label: "Inventory" },
   { key: "orders",       href: "/admin/orders",       label: "Orders" },
   { key: "returns",      href: "/admin/returns",      label: "Returns",      requires: "returns" },
   { key: "reviews",      href: "/admin/reviews",      label: "Reviews",      requires: "reviews" },
@@ -1785,8 +1857,8 @@ var INTEGRATIONS_CATALOG = [
     set: "GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, SHOP_ORIGIN. Add <SHOP_ORIGIN>/account/auth/google/callback as a Google OAuth redirect URI." },
   { key: "apple_signin",     name: "Sign in with Apple",      enables: "A “Continue with Apple” button on the account login page.",
     set: "APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_CLIENT_ID (your Services ID), APPLE_PRIVATE_KEY (the .p8 key contents), SHOP_ORIGIN. Add <SHOP_ORIGIN>/account/auth/apple/callback as a Return URL on the Services ID. Requires an Apple Developer Program membership." },
-  { key: "paypal",           name: "PayPal checkout",         enables: "Native PayPal create / capture via PayPal Orders v2 (distinct from PayPal-through-Stripe). The on-page button and webhook endpoint land in a follow-up release.",
-    set: "PAYPAL_CLIENT_ID, PAYPAL_SECRET (a PayPal REST app), PAYPAL_WEBHOOK_ID, PAYPAL_ENV (sandbox|live). Card checkout (Stripe) must be live too." },
+  { key: "paypal",           name: "PayPal checkout",         enables: "A native PayPal button on the checkout page (create / capture via PayPal Orders v2) — distinct from PayPal-through-Stripe.",
+    set: "PAYPAL_CLIENT_ID, PAYPAL_SECRET (a PayPal REST app), PAYPAL_WEBHOOK_ID, PAYPAL_ENV (sandbox|live). Card checkout (Stripe) must be live too. Point a PayPal webhook at /api/webhooks/paypal." },
 ];
 
 function renderAdminIntegrations(opts) {
@@ -2178,6 +2250,55 @@ function renderAdminReviews(opts) {
   return _renderAdminShell(opts.shop_name, "Reviews", body, "reviews", opts.nav_available);
 }
 
+function renderAdminInventory(opts) {
+  opts = opts || {};
+  var rows = opts.inventory || [];
+  var created = opts.created ? "<div class=\"banner banner--ok\">SKU created.</div>" : "";
+  var updated = opts.updated ? "<div class=\"banner banner--ok\">Inventory updated.</div>" : "";
+  var notice  = opts.notice  ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (opts.low ? "" : " chip--on") + "\" href=\"/admin/inventory\">All</a>" +
+    "<a class=\"chip" + (opts.low ? " chip--on" : "") + "\" href=\"/admin/inventory?low=1\">Low stock</a>" +
+    "</div>";
+
+  var body = rows.map(function (r) {
+    var available = (r.stock_on_hand || 0) - (r.stock_held || 0);
+    var th = r.low_stock_threshold;
+    var isLow = th != null && available <= th;
+    var thVal = th == null ? "" : String(th);
+    return "<tr" + (isLow ? " class=\"row--low\"" : "") + ">" +
+      "<td><code class=\"order-id\">" + _htmlEscape(r.sku) + "</code>" + (isLow ? " <span class=\"status-pill pending\">low</span>" : "") + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.stock_on_hand)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.stock_held)) + "</td>" +
+      "<td class=\"num\"><strong>" + _htmlEscape(String(available)) + "</strong></td>" +
+      "<td>" +
+        "<form method=\"post\" action=\"/admin/inventory/" + _htmlEscape(r.sku) + "/restock\" class=\"inv-row-form\">" +
+          "<input type=\"number\" name=\"qty\" min=\"1\" placeholder=\"+ qty\" style=\"width:6rem;\">" +
+          "<input type=\"number\" name=\"threshold\" min=\"0\" value=\"" + _htmlEscape(thVal) + "\" placeholder=\"alert ≤\" title=\"low-stock threshold (blank clears)\" style=\"width:6rem;\">" +
+          "<button class=\"btn btn--ghost\" type=\"submit\">Save</button>" +
+        "</form>" +
+      "</td></tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th>SKU</th><th class=\"num\">On hand</th><th class=\"num\">Held</th><th class=\"num\">Available</th><th>Restock / threshold</th></tr></thead><tbody>" + body + "</tbody></table></div>"
+    : "<p class=\"empty\">No inventory rows" + (opts.low ? " below threshold" : " yet") + ".</p>";
+
+  var createForm =
+    "<div class=\"panel\" style=\"margin-top:1.5rem; max-width:34rem;\">" +
+      "<h3 style=\"font-size:.95rem; margin-bottom:.75rem;\">Track a new SKU</h3>" +
+      "<form method=\"post\" action=\"/admin/inventory\">" +
+        _setupField("SKU", "sku", "", "text", "Must match a variant SKU.", " maxlength=\"128\" required") +
+        _setupField("Starting stock on hand", "stock_on_hand", "0", "number", "", " min=\"0\"") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Track SKU</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Inventory</h2>" + created + updated + notice + chips + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Inventory", bodyHtml, "inventory", opts.nav_available);
+}
+
 module.exports = {
   mount:           mount,
   AUDIT_NAMESPACE: AUDIT_NAMESPACE,
@@ -2187,6 +2308,7 @@ module.exports = {
   renderAdminSetup:        renderAdminSetup,
   renderAdminIntegrations: renderAdminIntegrations,
   renderAdminProducts:     renderAdminProducts,
+  renderAdminInventory:    renderAdminInventory,
   renderAdminOrders:       renderAdminOrders,
   renderAdminOrder:        renderAdminOrder,
   renderAdminReturns:      renderAdminReturns,

package/lib/catalog.js

@@ -629,6 +629,22 @@ function _inventoryModule(query, opts) {
       return r.rows[0] || null;
     },
 
+    // Operator-facing inventory list (sku ASC), optionally only the SKUs at
+    // or below their configured low-stock threshold. Capped + uncursored —
+    // it backs the admin inventory console, not a hot path.
+    list: async function (listOpts) {
+      listOpts = listOpts || {};
+      var limit = listOpts.limit == null ? 200 : listOpts.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > 1000) {
+        throw new TypeError("catalog.inventory.list: limit must be 1..1000");
+      }
+      var sql = listOpts.low_only
+        ? "SELECT * FROM inventory WHERE low_stock_threshold IS NOT NULL AND " +
+          "(stock_on_hand - stock_held) <= low_stock_threshold ORDER BY sku ASC LIMIT ?1"
+        : "SELECT * FROM inventory ORDER BY sku ASC LIMIT ?1";
+      return { rows: (await query(sql, [limit])).rows };
+    },
+
     // Hot-path decrement happens via the Worker's InventoryLock
     // Durable Object — this primitive is for admin restock / release
     // operations that don't need the DO serialization. Concurrent

package/lib/storefront.js

@@ -1620,6 +1620,15 @@ function renderCheckoutForm(opts) {
     });
   }
   var body = _render(CHECKOUT_PAGE, { subtotal: subtotal });
+  // When PayPal is configured, append its button below the card form. The
+  // block is built as raw HTML (appended after the strict render) so the SDK
+  // script + handlers survive; the client-id is the only interpolation and is
+  // attribute-escaped. The PayPal button's createOrder/onApprove drive the
+  // /checkout/paypal/create + /capture routes. (Operators must allow
+  // www.paypal.com in their CSP script-src/frame-src, as for js.stripe.com.)
+  if (opts.paypal_client_id) {
+    body += _paypalCheckoutBlock(opts.paypal_client_id, totals.currency);
+  }
   return _wrap({
     title:      "Checkout",
     shop_name:  shopName,
@@ -1629,6 +1638,31 @@ function renderCheckoutForm(opts) {
   });
 }
 
+function _paypalCheckoutBlock(clientId, currency) {
+  var esc = b.template.escapeHtml;
+  var cid = esc(String(clientId));
+  var cur = esc(String(currency || "USD"));
+  return "\n<div class=\"checkout-paypal\" style=\"max-width:32rem;margin:1.5rem auto 0;\">" +
+    "<div class=\"pay-card__divider\"><span>or pay with PayPal</span></div>" +
+    "<div id=\"paypal-button-container\"></div>" +
+    "<p id=\"paypal-error\" class=\"auth-form__message auth-form__message--err\" hidden></p>" +
+    "</div>" +
+    "<script src=\"https://www.paypal.com/sdk/js?client-id=" + cid + "&currency=" + cur + "&intent=capture\"></script>" +
+    "<script>(function(){" +
+    "if(!window.paypal){return;}" +
+    "var form=document.querySelector('.checkout-page form');" +
+    "var errEl=document.getElementById('paypal-error');" +
+    "function vals(){var d={};['email','name','country','state','postal'].forEach(function(k){var el=form&&form.elements[k];if(el){d[k]=el.value;}});return d;}" +
+    "function showErr(m){if(errEl){errEl.hidden=false;errEl.textContent=m||'PayPal checkout could not be completed.';}}" +
+    "paypal.Buttons({" +
+    "onClick:function(_d,actions){if(form&&form.reportValidity&&!form.reportValidity()){return actions.reject();}return actions.resolve();}," +
+    "createOrder:function(){return fetch('/checkout/paypal/create',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(vals())}).then(function(r){return r.json();}).then(function(d){if(!d.id){throw new Error(d.error||'create failed');}return d.id;});}," +
+    "onApprove:function(data){return fetch('/checkout/paypal/capture',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({paypal_order_id:data.orderID})}).then(function(r){return r.json();}).then(function(d){if(d.redirect){window.location.href=d.redirect;}else{showErr(d.error);}});}," +
+    "onError:function(){showErr();}" +
+    "}).render('#paypal-button-container');" +
+    "})();</script>\n";
+}
+
 // Stripe Elements payment page — embeds Stripe.js + a minimal
 // mount block. The publishable key is operator-supplied (env
 // `STRIPE_PUBLISHABLE_KEY` → forwarded into the rendered HTML).
@@ -2808,7 +2842,7 @@ function mount(router, deps) {
         return res.end ? res.end() : res.send("");
       }
       var totals = pricing.totals(c, lines, {});
-      _send(res, 200, renderCheckoutForm({ lines: lines, totals: totals, shop_name: shopName, theme: theme }));
+      _send(res, 200, renderCheckoutForm({ lines: lines, totals: totals, shop_name: shopName, theme: theme, paypal_client_id: deps.paypal ? deps.paypal_client_id : null }));
     });
 
     router.post("/checkout", async function (req, res) {
@@ -2867,6 +2901,76 @@ function mount(router, deps) {
       }
     });
 
+    // PayPal express checkout (Orders v2). Mounts when the PayPal adapter is
+    // wired. The pay-page PayPal button drives two AJAX calls: `create` opens
+    // a PayPal order for the current cart (returns its id for the SDK to
+    // approve in the popup); `capture` finalizes after approval and advances
+    // the local order to paid. Both read the session cart; the button posts
+    // the same ship_to fields the card form collects.
+    if (deps.paypal) {
+      router.post("/checkout/paypal/create", async function (req, res) {
+        function _json(status, obj) {
+          res.status(status);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var s = JSON.stringify(obj);
+          return res.end ? res.end(s) : res.send(s);
+        }
+        var body = req.body || {};
+        var sid = _readSidCookie(req);
+        if (!sid) return _json(400, { error: "no-session" });
+        var c = await deps.cart.bySession(sid);
+        if (!c || c.status !== "active") return _json(409, { error: "no-active-cart" });
+        var shipTo = {
+          country: (body.country || "").toUpperCase(),
+          state:   body.state ? String(body.state).toUpperCase() : undefined,
+          postal:  body.postal || undefined,
+        };
+        try {
+          var defaultShipId = typeof deps.default_shipping_id === "function"
+            ? await deps.default_shipping_id() : deps.default_shipping_id;
+          var created = await deps.checkout.createPaypalOrder({
+            cart_id:              c.id,
+            ship_to:              shipTo,
+            selected_shipping_id: body.selected_shipping_id || defaultShipId || "std",
+            customer:             { email: body.email, name: body.name },
+            idempotency_key:      "paypal:" + c.id + ":" + b.uuid.v7(),
+            return_url:           body.return_url || undefined,
+            cancel_url:           body.cancel_url || undefined,
+          });
+          // The PayPal JS SDK's createOrder expects `{ id }`.
+          return _json(200, { id: created.paypal_order_id, order_id: created.order.id });
+        } catch (e) {
+          return _json(e instanceof TypeError ? 400 : 502, { error: (e && e.message) || "paypal-create-failed" });
+        }
+      });
+
+      router.post("/checkout/paypal/capture", async function (req, res) {
+        function _json(status, obj) {
+          res.status(status);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var s = JSON.stringify(obj);
+          return res.end ? res.end(s) : res.send(s);
+        }
+        var body = req.body || {};
+        var paypalOrderId = body.paypal_order_id || body.orderID || body.orderId;
+        if (typeof paypalOrderId !== "string" || !paypalOrderId.length) return _json(400, { error: "paypal_order_id required" });
+        try {
+          var result = await deps.checkout.capturePaypalOrder(paypalOrderId);
+          if (!result.order) return _json(404, { error: "order-not-found" });
+          // Only redirect to the order page when the capture actually
+          // completed (or the order is already paid). A non-completing capture
+          // leaves the order pending — surface it as an error so the client
+          // doesn't show success for an unpaid order.
+          if (!result.handled && result.order.status !== "paid") {
+            return _json(502, { error: "capture-incomplete", status: result.order.status });
+          }
+          return _json(200, { order_id: result.order.id, status: result.order.status, redirect: "/orders/" + result.order.id });
+        } catch (e) {
+          return _json(502, { error: (e && e.message) || "paypal-capture-failed" });
+        }
+      });
+    }
+
     router.get("/pay/:order_id", async function (req, res) {
       var orderId = req.params && req.params.order_id;
       if (!orderId) return _send(res, 404, renderNotFound({ shop_name: shopName, theme: theme }));
@@ -2952,6 +3056,32 @@ function mount(router, deps) {
         return res.end ? res.end("handler error") : res.send("");
       }
     });
+
+    // PayPal webhook — the async backstop for captures completed/refunded out
+    // of band (the create/capture flow is primary). Verified server-to-server
+    // through PayPal's API (handlePaypalEvent), so unlike Stripe there is no
+    // edge HMAC pre-check; the raw body is captured upstream by
+    // webhookRawBodyCapture. Mounts only when the PayPal adapter is wired.
+    if (deps.paypal) {
+      router.post("/api/webhooks/paypal", async function (req, res) {
+        var raw = Buffer.isBuffer(req.body) ? req.body.toString("utf8")
+          : (typeof req.body === "string" ? req.body : "");
+        try {
+          var result = await deps.checkout.handlePaypalEvent({ headers: req.headers || {}, rawBody: raw });
+          res.status(200);
+          res.setHeader && res.setHeader("content-type", "application/json; charset=utf-8");
+          var payload = JSON.stringify({ ok: true, handled: !!(result && result.handled) });
+          return res.end ? res.end(payload) : res.send(payload);
+        } catch (e) {
+          if (e && e.code === "WEBHOOK_INVALID") {
+            res.status(400);
+            return res.end ? res.end("invalid signature") : res.send("");
+          }
+          res.status(500);
+          return res.end ? res.end("handler error") : res.send("");
+        }
+      });
+    }
   }
 
   // ---- customer accounts (passkey-only) ------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {