@blamejs/blamejs-shop 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.10 (2026-05-30) — **Order discounts are split across lines for accurate partial refunds.** When an order carries a cart-level discount, the admin console now records how that discount split across the order's lines — proportional to each line's value — so a later partial refund of one line knows that line's discounted share rather than the whole-order amount. A new read-only Discount splits screen shows the per-line breakdown for an order. This is back-office bookkeeping recorded after the order is placed; it has no effect on what the shopper is charged, and an order with no discount records nothing. **Added:** *Per-line discount allocation + admin view* — An order that carried an automatic cart discount now gets a recorded breakdown of how that discount split across its lines — proportional to each line's subtotal, summing exactly to the discount. A read-only Discount splits admin screen shows the breakdown for an order. The recording runs after the order is placed and never affects the charged amount; an order with no discount records nothing.
+
 - v0.3.9 (2026-05-30) — **Automatic discounts now apply at checkout.** The automatic-discount rules you define in the admin console — an amount or percentage off a cart that meets a threshold — now reduce the order total at checkout. When a rule matches, the discount is applied (capped so it never exceeds the order subtotal) and shown in the quote the shopper pays; when no rule matches, or none are defined, the total is exactly as before, so a store that has not set up rules is unaffected. The admin screen for managing rules already shipped; this wires it through to the checkout quote and the charge. **Added:** *Automatic cart discounts at checkout* — When a cart matches a configured automatic-discount rule, the checkout reduces the order total by the rule's saving — capped to the order subtotal so the total is never negative — and the reduced amount is what the shopper is charged. With no matching rule, or no rules defined, the order total is unchanged, so the change stays invisible until you set rules up; any rule-engine error degrades to no discount rather than blocking checkout.
 
 - v0.3.8 (2026-05-30) — **Update the vendored blamejs runtime to v0.14.6.** Refreshes the vendored blamejs runtime from v0.14.5 to v0.14.6, a maintenance update. The createApp request-lifecycle security stack the shop composes — CSRF, fetch-metadata, body-parser, cookies, rate limiting — is unchanged in default behavior. v0.14.6 adds opt-in RFC 9457 problem+json and onDeny response hooks to the access-refusal middleware (defaults unchanged, so nothing the shop relies on shifts) and corrects a few internal export and bearer-scope paths. No operator action is required. **Changed:** *Vendored blamejs runtime updated to v0.14.6* — The pinned blamejs runtime moves from v0.14.5 to v0.14.6. The middleware the storefront and admin compose keeps its current default behavior; the release adds opt-in problem-details / onDeny response hooks to the refusal middleware and fixes internal export and bearer-scope paths. No behavior change for the shop.

package/lib/admin.js

@@ -451,7 +451,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -3741,6 +3741,59 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- discount allocations -------------------------------------------
+
+  // Read-only console for the per-line discount-allocation audit trail.
+  // When a placed order carried a cart-level discount, checkout records
+  // (post-commit) how that discount split across the order's lines, so a
+  // later partial refund knows each line's discounted share. Allocations
+  // are SYSTEM-WRITTEN — there's no create/edit here; the operator looks
+  // up an order id and reads back the recorded breakdown. Endpoints are
+  // omitted entirely when no discountAllocation primitive is wired.
+  var discountAllocation = deps.discountAllocation || null;
+  if (discountAllocation) {
+    // Look an order's recorded allocations up by id. Content-negotiates:
+    // bearer → JSON (the raw rows, unchanged for tooling); signed-in
+    // browser → the lookup form plus the rendered breakdown tables.
+    //
+    // The order id is a defensive request-shape reader — an empty / over-
+    // long / control-byte id makes allocationsForOrder throw a TypeError,
+    // which surfaces as an empty result + a notice, never a 500.
+    async function _lookupAllocations(orderId) {
+      if (typeof orderId !== "string" || orderId === "") return [];
+      try {
+        return await discountAllocation.allocationsForOrder(orderId);
+      } catch (e) {
+        if (e instanceof TypeError) return [];   // malformed id — treat as "nothing recorded"
+        throw e;
+      }
+    }
+
+    router.get("/admin/discount-allocation", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var orderId = (url && url.searchParams.get("order_id")) || "";
+        var rows = await _lookupAllocations(orderId);
+        _json(res, 200, { order_id: orderId, rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var orderId = (url && url.searchParams.get("order_id")) || "";
+        var rows = orderId ? await _lookupAllocations(orderId) : [];
+        var notice = (orderId && rows.length === 0)
+          ? "No discount allocations recorded for that order."
+          : null;
+        _sendHtml(res, 200, renderAdminDiscountAllocation({
+          shop_name:     deps.shop_name,
+          nav_available: navAvailable,
+          order_id:      orderId,
+          allocations:   rows,
+          notice:        notice,
+        }));
+      },
+    ));
+  }
+
   // ---- announcements --------------------------------------------------
   // Sitewide promo/notice strip. Content-negotiated like the other console
   // screens: bearer → the JSON contract; signed-in browser → the HTML
@@ -6135,6 +6188,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "subscriptions", href: "/admin/subscription-plans", label: "Subscriptions", requires: "subscriptions" },
   { key: "collections",  href: "/admin/collections",  label: "Collections",  requires: "collections" },
   { key: "discounts",    href: "/admin/discounts",    label: "Discounts",    requires: "autoDiscount" },
+  { key: "discount-allocation", href: "/admin/discount-allocation", label: "Discount splits", requires: "discountAllocation" },
   { key: "quantity-discounts", href: "/admin/quantity-discounts", label: "Quantity breaks", requires: "quantityDiscounts" },
   { key: "tax",          href: "/admin/tax-rates",    label: "Tax",          requires: "taxRates" },
   { key: "tax-filings",  href: "/admin/tax-filings",  label: "Tax filings",  requires: "salesTaxFilings" },
@@ -8674,6 +8728,60 @@ function renderAdminCollections(opts) {
   return _renderAdminShell(opts.shop_name, "Collections", bodyHtml, "collections", opts.nav_available);
 }
 
+// Read-only view of the per-line discount-allocation audit trail for one
+// order. The operator looks an order up by id; each recorded allocation
+// renders as a header (source, kind, total, recorded-at) plus a table of
+// the per-line breakdown. Allocations are system-written by checkout —
+// there's no create/edit affordance here. Amounts are exact minor-unit
+// integers (the audit row carries no currency; the figures are the same
+// integers the refund math reads back), so the operator sees the precise
+// recorded split rather than a rounded display value.
+function renderAdminDiscountAllocation(opts) {
+  opts = opts || {};
+  var orderId = typeof opts.order_id === "string" ? opts.order_id : "";
+  var allocations = opts.allocations || [];
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var lookupForm =
+    "<div class=\"panel mw-40\">" +
+      "<h3 class=\"subhead\">Look up an order</h3>" +
+      "<p class=\"meta\">When an order carried a cart-level discount, the split across its lines is recorded here for refund precision. Enter an order id to see its recorded allocations.</p>" +
+      "<form method=\"get\" action=\"/admin/discount-allocation\">" +
+        _setupField("Order id", "order_id", orderId, "text", "The order's id (shown on the order detail page).", " maxlength=\"200\"") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Look up</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var results = "";
+  if (allocations.length) {
+    results = allocations.map(function (a) {
+      var breakdown = Array.isArray(a.breakdown) ? a.breakdown : [];
+      var lineRows = breakdown.map(function (l) {
+        return "<tr>" +
+          "<td><code class=\"order-id\">" + _htmlEscape(String(l.line_id)) + "</code></td>" +
+          "<td class=\"num\">" + _htmlEscape(String(l.allocated_minor)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(l.remaining_minor)) + "</td>" +
+        "</tr>";
+      }).join("");
+      var lineTable = breakdown.length
+        ? "<table><thead><tr><th scope=\"col\">Line</th><th scope=\"col\" class=\"num\">Allocated (minor)</th><th scope=\"col\" class=\"num\">Remaining (minor)</th></tr></thead><tbody>" + lineRows + "</tbody></table>"
+        : "<p class=\"empty\">This allocation has no recorded lines.</p>";
+      return "<div class=\"panel mt\">" +
+        "<h3 class=\"subhead\">" + _htmlEscape(a.source || "—") + "</h3>" +
+        "<p class=\"meta\">" +
+          "Split: <strong>" + _htmlEscape(a.kind || "—") + "</strong>" +
+          " &middot; Total: <strong>" + _htmlEscape(String(a.total_minor)) + "</strong> minor units" +
+          " &middot; Recorded: " + _htmlEscape(_fmtDate(a.applied_at)) +
+        "</p>" +
+        lineTable +
+      "</div>";
+    }).join("");
+  }
+
+  var bodyHtml = "<section><h2>Discount splits</h2>" + notice + lookupForm + results + "</section>";
+  return _renderAdminShell(opts.shop_name, "Discount splits", bodyHtml, "discount-allocation", opts.nav_available);
+}
+
 // A <datetime-local> form value → epoch ms (integer) for the lib's
 // starts_at/expires_at, or null when blank/unparseable (open-ended). The
 // announcement primitive validates the result; a blank schedule field just
@@ -9564,6 +9672,7 @@ module.exports = {
   renderAdminShipping:     renderAdminShipping,
   renderAdminShippingZone: renderAdminShippingZone,
   renderAdminDiscounts:    renderAdminDiscounts,
+  renderAdminDiscountAllocation: renderAdminDiscountAllocation,
   renderAdminQuantityDiscounts: renderAdminQuantityDiscounts,
   renderAdminQuantityDiscount:  renderAdminQuantityDiscount,
   renderAdminConfirm:      renderAdminConfirm,

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.9",
+  "version": "0.3.10",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/lib/checkout.js

@@ -157,6 +157,16 @@ function create(deps) {
   // rule's savings are a shipping concern and are left to the shipping
   // primitive, not folded into the subtotal discount here.
   var autoDiscount  = deps.autoDiscount || null;
+  // Optional discount-allocation recorder. When wired, a placed order
+  // that carried a cart-level discount gets a per-line breakdown of how
+  // that discount split across the order lines, recorded as a back-office
+  // audit row so a later partial refund knows each line's discounted
+  // share. POST-COMMIT + drop-silent: it runs after the order exists, in
+  // its own try/catch, so a recording failure can never fail, reverse, or
+  // change the charge of a placed order. No discount -> nothing recorded.
+  // Disabled when absent — the buy path is byte-identical to the un-wired
+  // flow.
+  var discountAllocation = deps.discountAllocation || null;
 
   // Reprice a list of cart lines through the quantity-discount engine.
   // Returns a shallow copy with `unit_amount_minor` overwritten by the
@@ -440,6 +450,72 @@ function create(deps) {
     }
   }
 
+  // Record HOW a cart-level order discount split across the order lines,
+  // for accounting + partial-refund precision. The recorded breakdown's
+  // per-line `allocated_minor` values sum exactly to the discount, so a
+  // later partial refund of one line can remove that line's share rather
+  // than the whole-order amount.
+  //
+  // POST-COMMIT + drop-silent — by design: the order is already placed
+  // (and, in the charged path, the PaymentIntent already exists) by the
+  // time this runs. The entire body is wrapped in one try/catch so a
+  // recording failure (bad input, DB error, an unmigrated table) can
+  // NEVER fail, reverse, or change the charge of a placed order. This is
+  // pure back-office bookkeeping with zero impact on the charged amount.
+  //
+  // No-op when: the recorder isn't wired, the order carried no discount
+  // (discount_minor <= 0), or the order has no lines to split across.
+  // The default split is `proportional` (by line subtotal) — the
+  // operator-readable "each line absorbs its share of the savings"
+  // distribution.
+  async function _recordDiscountAllocation(quote, orderLines, orderId) {
+    if (!discountAllocation ||
+        typeof discountAllocation.allocate !== "function" ||
+        typeof discountAllocation.recordAllocation !== "function") return;
+    try {
+      var discount = quote && quote.totals ? quote.totals.discount_minor : 0;
+      if (!Number.isInteger(discount) || discount <= 0) return;   // no discount -> record nothing
+      if (!Array.isArray(orderLines) || orderLines.length === 0) return;
+
+      // Build the allocate() line shape from the placed order lines. The
+      // line_id is the PERSISTED order-line id, so a later partial refund —
+      // which operates on order lines — can apply the breakdown directly
+      // without re-mapping by (variant, sku). The per-line subtotal is
+      // unit_amount_minor * qty — the same per-line
+      // figure pricing.subtotal summed into quote.totals.subtotal_minor,
+      // so the discount (clamped to <= subtotal upstream) never exceeds
+      // the total line weight.
+      var lines = [];
+      for (var i = 0; i < orderLines.length; i += 1) {
+        var l = orderLines[i];
+        var lineId = l.line_id != null ? l.line_id : l.id;
+        if (lineId == null) return;                                 // no stable id to key the breakdown on
+        lines.push({
+          line_id:        String(lineId),
+          subtotal_minor: l.unit_amount_minor * l.qty,
+          quantity:       l.qty,
+        });
+      }
+
+      var breakdown = discountAllocation.allocate({
+        lines:          lines,
+        discount_minor: discount,
+        kind:           "proportional",
+      });
+      await discountAllocation.recordAllocation({
+        order_id:        orderId,
+        discount_source: "auto_discount",
+        kind:            "proportional",
+        breakdown:       breakdown,
+        total_minor:     discount,
+      });
+    } catch (_e) {
+      // drop-silent — by design: the order is already placed; a failed
+      // allocation record is back-office bookkeeping and must never
+      // surface to the buyer or affect the charge.
+    }
+  }
+
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
   async function _buildQuote(input) {
@@ -619,6 +695,10 @@ function create(deps) {
         // placed order. Runs post-commit so a recording failure can't
         // reverse an order that's already paid.
         await _recordAutoDiscounts(quote, paidOrder.id, cartRow.customer_id || null);
+        // Best-effort: record how the cart-level discount split across the
+        // order lines (accounting + refund precision). Post-commit +
+        // drop-silent — no impact on the already-settled order.
+        await _recordDiscountAllocation(quote, paidOrder.lines, paidOrder.id);
         await cart.setStatus(quote.cart_id, "converted");
         var settled = await order.transition(paidOrder.id, "mark_paid", {
           reason: loy && !gc ? "loyalty:full" : "gift_card:full",
@@ -676,6 +756,11 @@ function create(deps) {
       // placed order. Runs post-commit so a recording failure can't
       // reverse or fail an order whose PaymentIntent already exists.
       await _recordAutoDiscounts(quote, createdOrder.id, cartRow.customer_id || null);
+      // Best-effort: record how the cart-level discount split across the
+      // order lines (accounting + refund precision). Post-commit +
+      // drop-silent — the PaymentIntent already exists; this never
+      // changes the charged amount.
+      await _recordDiscountAllocation(quote, createdOrder.lines, createdOrder.id);
 
       // Mark the cart converted so a refresh of the storefront
       // doesn't accidentally re-quote the same cart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "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": {