@blamejs/blamejs-shop 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.4 (2026-05-30) — **Sales-tax filings and remittance tracking in the admin console.** The admin console gains a Tax filings section for tracking sales-tax remittance across reporting periods. Open a filing period for a jurisdiction, compute the tax collected from completed orders in that window, then record the submission and the payment as you remit. Each filing carries a per-rate breakdown and an audit trail, and the list surfaces what's due soon or already overdue. A per-jurisdiction remittance report totals the tax owed across a date range. Every figure derives from completed orders — nothing in the storefront, cart, or checkout changes. **Added:** *Tax filings admin console* — A new Tax filings section tracks sales-tax remittance: open a filing period for a jurisdiction and reporting kind, compute the tax collected from completed orders in the window with a per-rate breakdown, then record submission and payment through the filing lifecycle. The list surfaces filings due soon or overdue, and a remittance report totals tax owed per jurisdiction across a date range. This is reporting only — it reads completed orders and changes nothing in checkout.
+
+- v0.3.3 (2026-05-30) — **Manage quantity-break (volume) pricing from the admin console.** The admin console gains a Quantity breaks section for creating and managing volume-pricing tier sets — buy-more-save-more rules scoped to a SKU, product, collection, vendor, category, or the whole store. Each set defines one or more quantity thresholds (e.g. buy 5, buy 10) with a percentage off, an amount off each unit, an amount off the line, or a fixed per-unit price, and can be marked exclusive or left to stack with others. A sample-price preview shows the discounted unit at each threshold before you commit, and sets archive and restore. The tiers take effect immediately on the product page, in the cart, and at checkout. **Added:** *Quantity Breaks admin console* — A new Quantity breaks section manages volume-pricing tier sets: create a set scoped to a SKU, product, collection, vendor, category, or globally; define one or more quantity thresholds with a percent-off, amount-off-each, amount-off-line, or fixed-per-unit discount; mark a set exclusive or let it stack. A sample-price preview shows the discounted unit at each threshold, and sets archive and restore. The tiers apply automatically on the product page, the cart, and at checkout.
+
 - v0.3.2 (2026-05-30) — **Creating a product lands you on its detail screen to finish setup.** Creating a product from the admin console now takes you straight to that product's detail screen — where you add a variant, set its price, and add stock — instead of returning you to the product list. A banner on the new product names the remaining steps to make it sellable. This removes the hunt-for-the-product-you-just-made step from the catalog setup flow. **Changed:** *Product create flows straight into editing* — Submitting the new-product form now redirects to the product's detail screen with a banner naming the next steps — add a variant with a SKU, set its price, and add stock — rather than bouncing back to the product list. Configuring a just-created product no longer requires finding it again first.
 
 - v0.3.1 (2026-05-30) — **Fix CSRF origin check refusing authenticated forms behind a TLS-terminating proxy.** The token-based CSRF protection added in 0.3.0 runs an Origin/Referer pre-check on every state-changing request. When the app is served behind a proxy that terminates TLS and forwards plain HTTP to the application — a CDN or load balancer, the standard production topology — the application saw the connection as HTTP and rebuilt its own origin as `http://<host>`, while the browser's request carried `Origin: https://<host>`. That bare scheme mismatch made the check refuse every legitimate same-origin POST as cross-origin, blocking sign-in and every account and admin form. The CSRF gate now trusts the forwarded protocol header — the same proxy stance the session cookies already use — so it derives the real public origin, and it matches against an explicit allowlist of the public origin(s), configurable via SHOP_PUBLIC_ORIGINS. The token cookie also regains its `__Host-` prefix over the forwarded HTTPS connection. No operator action is required for the default origin. **Fixed:** *Authenticated forms no longer refused behind a TLS-terminating proxy* — The CSRF origin pre-check derived the application origin from the raw proxied connection scheme, so a same-origin browser POST carrying `Origin: https://<host>` was refused as cross-origin under a CDN that forwards plain HTTP. The gate now trusts the forwarded `x-forwarded-proto` and matches against an explicit public-origin allowlist — `SHOP_PUBLIC_ORIGINS` (comma-separated), defaulting to the canonical origin — so sign-in and the account and admin forms submit correctly. The double-submit token cookie also regains its `__Host-` prefix over the forwarded HTTPS connection.

package/lib/admin.js

@@ -32,6 +32,7 @@
 
 var pricing = require("./pricing");
 var collectionsModule = require("./collections");
+var quantityDiscountsModule = require("./quantity-discounts");
 var { AsyncLocalStorage } = require("node:async_hooks");   // allow:non-shop-require — Node-core per-request context (no npm dep); the framework itself composes it in db-role-context / log. No b.* request-context primitive exists to wrap it.
 
 var b = require("./vendor/blamejs");
@@ -437,6 +438,7 @@ function mount(router, deps) {
   var pickLists      = deps.pickLists      || null;  // warehouse pick-list console disabled when absent
   var shippingLabels = deps.shippingLabels || null;  // per-shipment carrier-label record disabled when absent
   var splitShipments = deps.splitShipments || null;  // order split-shipment planner disabled when absent
+  var salesTaxFilings = deps.salesTaxFilings || null; // sales-tax-filing remittance console disabled when absent
 
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
@@ -444,7 +446,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, pickLists: !!pickLists };
+  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 };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -4581,6 +4583,252 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- sales tax filings ----------------------------------------------
+  //
+  // Post-checkout remittance bookkeeping. Each row aggregates completed
+  // orders that fell inside a filing window for one jurisdiction, then
+  // walks the lifecycle the authority expects: draft → computed (the
+  // aggregation snapshot) → submitted (filed) → paid (remittance cleared),
+  // with an amend path for a correction. The console never touches cart /
+  // checkout / order pricing — it reads orders the storefront already
+  // wrote. A missing sales_tax_filings table only surfaces when a route
+  // reads it (degrades to a notice), never at boot.
+  if (salesTaxFilings) {
+    // Translate a create form / JSON body into a defineFilingPeriod input.
+    // The four window fields are epoch-ms; strict integer parsing so a
+    // typo is a 400, never a silent zero.
+    function _filingPeriodInput(body) {
+      return {
+        jurisdiction: typeof body.jurisdiction === "string" ? body.jurisdiction.trim().toUpperCase() : body.jurisdiction,
+        kind:         typeof body.kind === "string" ? body.kind.trim() : body.kind,
+        period_start: _strictMinorInt(body.period_start, "salesTaxFilings", "period_start (epoch-ms)"),
+        period_end:   _strictMinorInt(body.period_end,   "salesTaxFilings", "period_end (epoch-ms)"),
+        due_date:     _strictMinorInt(body.due_date,     "salesTaxFilings", "due_date (epoch-ms)"),
+      };
+    }
+
+    // Build the list-screen model: the filtered filings, the upcoming-due
+    // strip, and the filter values echoed back into the form. A malformed
+    // filter (bad jurisdiction / status) throws TypeError in the primitive
+    // — map it to an empty list so the page renders the notice, never 500.
+    async function _filingsForBrowser(filter) {
+      try { return await salesTaxFilings.listFilings(filter); }
+      catch (e) { if (e instanceof TypeError) return []; throw e; }
+    }
+    async function _upcomingForBrowser() {
+      try { return await salesTaxFilings.upcomingDue({ days_ahead: 30 }); }
+      catch (e) { if (e instanceof TypeError) return []; throw e; }
+    }
+
+    router.get("/admin/tax-filings", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var filter = {};
+        var j = url && url.searchParams.get("jurisdiction");
+        var s = url && url.searchParams.get("status");
+        if (j) filter.jurisdiction = String(j).trim().toUpperCase();
+        if (s) filter.status = String(s).trim();
+        var rows;
+        try { rows = await salesTaxFilings.listFilings(filter); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        var s = url && url.searchParams.get("status");
+        var jurisdiction = j ? String(j).trim().toUpperCase() : null;
+        var status       = s ? String(s).trim() : null;
+        var filter = {};
+        if (jurisdiction) filter.jurisdiction = jurisdiction;
+        if (status)       filter.status = status;
+        var rows     = await _filingsForBrowser(filter);
+        var upcoming = await _upcomingForBrowser();
+        _sendHtml(res, 200, renderAdminTaxFilings({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          filings: rows, upcoming: upcoming,
+          jurisdiction: jurisdiction, status_filter: status,
+          kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+          created:  url && url.searchParams.get("created"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the filing." : null,
+        }));
+      },
+    ));
+
+    // Open a filing period → draft row. A duplicate (jurisdiction, kind,
+    // period_start) is refused by the primitive's UNIQUE index; surface it
+    // as a 400 notice rather than a 500.
+    router.post("/admin/tax-filings", _pageOrApi(false,
+      W("tax_filing.create", async function (req, res) {
+        var filing;
+        try { filing = await salesTaxFilings.defineFilingPeriod(_filingPeriodInput(req.body || {})); }
+        catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e.code === "SALES_TAX_FILING_DUPLICATE") return _problem(res, 409, "filing-duplicate", e.message);
+          throw e;
+        }
+        _json(res, 201, filing);
+        return { id: filing.id };
+      }),
+      async function (req, res) {
+        var filing;
+        try { filing = await salesTaxFilings.defineFilingPeriod(_filingPeriodInput(req.body || {})); }
+        catch (e) {
+          if (!(e instanceof TypeError) && e.code !== "SALES_TAX_FILING_DUPLICATE") throw e;
+          var rows     = await _filingsForBrowser({});
+          var upcoming = await _upcomingForBrowser();
+          return _sendHtml(res, 400, renderAdminTaxFilings({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            filings: rows, upcoming: upcoming,
+            kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+            notice: (e && e.message || "").replace(/^salesTaxFilings[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".tax_filing.create", outcome: "success", metadata: { id: filing.id } });
+        _redirect(res, "/admin/tax-filings/" + encodeURIComponent(filing.id) + "?created=1");
+      },
+    ));
+
+    // Per-jurisdiction remittance report over a [from, to] window. GET so
+    // the window lives in the URL (bookmarkable). A bad / missing range is
+    // a notice on the list page, not a 500.
+    router.get("/admin/tax-filings/report", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        if (!j) return _problem(res, 400, "bad-request", "jurisdiction required");
+        var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+        var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+        if (from == null || to == null) return _problem(res, 400, "bad-request", "from and to (epoch-ms) required");
+        var report;
+        try { report = await salesTaxFilings.auditReportForJurisdiction({ jurisdiction: String(j).trim().toUpperCase(), from: from, to: to }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, report);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        var jurisdiction = j ? String(j).trim().toUpperCase() : null;
+        // Parse the window defensively — a present-but-malformed epoch throws
+        // TypeError; treat it as unset so the window notice guides the operator
+        // (a bad range is a notice on this page, never a 500).
+        var from = null, to = null;
+        try {
+          from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+          to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+        } catch (e) { if (!(e instanceof TypeError)) throw e; }
+        var report = null, notice = null;
+        if (!jurisdiction) {
+          notice = "Enter a jurisdiction and a window to run a remittance report.";
+        } else if (from == null || to == null) {
+          notice = "Enter both a from and a to date (epoch-ms) for the report window.";
+        } else {
+          try { report = await salesTaxFilings.auditReportForJurisdiction({ jurisdiction: jurisdiction, from: from, to: to }); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; notice = (e.message || "").replace(/^salesTaxFilings[.:]\s*/, ""); }
+        }
+        _sendHtml(res, 200, renderAdminTaxFilingReport({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          report: report, jurisdiction: jurisdiction, notice: notice,
+        }));
+      },
+    ));
+
+    async function _filingDetailModel(id) {
+      return await salesTaxFilings.getFiling(id);
+    }
+
+    router.get("/admin/tax-filings/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var filing;
+        try { filing = await _filingDetailModel(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 404, "filing-not-found", e.message); throw e; }
+        if (!filing) return _problem(res, 404, "filing-not-found");
+        _json(res, 200, filing);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var filing;
+        try { filing = await _filingDetailModel(req.params.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; filing = null; }
+        if (!filing) return _sendHtml(res, 404, renderAdminTaxFilings({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          filings: [], upcoming: [], kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+          notice: "Filing not found.",
+        }));
+        _sendHtml(res, 200, renderAdminTaxFiling({
+          shop_name: deps.shop_name, nav_available: navAvailable, filing: filing,
+          computed: url && url.searchParams.get("computed"),
+          created:  url && url.searchParams.get("created"),
+          submitted: url && url.searchParams.get("submitted"),
+          paid:     url && url.searchParams.get("paid"),
+          amended:  url && url.searchParams.get("amended"),
+          notice:   (url && url.searchParams.get("err"))
+            ? String(url.searchParams.get("err_msg") || "That action couldn't be completed for the filing.")
+            : null,
+        }));
+      },
+    ));
+
+    // Lifecycle transitions — each is a browser POST that PRGs back to the
+    // detail. A bad transition (wrong status) or bad input is a ?err notice
+    // on the detail page, never a 500. The bearer JSON contract returns the
+    // updated filing (or a problem document).
+    function _filingActionRoute(suffix, audit, okParam, run) {
+      router.post("/admin/tax-filings/:id/" + suffix, _pageOrApi(false,
+        W("tax_filing." + audit, async function (req, res) {
+          var filing;
+          try { filing = await run(req.params.id, req.body || {}); }
+          catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            if (e.code === "SALES_TAX_FILING_NOT_FOUND") return _problem(res, 404, "filing-not-found", e.message);
+            if (e.code === "SALES_TAX_FILING_BAD_TRANSITION") return _problem(res, 409, "filing-bad-transition", e.message);
+            throw e;
+          }
+          _json(res, 200, filing);
+          return { id: filing.id };
+        }),
+        async function (req, res) {
+          var enc = encodeURIComponent(req.params.id);
+          try {
+            await run(req.params.id, req.body || {});
+          } catch (e) {
+            if (!(e instanceof TypeError) &&
+                e.code !== "SALES_TAX_FILING_NOT_FOUND" &&
+                e.code !== "SALES_TAX_FILING_BAD_TRANSITION") throw e;
+            var msg = (e && e.message || "").replace(/^salesTaxFilings[.:]\s*/, "");
+            return _redirect(res, "/admin/tax-filings/" + enc + "?err=1&err_msg=" + encodeURIComponent(msg));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".tax_filing." + audit, outcome: "success", metadata: { id: req.params.id } });
+          _redirect(res, "/admin/tax-filings/" + enc + "?" + okParam + "=1");
+        },
+      ));
+    }
+
+    _filingActionRoute("compute", "compute", "computed", function (id) {
+      return salesTaxFilings.computeFiling({ filing_id: id });
+    });
+    _filingActionRoute("submit", "submit", "submitted", function (id, body) {
+      return salesTaxFilings.recordSubmission({
+        filing_id:      id,
+        submission_ref: typeof body.submission_ref === "string" ? body.submission_ref.trim() : body.submission_ref,
+        submitted_by:   typeof body.submitted_by === "string" ? body.submitted_by.trim() : body.submitted_by,
+      });
+    });
+    _filingActionRoute("pay", "pay", "paid", function (id, body) {
+      return salesTaxFilings.recordPayment({
+        filing_id:     id,
+        payment_minor: _strictMinorInt(body.payment_minor, "salesTaxFilings", "payment_minor"),
+        payment_ref:   typeof body.payment_ref === "string" ? body.payment_ref.trim() : body.payment_ref,
+      });
+    });
+    _filingActionRoute("amend", "amend", "amended", function (id, body) {
+      return salesTaxFilings.markAmended({
+        filing_id: id,
+        reason:    typeof body.reason === "string" ? body.reason.trim() : body.reason,
+      });
+    });
+  }
+
   // Read a jurisdiction's rate history for the browser list. A null /
   // unset jurisdiction yields an empty list (the page shows the picker
   // form). A malformed jurisdiction throws TypeError in the primitive —
@@ -4965,6 +5213,254 @@ function mount(router, deps) {
     }
   }
 
+  // ---- quantity discounts ---------------------------------------------
+  // Tier-set CRUD for automatic per-line quantity breaks ("buy 5, save
+  // 10%"). The pricing engine already applies these at PDP / cart /
+  // checkout; this console manages the schedules. Content-negotiated like
+  // the other screens: bearer → the JSON contract; signed-in browser →
+  // the HTML table + create form. The detail screen renders the schedule,
+  // a rewrite form, archive/unarchive, and a sample tierBreakdown preview.
+  if (deps.quantityDiscounts) {
+    var quantityDiscounts = deps.quantityDiscounts;
+
+    // The engine has no get(id) — fetch a single set by walking the
+    // both-states list (operators have tens of sets, not thousands).
+    async function _qdSetById(id) {
+      var rows = await quantityDiscounts.list({ archived: null, limit: 200 });
+      for (var i = 0; i < rows.length; i += 1) {
+        if (rows[i].id === id) return rows[i];
+      }
+      return null;
+    }
+
+    // Map the ?archived= query to a list filter: 1/true → archived-only,
+    // 0/false → active-only, absent → both. The list view defaults to
+    // showing everything so a freshly-archived set stays visible.
+    function _qdFilter(archivedS) {
+      if (archivedS === "1" || archivedS === "true")  return { archived: true };
+      if (archivedS === "0" || archivedS === "false") return { archived: false };
+      return { archived: null };
+    }
+
+    // Parse the create / edit form's flat tier fields into the engine's
+    // tiers array. The form posts parallel arrays tier_min[] /
+    // tier_kind[] / tier_value[]; a row with every field blank is
+    // dropped (the spare append row), a row with any field set is kept
+    // and validated by the engine. min_quantity + value go through the
+    // strict integer reader so "", floats, and "12abc" are refused as a
+    // 4xx rather than coerced.
+    function _qdAsArray(v) {
+      if (v == null) return [];
+      return Array.isArray(v) ? v : [v];
+    }
+    function _qdTiersFromForm(body) {
+      var mins   = _qdAsArray(body.tier_min);
+      var kinds  = _qdAsArray(body.tier_kind);
+      var values = _qdAsArray(body.tier_value);
+      var n = Math.max(mins.length, kinds.length, values.length);
+      var tiers = [];
+      for (var i = 0; i < n; i += 1) {
+        var minRaw   = mins[i]   == null ? "" : String(mins[i]).trim();
+        var kindRaw  = kinds[i]  == null ? "" : String(kinds[i]).trim();
+        var valueRaw = values[i] == null ? "" : String(values[i]).trim();
+        if (minRaw === "" && kindRaw === "" && valueRaw === "") continue;   // spare blank row
+        tiers.push({
+          min_quantity:  _strictMinorInt(minRaw, "quantityDiscounts", "min_quantity"),
+          discount_kind: kindRaw,
+          value:         _strictMinorInt(valueRaw, "quantityDiscounts", "value"),
+        });
+      }
+      return tiers;
+    }
+
+    // Translate the create form / JSON body into a defineTier input. A
+    // body already carrying a tiers array (bearer JSON client) passes
+    // through untouched; the browser form is flattened first.
+    function _qdDefineInput(body) {
+      if (Array.isArray(body.tiers)) return body;
+      var scope = typeof body.scope === "string" ? body.scope.trim() : body.scope;
+      var input = {
+        scope:     scope,
+        exclusive: (body.exclusive === "on" || body.exclusive === "1" || body.exclusive === true),
+        tiers:     _qdTiersFromForm(body),
+      };
+      // scope_id is null exactly for global; the engine enforces the
+      // pairing. Trim + omit for global so a stray blank field doesn't
+      // trip the "must be null when global" check.
+      if (scope !== "global") {
+        input.scope_id = typeof body.scope_id === "string" ? body.scope_id.trim() : body.scope_id;
+      }
+      return input;
+    }
+
+    function _qdCleanMessage(e) {
+      return (e && e.message || "Couldn't save that tier set.").replace(/^quantityDiscounts[.:]\s*/, "");
+    }
+
+    async function _renderQdList(flags) {
+      flags = flags || {};
+      var rows = await quantityDiscounts.list(_qdFilter(flags.archived_filter));
+      return renderAdminQuantityDiscounts(Object.assign({
+        shop_name: deps.shop_name, nav_available: navAvailable,
+        scopes: quantityDiscountsModule.VALID_SCOPES, kinds: quantityDiscountsModule.VALID_KINDS,
+        tier_sets: rows,
+      }, flags));
+    }
+
+    router.get("/admin/quantity-discounts", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var archivedS = url && url.searchParams.get("archived");
+        _json(res, 200, { rows: await quantityDiscounts.list(_qdFilter(archivedS)) });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var archivedS = url && url.searchParams.get("archived");
+        _sendHtml(res, 200, await _renderQdList({
+          archived_filter: archivedS,
+          created:  url && url.searchParams.get("created"),
+          saved:    url && url.searchParams.get("saved"),
+          archived: url && url.searchParams.get("archived_ok"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the tier set." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/quantity-discounts", _pageOrApi(false,
+      W("quantity_discount.create", async function (req, res) {
+        var set = await quantityDiscounts.defineTier(_qdDefineInput(req.body || {}));
+        _json(res, 201, set);
+        return { id: set.id };
+      }),
+      async function (req, res) {
+        try {
+          await quantityDiscounts.defineTier(_qdDefineInput(req.body || {}));
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _sendHtml(res, 400, await _renderQdList({ notice: _qdCleanMessage(e) }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".quantity_discount.create", outcome: "success" });
+        _redirect(res, "/admin/quantity-discounts?created=1");
+      },
+    ));
+
+    // Detail: the tier set + its schedule, a rewrite form, archive /
+    // unarchive, and a sample-price tierBreakdown preview. A bad / unknown
+    // id is a 404 page, never a 500.
+    async function _qdDetailModel(id, sampleMinor) {
+      var set = await _qdSetById(id);
+      if (!set) return null;
+      var breakdown = null;
+      try {
+        breakdown = await quantityDiscounts.tierBreakdown({
+          scope:    set.scope,
+          scope_id: set.scope_id,
+          sample_unit_price_minor: (sampleMinor == null ? 1000 : sampleMinor),
+        });
+      } catch (_e) { breakdown = null; }
+      return { set: set, breakdown: breakdown, sample_minor: (sampleMinor == null ? 1000 : sampleMinor) };
+    }
+
+    router.get("/admin/quantity-discounts/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var set = await _qdSetById(req.params.id);
+        if (!set) return _problem(res, 404, "quantity-discount-not-found");
+        _json(res, 200, set);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var sampleS = url && url.searchParams.get("sample");
+        var sampleMinor = null;
+        if (sampleS != null && /^\d+$/.test(sampleS)) sampleMinor = Number(sampleS);
+        var model = await _qdDetailModel(req.params.id, sampleMinor);
+        if (!model) return _sendHtml(res, 404, renderAdminQuantityDiscount({
+          shop_name: deps.shop_name, nav_available: navAvailable, tier_set: null,
+        }));
+        _sendHtml(res, 200, renderAdminQuantityDiscount({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          kinds: quantityDiscountsModule.VALID_KINDS,
+          tier_set: model.set, breakdown: model.breakdown, sample_minor: model.sample_minor,
+          saved:  url && url.searchParams.get("saved"),
+          notice: (url && url.searchParams.get("err")) ? "That action couldn't be completed." : null,
+        }));
+      },
+    ));
+
+    router.post("/admin/quantity-discounts/:id/edit", _pageOrApi(false,
+      W("quantity_discount.update", async function (req, res) {
+        var set;
+        try { set = await quantityDiscounts.update(req.params.id, req.body || {}); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!set) return _problem(res, 404, "quantity-discount-not-found");
+        _json(res, 200, set);
+        return { id: set.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var body = req.body || {};
+        var enc = encodeURIComponent(id);
+        try {
+          var patch = {};
+          // exclusive_present marks the checkbox was rendered, so an
+          // unchecked box reads as false rather than "leave unchanged".
+          if (body.exclusive_present === "1") {
+            patch.exclusive = (body.exclusive === "on" || body.exclusive === "1");
+          }
+          var tiers = _qdTiersFromForm(body);
+          if (tiers.length > 0) patch.tiers = tiers;
+          if (Object.keys(patch).length === 0) return _redirect(res, "/admin/quantity-discounts/" + enc + "?err=1");
+          var set = await quantityDiscounts.update(id, patch);
+          if (!set) return _redirect(res, "/admin/quantity-discounts/" + enc + "?err=1");
+        } catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          return _redirect(res, "/admin/quantity-discounts/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".quantity_discount.update", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/quantity-discounts/" + enc + "?saved=1");
+      },
+    ));
+
+    router.post("/admin/quantity-discounts/:id/archive", _pageOrApi(false,
+      W("quantity_discount.archive", async function (req, res) {
+        var ok;
+        try { ok = await quantityDiscounts.archive(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!ok) return _problem(res, 404, "quantity-discount-not-found");
+        _json(res, 200, { ok: true });
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var ok = false;
+        try { ok = await quantityDiscounts.archive(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!ok) return _redirect(res, "/admin/quantity-discounts?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".quantity_discount.archive", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/quantity-discounts?archived_ok=1");
+      },
+    ));
+
+    router.post("/admin/quantity-discounts/:id/unarchive", _pageOrApi(false,
+      W("quantity_discount.unarchive", async function (req, res) {
+        var ok;
+        try { ok = await quantityDiscounts.unarchive(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        if (!ok) return _problem(res, 404, "quantity-discount-not-found");
+        _json(res, 200, { ok: true });
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var ok = false;
+        try { ok = await quantityDiscounts.unarchive(id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!ok) return _redirect(res, "/admin/quantity-discounts?err=1");
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".quantity_discount.unarchive", outcome: "success", metadata: { id: id } });
+        _redirect(res, "/admin/quantity-discounts?saved=1");
+      },
+    ));
+  }
+
   // Render the discounts screen — gathers rules + (optional) stacking
   // policies, then hands them to the renderer with whatever banner flags
   // the caller passed.
@@ -5394,7 +5890,9 @@ 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: "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" },
   { key: "shipping",     href: "/admin/shipping",     label: "Shipping",     requires: "shippingZones" },
   { key: "pick-lists",   href: "/admin/pick-lists",   label: "Pick lists",   requires: "pickLists" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
@@ -6916,6 +7414,280 @@ function renderAdminTaxRates(opts) {
   return _renderAdminShell(opts.shop_name, "Tax rates", body, "tax", opts.nav_available);
 }
 
+// Money for the filings screens. A filing aggregates orders that may span
+// currencies, so the row stores raw minor-unit totals with no single
+// currency column. Display them through the same pricing formatter the rest
+// of the console uses, in the operator's display currency (defaults to USD)
+// — the number is the reconciliation figure regardless of the symbol.
+var TAX_FILING_DISPLAY_CURRENCY = "USD";
+function _filingMoney(minor) {
+  return pricing.format(Number(minor) || 0, TAX_FILING_DISPLAY_CURRENCY);
+}
+
+// Sales-tax-filings list screen — open filings (filterable by jurisdiction
+// + status), an upcoming-due strip, and the open-a-period form. Read-heavy:
+// the lifecycle actions live on each filing's detail page.
+function renderAdminTaxFilings(opts) {
+  opts = opts || {};
+  var filings  = opts.filings  || [];
+  var upcoming = opts.upcoming || [];
+  var kinds    = opts.kinds    || ["monthly", "quarterly", "annual"];
+  var statuses = opts.statuses || ["draft", "computed", "submitted", "paid", "amended"];
+  var jurisdiction = opts.jurisdiction || "";
+  var statusFilter = opts.status_filter || "";
+  var created = opts.created ? "<div class=\"banner banner--ok\">Filing period opened.</div>" : "";
+  var notice  = opts.notice  ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Status pill class reuse: map filing status onto the order pill palette so
+  // the visual language matches the rest of the console.
+  function _statusPill(s) {
+    var cls = s === "paid" ? "paid"
+            : s === "submitted" ? "shipped"
+            : s === "computed" ? "fulfilling"
+            : s === "amended" ? "cancelled"
+            : "pending";
+    return "<span class=\"status-pill " + cls + "\">" + _htmlEscape(s) + "</span>";
+  }
+
+  // Filter form — jurisdiction text + status select. GET so the filter
+  // lives in the URL.
+  var statusOpts = [{ value: "", label: "All statuses" }].concat(statuses.map(function (s) { return { value: s, label: s }; }));
+  var filterForm =
+    "<form method=\"get\" action=\"/admin/tax-filings\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>Jurisdiction</span>" +
+        "<input type=\"text\" name=\"jurisdiction\" value=\"" + _htmlEscape(jurisdiction) + "\" placeholder=\"US or US-CA\" maxlength=\"6\" class=\"input-code\"></label>" +
+      _selectField("Status", "status", statusOpts, statusFilter, "", "") +
+      "<button class=\"btn\" type=\"submit\">Filter</button>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Clear</a>" +
+    "</form>";
+
+  // Due/overdue strip — open filings due within the next 30 days OR already
+  // past their due date (upcomingDue filters due_date <= now+30d, no lower bound).
+  var dueRows = upcoming.map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.jurisdiction) + "</a></td>" +
+      "<td>" + _htmlEscape(f.kind) + "</td>" +
+      "<td>" + _statusPill(f.status) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.due_date)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var dueBlock = upcoming.length
+    ? "<section><h2>Due soon or overdue</h2><div class=\"panel\">" +
+        "<table><thead><tr><th scope=\"col\">Jurisdiction</th><th scope=\"col\">Period</th><th scope=\"col\">Status</th><th scope=\"col\">Due</th></tr></thead><tbody>" + dueRows + "</tbody></table>" +
+      "</div></section>"
+    : "";
+
+  // Filings table.
+  var rows = filings.map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.jurisdiction) + "</a></td>" +
+      "<td>" + _htmlEscape(f.kind) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.due_date)) + "</td>" +
+      "<td>" + _statusPill(f.status) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_collected_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_owed_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = filings.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Jurisdiction</th><th scope=\"col\">Kind</th><th scope=\"col\">Period</th><th scope=\"col\">Due</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Collected</th><th scope=\"col\" class=\"num\">Owed</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No filings" + (jurisdiction ? " for " + _htmlEscape(jurisdiction) : "") + " yet. Open a period below.</p>";
+
+  // Open-a-period form.
+  var kindOpts = kinds.map(function (k) { return { value: k, label: k }; });
+  var createForm =
+    "<div class=\"panel mt mw-34\">" +
+      "<h3 class=\"subhead\">Open a filing period</h3>" +
+      "<form method=\"post\" action=\"/admin/tax-filings\">" +
+        _setupField("Jurisdiction", "jurisdiction", "", "text", "ISO 3166-1 country, optionally -subdivision (e.g. US, US-CA, DE-BY).", " maxlength=\"6\" class=\"input-code\" required") +
+        _selectField("Kind", "kind", kindOpts, "quarterly", "Filing cadence the authority expects.", " required") +
+        _setupField("Period start (epoch-ms)", "period_start", "", "number", "First instant of the filing window.", " min=\"0\" required") +
+        _setupField("Period end (epoch-ms)", "period_end", "", "number", "Exclusive end of the window (must be after start).", " min=\"0\" required") +
+        _setupField("Due date (epoch-ms)", "due_date", "", "number", "When the filing is due (must be on or after the period end).", " min=\"0\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Open period</button></div>" +
+      "</form>" +
+    "</div>";
+
+  // Report shortcut.
+  var reportForm =
+    "<div class=\"panel mt mw-34\">" +
+      "<h3 class=\"subhead\">Remittance report</h3>" +
+      "<form method=\"get\" action=\"/admin/tax-filings/report\">" +
+        _setupField("Jurisdiction", "jurisdiction", jurisdiction, "text", "Roll up every filing whose period intersects the window.", " maxlength=\"6\" class=\"input-code\" required") +
+        _setupField("From (epoch-ms)", "from", "", "number", "Window start.", " min=\"0\" required") +
+        _setupField("To (epoch-ms)", "to", "", "number", "Window end.", " min=\"0\" required") +
+        "<div class=\"actions-row\"><button class=\"btn btn--ghost\" type=\"submit\">Run report</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body =
+    "<section><h2>Sales tax filings</h2>" + created + notice + filterForm + table + "</section>" +
+    dueBlock +
+    "<section><div class=\"two-col\">" + createForm + reportForm + "</div></section>";
+  return _renderAdminShell(opts.shop_name, "Tax filings", body, "tax-filings", opts.nav_available);
+}
+
+// Sales-tax-filing detail — the snapshot totals, the per-rate breakdown, the
+// audit trail, and the lifecycle action forms gated on the filing's status.
+function renderAdminTaxFiling(opts) {
+  opts = opts || {};
+  var f = opts.filing;
+  var banners =
+    (opts.created   ? "<div class=\"banner banner--ok\">Filing period opened.</div>" : "") +
+    (opts.computed  ? "<div class=\"banner banner--ok\">Snapshot computed.</div>" : "") +
+    (opts.submitted ? "<div class=\"banner banner--ok\">Submission recorded.</div>" : "") +
+    (opts.paid      ? "<div class=\"banner banner--ok\">Payment recorded.</div>" : "") +
+    (opts.amended   ? "<div class=\"banner banner--ok\">Filing amended.</div>" : "") +
+    (opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "");
+  if (!f) {
+    return _renderAdminShell(opts.shop_name, "Filing", "<section><h2>Filing</h2>" + banners + "<p class=\"empty\">Filing not found.</p></section>", "tax-filings", opts.nav_available);
+  }
+  var enc = encodeURIComponent(f.id);
+
+  var meta =
+    "<section><h2>" + _htmlEscape(f.jurisdiction) + " · " + _htmlEscape(f.kind) + "</h2>" + banners +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) +
+        " · Due " + _htmlEscape(_fmtDate(f.due_date)) +
+        " · Status <span class=\"status-pill " + _htmlEscape(f.status) + "\">" + _htmlEscape(f.status) + "</span></p>" +
+    "</section>";
+
+  var stats =
+    "<section><h2>Snapshot</h2><div class=\"stat-grid\">" +
+      _statCard("Gross revenue", _filingMoney(f.gross_revenue_minor)) +
+      _statCard("Taxable revenue", _filingMoney(f.taxable_revenue_minor)) +
+      _statCard("Exempt revenue", _filingMoney(f.exempt_revenue_minor)) +
+      _statCard("Tax collected", _filingMoney(f.tax_collected_minor)) +
+      _statCard("Tax owed", _filingMoney(f.tax_owed_minor), true) +
+    "</div>" +
+    (f.computed_at == null ? "<p class=\"meta\">Not computed yet — run the snapshot to aggregate orders in the window.</p>"
+                           : "<p class=\"meta\">Computed " + _htmlEscape(_fmtDate(f.computed_at)) + ".</p>") +
+    "</section>";
+
+  // Per-rate breakdown table — one row per rate bucket the snapshot produced.
+  var breakdown = f.by_rate_breakdown || {};
+  var bkeys = Object.keys(breakdown);
+  var breakdownRows = bkeys.map(function (k) {
+    var bkt = breakdown[k] || {};
+    var label = k === "__none__" ? "no rate matched"
+              : k === "__exempt__" ? "exempt"
+              : k === "__unknown__" ? "unknown rate"
+              : _fmtBps(k);
+    return "<tr>" +
+      "<td>" + _htmlEscape(label) + (k === "__none__" || k === "__exempt__" || k === "__unknown__" ? "" : " <span class=\"meta\">(" + _htmlEscape(String(k)) + " bps)</span>") + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(bkt.order_count == null ? 0 : bkt.order_count)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(bkt.taxable_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(bkt.tax_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var breakdownBlock = bkeys.length
+    ? "<section><h2>By rate</h2><div class=\"panel\"><table><thead><tr><th scope=\"col\">Rate</th><th scope=\"col\" class=\"num\">Orders</th><th scope=\"col\" class=\"num\">Taxable</th><th scope=\"col\" class=\"num\">Tax</th></tr></thead><tbody>" + breakdownRows + "</tbody></table></div></section>"
+    : "";
+
+  // Audit trail — submission + payment + amendment columns once recorded.
+  var trail = "";
+  if (f.submission_ref || f.payment_ref || f.amended_reason) {
+    var trailRows = "";
+    if (f.submission_ref) {
+      trailRows += "<tr><td>Submitted</td><td>" + _htmlEscape(f.submission_ref) +
+        (f.submitted_by ? " <span class=\"meta\">by " + _htmlEscape(f.submitted_by) + "</span>" : "") +
+        (f.submitted_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.submitted_at)) + "</span>" : "") + "</td></tr>";
+    }
+    if (f.payment_ref || f.payment_minor != null) {
+      trailRows += "<tr><td>Paid</td><td>" + _htmlEscape(_filingMoney(f.payment_minor)) +
+        (f.payment_ref ? " <span class=\"meta\">ref " + _htmlEscape(f.payment_ref) + "</span>" : "") +
+        (f.paid_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.paid_at)) + "</span>" : "") + "</td></tr>";
+    }
+    if (f.amended_reason) {
+      trailRows += "<tr><td>Amended</td><td>" + _htmlEscape(f.amended_reason) +
+        (f.amended_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.amended_at)) + "</span>" : "") + "</td></tr>";
+    }
+    trail = "<section><h2>Audit trail</h2><div class=\"panel\"><table><tbody>" + trailRows + "</tbody></table></div></section>";
+  }
+
+  // Lifecycle actions — gated on the FSM. draft → compute; computed →
+  // submit or amend; submitted → pay or amend; paid → amend.
+  var actions = "";
+  if (f.status === "draft" || f.status === "computed") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/compute\" class=\"form-inline\">" +
+        "<button class=\"btn\" type=\"submit\">" + (f.status === "computed" ? "Recompute snapshot" : "Compute snapshot") + "</button>" +
+      "</form>";
+  }
+  if (f.status === "computed") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/submit\" class=\"stack\">" +
+        _setupField("Submission reference", "submission_ref", "", "text", "The authority's confirmation number (e.g. DR-123-456).", " maxlength=\"200\" required") +
+        _setupField("Submitted by", "submitted_by", "", "text", "Who filed it.", " maxlength=\"200\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Record submission</button></div>" +
+      "</form>";
+  }
+  if (f.status === "submitted") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/pay\" class=\"stack\">" +
+        _setupField("Payment (minor units)", "payment_minor", "", "number", "Remitted amount in minor units — may be a partial / installment payment.", " min=\"0\" required") +
+        _setupField("Payment reference", "payment_ref", "", "text", "The authority's payment confirmation.", " maxlength=\"200\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Record payment</button></div>" +
+      "</form>";
+  }
+  if (f.status === "computed" || f.status === "submitted" || f.status === "paid") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/amend\" class=\"stack\">" +
+        _setupField("Amendment reason", "reason", "", "text", "Why this filing is being corrected. The snapshot stays for the audit trail.", " maxlength=\"1000\" required") +
+        "<div class=\"actions-row\"><button class=\"btn btn--danger\" type=\"submit\">Mark amended</button></div>" +
+      "</form>";
+  }
+  var actionsBlock = actions
+    ? "<section><h2>Actions</h2><div class=\"panel\">" + actions + "</div></section>"
+    : "<section><h2>Actions</h2><p class=\"meta\">This filing is in a terminal state; re-open the period after amending to file again.</p></section>";
+
+  var back = "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p>";
+  return _renderAdminShell(opts.shop_name, "Filing", meta + stats + breakdownBlock + trail + actionsBlock + back, "tax-filings", opts.nav_available);
+}
+
+// Per-jurisdiction remittance report — the totals across every filing whose
+// period intersects the window. Read-only.
+function renderAdminTaxFilingReport(opts) {
+  opts = opts || {};
+  var report = opts.report;
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  if (!report) {
+    return _renderAdminShell(opts.shop_name, "Remittance report",
+      "<section><h2>Remittance report</h2>" + notice +
+      "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p></section>",
+      "tax-filings", opts.nav_available);
+  }
+  var stats =
+    "<div class=\"stat-grid\">" +
+      _statCard("Filings", String(report.filing_count)) +
+      _statCard("Gross revenue", _filingMoney(report.total_gross_revenue_minor)) +
+      _statCard("Taxable revenue", _filingMoney(report.total_taxable_revenue_minor)) +
+      _statCard("Exempt revenue", _filingMoney(report.total_exempt_revenue_minor)) +
+      _statCard("Tax collected", _filingMoney(report.total_tax_collected_minor)) +
+      _statCard("Tax owed", _filingMoney(report.total_tax_owed_minor), true) +
+      _statCard("Tax paid", _filingMoney(report.total_tax_paid_minor)) +
+    "</div>";
+  var rows = (report.filings || []).map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.kind) + "</a></td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) + "</td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(f.status) + "\">" + _htmlEscape(f.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_collected_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_owed_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = (report.filings || []).length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Period</th><th scope=\"col\">Window</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Collected</th><th scope=\"col\" class=\"num\">Owed</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No filings intersect this window.</p>";
+
+  var body =
+    "<section><h2>Remittance report · " + _htmlEscape(report.jurisdiction) + "</h2>" + notice +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(report.from)) + " → " + _htmlEscape(_fmtDate(report.to)) + "</p>" +
+      stats + table +
+      "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Remittance report", body, "tax-filings", opts.nav_available);
+}
+
 function renderAdminShipping(opts) {
   opts = opts || {};
   var rows = opts.zones || [];
@@ -7920,6 +8692,210 @@ function renderAdminCollection(opts) {
   return _renderAdminShell(opts.shop_name, "Collection " + col.slug, body, "collections", opts.nav_available);
 }
 
+// One labelled <option> list for the discount_kind dropdown, with the
+// kind whose value is a fixed money amount annotated so the operator
+// knows whether `value` is basis points or minor units.
+function _qdKindLabel(kind) {
+  if (kind === "percent_off")      return "percent_off (value = basis points; 1000 = 10%)";
+  if (kind === "amount_off_each")  return "amount_off_each (value = minor units off each unit)";
+  if (kind === "amount_off_total") return "amount_off_total (value = minor units off the line)";
+  if (kind === "fixed_each_price") return "fixed_each_price (value = new unit price in minor units)";
+  return kind;
+}
+
+function _qdKindOptions(kinds, selected) {
+  return (kinds || []).map(function (k) {
+    return "<option value=\"" + _htmlEscape(k) + "\"" + (k === selected ? " selected" : "") + ">" +
+      _htmlEscape(_qdKindLabel(k)) + "</option>";
+  }).join("");
+}
+
+// A single editable tier row — min_quantity + discount_kind + value.
+// `tier` may be a stored row (edit) or {} for a spare append row.
+function _qdTierRow(kinds, tier) {
+  tier = tier || {};
+  var minVal = tier.min_quantity == null ? "" : String(tier.min_quantity);
+  var valVal = tier.value == null ? "" : String(tier.value);
+  return "<div class=\"actions-row m-04\">" +
+    "<input type=\"number\" name=\"tier_min\" value=\"" + _htmlEscape(minVal) + "\" placeholder=\"min qty\" min=\"1\" step=\"1\" class=\"input-code\">" +
+    "<select name=\"tier_kind\"><option value=\"\">kind…</option>" + _qdKindOptions(kinds, tier.discount_kind) + "</select>" +
+    "<input type=\"number\" name=\"tier_value\" value=\"" + _htmlEscape(valVal) + "\" placeholder=\"value\" min=\"0\" step=\"1\" class=\"input-code\">" +
+  "</div>";
+}
+
+// Quantity-discount tier-set list — a table of tier sets (scope,
+// scope_id, #tiers, exclusive, status) plus a create form. The create
+// form's scope dropdown + each tier row's kind dropdown use the engine's
+// exact enums so a console-built set always validates. Mirrors
+// renderAdminCollections.
+function renderAdminQuantityDiscounts(opts) {
+  opts = opts || {};
+  var rows   = opts.tier_sets || [];
+  var scopes = opts.scopes || quantityDiscountsModule.VALID_SCOPES;
+  var kinds  = opts.kinds  || quantityDiscountsModule.VALID_KINDS;
+  var created  = opts.created  ? "<div class=\"banner banner--ok\">Tier set created.</div>" : "";
+  var saved    = opts.saved    ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var archived = opts.archived ? "<div class=\"banner banner--ok\">Tier set archived.</div>" : "";
+  var notice   = opts.notice   ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var af = opts.archived_filter;
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (af == null ? " chip--on" : "") + "\" href=\"/admin/quantity-discounts\">All</a>" +
+    "<a class=\"chip" + (af === "0" ? " chip--on" : "") + "\" href=\"/admin/quantity-discounts?archived=0\">Active</a>" +
+    "<a class=\"chip" + (af === "1" ? " chip--on" : "") + "\" href=\"/admin/quantity-discounts?archived=1\">Archived</a>" +
+    "</div>";
+
+  var bodyRows = rows.map(function (s) {
+    var isArchived = s.archived_at != null;
+    var enc = encodeURIComponent(s.id);
+    return "<tr>" +
+      "<td><a href=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(s.scope) + "</strong></a></td>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(s.scope_id == null ? "—" : s.scope_id) + "</code></td>" +
+      "<td class=\"num\">" + _htmlEscape(String((s.tiers || []).length)) + "</td>" +
+      "<td><span class=\"status-pill " + (s.exclusive ? "pending" : "paid") + "\">" + (s.exclusive ? "exclusive" : "stacks") + "</span></td>" +
+      "<td><span class=\"status-pill " + (isArchived ? "cancelled" : "paid") + "\">" + (isArchived ? "archived" : "active") + "</span></td>" +
+      "<td><div class=\"actions-row\">" +
+        "<a class=\"btn btn--ghost\" href=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "\">Manage</a>" +
+        (isArchived
+          ? "<form method=\"post\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--ghost\" type=\"submit\">Restore</button></form>"
+          : "<form method=\"post\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger\" type=\"submit\">Archive</button></form>") +
+      "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Scope</th><th scope=\"col\">Scope id</th><th scope=\"col\" class=\"num\">Tiers</th><th scope=\"col\">Stacking</th><th scope=\"col\">Status</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No quantity breaks" + (af === "1" ? " archived" : af === "0" ? " active" : " yet") + ".</p>";
+
+  var scopeOpts = scopes.map(function (sc) {
+    return "<option value=\"" + _htmlEscape(sc) + "\"" + (sc === "sku" ? " selected" : "") + ">" + _htmlEscape(sc) + "</option>";
+  }).join("");
+
+  // Three starter tier rows on create — enough for a typical "5 / 10 /
+  // 20" schedule without a separate add-row round-trip. Blank rows are
+  // dropped server-side; the operator fills as many as they need.
+  var starterRows = _qdTierRow(kinds, {}) + _qdTierRow(kinds, {}) + _qdTierRow(kinds, {});
+
+  var createForm =
+    "<div class=\"panel mt mw-40\">" +
+      "<h3 class=\"subhead\">Create a tier set</h3>" +
+      "<p class=\"meta\">A quantity break attaches to a scope (one SKU, product, collection, vendor, category, or everything) and a schedule of (min quantity, kind, value) rules. The pricing engine applies the best matching rule per cart line automatically.</p>" +
+      "<form method=\"post\" action=\"/admin/quantity-discounts\">" +
+        "<label class=\"form-field\"><span>Scope</span><select name=\"scope\">" + scopeOpts + "</select></label>" +
+        _setupField("Scope id", "scope_id", "", "text", "The SKU / product id / collection slug / vendor / category. Leave blank only when scope = global.", " maxlength=\"256\"") +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"exclusive\" value=\"on\"> Exclusive — when this set's best rule applies, no other tier set may stack on the same line.</label>" +
+        "<fieldset class=\"box\">" +
+          "<legend class=\"legend-sm\">Tiers (min quantity → discount)</legend>" +
+          starterRows +
+          "<small class=\"u-mute\">Leave a row blank to drop it. min quantity is a positive integer; value's meaning depends on the kind (percent_off = basis points, the amount/fixed kinds = minor units). Duplicate min quantities in one set are refused.</small>" +
+        "</fieldset>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Create tier set</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var bodyHtml = "<section><h2>Quantity breaks</h2>" + created + saved + archived + notice + chips + table + createForm + "</section>";
+  return _renderAdminShell(opts.shop_name, "Quantity breaks", bodyHtml, "quantity-discounts", opts.nav_available);
+}
+
+// Quantity-discount tier-set detail — the set's scope + schedule, a
+// rewrite form (rewrite the tier rows / toggle exclusive), archive or
+// unarchive, and a sample-price tierBreakdown preview. Mirrors
+// renderAdminCollection.
+function renderAdminQuantityDiscount(opts) {
+  opts = opts || {};
+  var s = opts.tier_set;
+  if (!s) {
+    var nf = "<section><h2>Quantity break</h2><p class=\"empty\">Tier set not found.</p>" +
+      "<div class=\"actions-row\"><a class=\"btn btn--ghost\" href=\"/admin/quantity-discounts\">Back to quantity breaks</a></div></section>";
+    return _renderAdminShell(opts.shop_name, "Quantity break", nf, "quantity-discounts", opts.nav_available);
+  }
+  var kinds = opts.kinds || quantityDiscountsModule.VALID_KINDS;
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var enc = encodeURIComponent(s.id);
+  var isArchived = s.archived_at != null;
+
+  // Render the stored tiers plus one spare empty row so the operator can
+  // append without a separate round-trip. The edit POST rewrites the
+  // whole schedule (the engine's update replaces tiers wholesale).
+  var tierRows = (s.tiers || []).map(function (t) { return _qdTierRow(kinds, t); }).join("") + _qdTierRow(kinds, {});
+
+  var editForm =
+    "<div class=\"panel mw-40\">" +
+      "<h3 class=\"subhead\">Schedule</h3>" +
+      "<form method=\"post\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "/edit\">" +
+        "<input type=\"hidden\" name=\"exclusive_present\" value=\"1\">" +
+        "<label class=\"kv\"><input type=\"checkbox\" name=\"exclusive\" value=\"on\"" + (s.exclusive ? " checked" : "") + "> Exclusive — no other tier set may stack on the same line.</label>" +
+        "<fieldset class=\"box\">" +
+          "<legend class=\"legend-sm\">Tiers (rewrites the whole schedule)</legend>" +
+          tierRows +
+          "<small class=\"u-mute\">Leave a row blank to drop it. Rewriting replaces every rule in this set. Duplicate min quantities are refused.</small>" +
+        "</fieldset>" +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Save schedule</button></div>" +
+      "</form>" +
+    "</div>";
+
+  // tierBreakdown preview — the active schedule at a sample unit price so
+  // the operator can sanity-check the discounted unit / line at each
+  // threshold. The sample defaults to 1000 minor (e.g. $10.00); the
+  // operator can re-sample via the query string.
+  var sampleMinor = opts.sample_minor == null ? 1000 : opts.sample_minor;
+  var breakdown = opts.breakdown;
+  var previewRows = (breakdown && Array.isArray(breakdown.rows) ? breakdown.rows : []).map(function (r) {
+    var du = r.sample_discounted_unit_minor;
+    var ld = r.sample_line_discount_minor;
+    var ls = r.sample_line_subtotal_minor;
+    return "<tr>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.min_quantity)) + "</td>" +
+      "<td>" + _htmlEscape(r.discount_kind) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(r.value)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(du == null ? "—" : String(du)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(ld == null ? "—" : String(ld)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(ls == null ? "—" : String(ls)) + "</td>" +
+    "</tr>";
+  }).join("");
+  var previewTable = previewRows
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\" class=\"num\">Min qty</th><th scope=\"col\">Kind</th><th scope=\"col\" class=\"num\">Value</th><th scope=\"col\" class=\"num\">Unit @ min</th><th scope=\"col\" class=\"num\">Line saved</th><th scope=\"col\" class=\"num\">Line total</th></tr></thead><tbody>" + previewRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No active rules to preview for this scope.</p>";
+  var previewForm =
+    "<form method=\"get\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "\" class=\"actions-row m-04\">" +
+      "<label class=\"form-field\"><span>Sample unit price (minor units)</span>" +
+        "<input type=\"number\" name=\"sample\" value=\"" + _htmlEscape(String(sampleMinor)) + "\" min=\"0\" step=\"1\" class=\"input-code\"></label>" +
+      "<button class=\"btn btn--ghost\" type=\"submit\">Preview</button>" +
+    "</form>";
+  // An archived set is not active, so tierBreakdown (which filters to
+  // active rules at this scope) would preview OTHER sets' rules — or
+  // nothing. Show a clear restore prompt instead of a foreign/empty table.
+  var previewSection = isArchived
+    ? "<section class=\"mt\"><h3 class=\"fs-105\">Schedule preview</h3>" +
+        "<p class=\"empty\">This tier set is archived, so its schedule isn't active. Restore the set to preview it.</p>" +
+      "</section>"
+    : "<section class=\"mt\"><h3 class=\"fs-105\">Schedule preview</h3>" +
+        "<p class=\"meta\">The active rules for this scope at a sample unit price (all values in minor units). Helps sanity-check a schedule before it goes live.</p>" +
+        previewForm + previewTable +
+      "</section>";
+
+  var archiveBlock = isArchived
+    ? "<form method=\"post\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "/unarchive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">Restore tier set</button></form>"
+    : "<form method=\"post\" action=\"/admin/quantity-discounts/" + _htmlEscape(enc) + "/archive\" class=\"form-inline\">" +
+        "<button class=\"btn btn--danger\" type=\"submit\">Archive tier set</button></form>";
+
+  var head =
+    "<p class=\"meta\"><a href=\"/admin/quantity-discounts\">&larr; Quantity breaks</a> · " +
+      "<span class=\"status-pill " + (s.exclusive ? "pending" : "paid") + "\">" + (s.exclusive ? "exclusive" : "stacks") + "</span>" +
+      (isArchived ? " · <span class=\"status-pill cancelled\">archived</span>" : "") +
+      " · <code class=\"order-id\">" + _htmlEscape(s.scope_id == null ? "global" : s.scope_id) + "</code></p>";
+
+  var body = "<section><h2>" + _htmlEscape(s.scope) +
+    (s.scope_id == null ? "" : " · " + _htmlEscape(s.scope_id)) + "</h2>" +
+    saved + notice + head + editForm +
+    "<div class=\"actions-row mt-1\">" + archiveBlock + "</div></section>" + previewSection;
+  return _renderAdminShell(opts.shop_name, "Quantity break", body, "quantity-discounts", opts.nav_available);
+}
+
 // Product detail / management screen — the console's full editor for a
 // single catalog product: its fields (slug / title / description /
 // status), its variants (create / edit / delete), each variant's price
@@ -8166,5 +9142,7 @@ module.exports = {
   renderAdminShipping:     renderAdminShipping,
   renderAdminShippingZone: renderAdminShippingZone,
   renderAdminDiscounts:    renderAdminDiscounts,
+  renderAdminQuantityDiscounts: renderAdminQuantityDiscounts,
+  renderAdminQuantityDiscount:  renderAdminQuantityDiscount,
   renderAdminConfirm:      renderAdminConfirm,
 };

package/lib/asset-manifest.json

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

package/package.json

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