domma-cms 1.6.37 → 1.6.39

package/plugins/mail-reader/CLAUDE.md

@@ -63,10 +63,13 @@ open on something rather than asking which before it has shown anything.
   is what makes it safe.)
 - **Credentials are not a collection.** `schema.plugin` is a badge, not a visibility gate - a
   plugin-owned collection still appears in admin Collections with a working Entries link, is
-  reachable via `/api/v1`, and can be pointed at a shared Mongo. Hence `data/accounts.json`, 0600,
-  gitignored, and excluded from the npm `files` list.
+  reachable via `/api/v1`, and can be pointed at a shared Mongo. Hence a file: the shared mail core
+  (`plugins/_lib/mail/accounts.js`) keeps them in `plugins/_lib/data/mail-accounts.json` (0600, written
+  atomically; `DOMMA_MAIL_DATA_DIR` moves it), gitignored and out of the npm `files` list. An older
+  site's `mail-reader/data/accounts.json` is adopted from there on first read.
 - **Key resolution is a chain**, not a single source: `MAIL_SECRET` → `INSTANCE_SECRET` →
-  generated `data/.mailkey`. `INSTANCE_SECRET` only exists on sites that ran setup or registered
+  generated `plugins/_lib/data/.mailkey` (0600; `_lib/mail/secretbox.js`, which adopts a legacy
+  `mail-reader/data/.mailkey`). `INSTANCE_SECRET` only exists on sites that ran setup or registered
   with the manager, so relying on it alone breaks every older site. The sealing source is recorded
   in each token so a key change fails with a sentence, not a bare auth error.
 - **Never derive from `JWT_SECRET`.** Rotating it logs everyone out, which is recoverable; silently
@@ -88,7 +91,10 @@ open on something rather than asking which before it has shown anything.
 
 ## Testing
 
-`services/secretbox.js` and `services/render.js` are pure and unit-tested. Connection behaviour
+The mail code is the engine's shared core, `plugins/_lib/mail/` (this plugin is little more than its
+manifest, guide and plugin.js wiring); `secretbox.js` and `render.js` there are pure and unit-tested in
+domma-cms (`tests/services/mail-secretbox.test.js`, `mail-render.test.js`, and the other `mail-*.test.js`
+files). Connection behaviour
 should be checked against a **real IMAP server** - `mail.dommajs.org` answers on 993 (TLS) and 143
 (STARTTLS). A wrong-credentials attempt is enough to verify TLS, auth-failure mapping and that the
 pool leaves nothing open; it does not verify folder listing or rendering, which need a real mailbox.
@@ -114,3 +120,8 @@ this version only documents it in docs/guide.md. 0.116.8 is already released, so
 Saving or testing a mailbox on a private, loopback or link-local address is refused by the shared read routes
 unless it is the site's own outgoing server or `allowPrivateMailHosts` is set; `/accounts/test` is limited to
 10 a minute. Engine code - this version only documents the option in docs/guide.md. Ship with the matching core.
+
+## Notes
+
+- 2026-10-13 (1.2.8): this file brought up to date - credentials, the key and the tested modules live in the
+  shared `plugins/_lib/mail` core and `plugins/_lib/data/`, not in this plugin's `services/` and `data/`. No code change.

package/plugins/mail-reader/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mail-reader",
   "displayName": "Mail Reader",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "tier": "free",
   "description": "Read-only IMAP mailbox reader. Connects to a standard IMAP server and reads mail without ever writing to it.",
   "author": "Darryl Waterhouse",

package/plugins/shopping-cart/CLAUDE.md

@@ -70,7 +70,7 @@ A paid or refunded order cannot be deleted. Each order has a random `token`: the
   and checks `paypalPaid`. Sandbox/live by setting.
 - Offline: the order is `awaiting`; the receipt shows `offlineInstructions`. Mark paid from the admin.
 - Refunds: `POST /orders/:id/refund` refunds through Stripe (payment_intent) or PayPal (capture id) FIRST,
-  and only then marks the order refunded. Full refunds only.
+  and only then records it. Part refunds since 1.6.2 (see the end of this file).
 - Secrets never leave the server: GET /settings masks them (`••••••••`); saving the mask keeps the value.
 
 ## Extensions (Shopping Cart Pro)
@@ -216,4 +216,37 @@ Cart only READS it (`lib/commission.js currentCommission`, re-read when the file
   is off when accounts are: user ids are public (`createdBy`), so "already confirmed -> here is the email" leaked emails.
 - `refundOrder` runs under `withLock` (provider call and `moveOrderNow` in one), and Stripe refunds carry
   `Idempotency-Key: shopping-cart-refund-<orderId>` (sessions: `shop-session-<orderId>`) so a retry after a timeout
-  returns the first result.
+  returns the first result.
+
+## 1.6.2 (2026-10-13): part refunds
+
+- `POST /orders/:id/refund {amount?, note, restock, viaProvider}` - `amount` in minor units refunds part of what is left;
+  left out, the rest goes back. `lib/refunds.js` (PURE, `tests/refunds.test.js`): `refundsOf` (an order refunded before
+  1.6.2 reads as ONE refund of its total, dated `refundedAt`), `refundedSoFar`, `refundable`, `refundPlan` (400 for a bad
+  or too-large amount, 409 when nothing is left).
+- The order keeps `refunds: [{at, amount, by, note, via, ref}]` and `refunded` (their sum). A part refund is recorded by
+  `recordRefundNow` (history line, status unchanged, no stock, no `status` event); the refund that leaves nothing moves the
+  order to `refunded` through `moveOrderNow` as before (restock, commission reversed, `announceMove`). Commission is
+  returned only on the full refund - a part refund leaves it whole (decision pending: pro-rata?).
+- Everything still runs under `withLock`. Provider keys are per refund: Stripe `Idempotency-Key` and PayPal
+  `PayPal-Request-Id` = `shopping-cart-refund-<orderId>-<n>` (n = this refund's ordinal), so a retry after a timeout
+  returns the first result and the next part refund is a new request. PayPal sends `amount {value, currency_code}` only for
+  a part refund. Stripe/PayPal refund ids land in `refunds[].ref`.
+- Sales: `refunds` and `refundCount` count each refund on its own day; the CSV's "Refunded" date is the last refund's and
+  a new last column "Refunded amount" holds the sum. `services.refund(id, {amount})` takes the same amount.
+- Admin: the Refund dialog has an amount (prefilled with what is left) and a reason; restock is offered only for a full
+  refund; the order panel lists the refunds; the menu says "Refund more…" once part has gone back.
+
+
+## 1.6.2 (2026-10-13): badge cache
+`lib/shop.js` keeps a write generation: `withLock` moves it as every write starts and ends, and `removeProduct` and
+`saveSettings` move it too. `GET /count` (every admin tab, every minute, all orders + products) keeps one answer for
+60 s unless the generation moved; an answer worked out across a write is not kept. `services.writeGeneration` lets
+extensions (Takeaway 0.4.2) cache their own order reads the same way - feature-detect it, older Carts lack it.
+
+## 1.6.3 (2026-10-13): the Refund form was empty
+`E.confirm` sanitises its message (preset basic), which strips `<input>` - so 1.6.2's Refund dialog showed only the words,
+no amount, reason or restock box, and OK refunded the WHOLE order. `refund()` in `admin/views/orders.js` is now a small
+slideover (`openPanel`, like Fulfil): amount (prefilled with what is left), reason, restock box (greyed out unless the
+amount is all that is left), a Refund button. Never put form fields in `E.confirm` / `E.alert`.
+`tests/pure.test.js` "admin: no form fields inside E.confirm" guards it across the admin views.

package/plugins/shopping-cart/admin/css/index.css

@@ -206,6 +206,9 @@ a.shp-tile:hover { border-color: var(--dm-primary); }
 .shp-order a { color: var(--dm-primary); }
 .shp-callout { border-left: 3px solid var(--dm-warning); background: color-mix(in srgb, var(--dm-warning) 9%, transparent); padding: .6rem .8rem; border-radius: var(--dm-radius-sm); }
 .shp-callout p { white-space: pre-wrap; margin-top: .25rem; }
+.shp-refunds { border-left-color: var(--dm-danger); background: color-mix(in srgb, var(--dm-danger) 8%, transparent); }
+.shp-refunds ul { margin: .35rem 0 0; padding-left: 1.1rem; font-size: var(--dm-text-sm); color: var(--dm-text-muted); }
+.shp-refunds code { font-size: var(--dm-text-xs); }
 .shp-ref { font-size: var(--dm-text-xs); }
 .shp-ext { display: flex; flex-wrap: wrap; gap: .3rem; }
 .shp-history { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: .4rem; border-left: 2px solid var(--dm-border); padding-left: .8rem; }

package/plugins/shopping-cart/admin/views/orders.js

@@ -9,7 +9,7 @@
  * slip. A notification's link (#/plugins/shopping-cart/orders/<id>) opens one.
  */
 
-import {api, copy, entriesOf, esc, fmtDate, fmtDateTime, money, mountPanels, openPanel, refreshBadge, store, when, wireRows} from '../lib/kit.js';
+import {api, copy, entriesOf, esc, fmtDate, fmtDateTime, money, moneyIn, moneyOut, mountPanels, openPanel, refreshBadge, store, when, wireRows} from '../lib/kit.js';
 import {NEXT, STATUS_LABEL, STATUS_TONE, addressLines, orderLabel} from '/plugins/shopping-cart/public/lib/orders.js';
 
 const FILTERS = [
@@ -169,27 +169,77 @@ export async function mount(root, ctx) {
         });
     }
 
-    async function refund(o) {
-        const via = {stripe: 'through Stripe', paypal: 'through PayPal'}[o.data.provider];
-        const html = `<p>Refund ${esc(orderLabel(o.data))}, <strong>${esc(money(o.data.total))}</strong>, in full?</p>
-<p>${via && o.data.paymentRef ? `The money goes back ${via} straight away.` : 'This only marks it refunded - give the money back the way it came.'}</p>
-<label class="shp-check"><input type="checkbox" id="shp-restock" ${o.data.stockTaken ? 'checked' : 'disabled'}> Put the items back in stock</label>`;
-        let restock = Boolean(o.data.stockTaken);
-        const onChange = (e) => { if (e.target.id === 'shp-restock') restock = e.target.checked; };
-        document.addEventListener('change', onChange);
-        const ok = await E.confirm(html);
-        document.removeEventListener('change', onChange);
-        if (!ok) return null;
-        try {
-            const r = await api.orders.refund(o.id, {restock});
-            replace(r.order);
-            refreshBadge();
-            E.toast(`${orderLabel(o.data)} ${r.how}.`, {type: 'success'});
-            return r.order;
-        } catch (err) {
-            E.toast(err.message || String(err), {type: 'error'});
-            return null;
-        }
+    /** Money already given back on an order (legacy whole-order refunds included). */
+    const refundedOf = (d) => Array.isArray(d.refunds) ? d.refunds.reduce((n, r) => n + (Number(r.amount) || 0), 0) : d.status === 'refunded' ? d.total || 0 : 0;
+
+    /**
+     * Refund - all that is left, or part of it - in a small form of its own. (Not E.confirm: its message is
+     * sanitised, which strips inputs, so the amount, reason and restock box never showed and OK refunded it all.)
+     */
+    function refund(o) {
+        return new Promise((resolve) => {
+            const d = o.data;
+            const via = {stripe: 'through Stripe', paypal: 'through PayPal'}[d.provider];
+            const before = refundedOf(d);
+            const left = Math.max(0, (d.total || 0) - before);
+            const f = {amount: M.observable(moneyIn(left)), note: M.observable(''), saving: M.observable(false)};
+            let restock = Boolean(d.stockTaken);
+            const full = () => moneyOut(f.amount.peek()) === left;
+            let panel = null;
+            let box = null;
+            // Stock only comes back when the whole order is refunded, so the box greys out on a part refund.
+            const syncBox = () => { if (box && d.stockTaken) { box.disabled = !full(); box.checked = full() && restock; } };
+            const stop = M.effect(() => { f.amount.value; syncBox(); });
+            openPanel({
+                title: `${before ? 'Refund more of' : 'Refund'} ${orderLabel(d)}`,
+                size: 'sm',
+                model: f,
+                html: `<div class="shp-form">
+  <p class="shp-note">${before ? `<strong>${esc(money(left))}</strong> of ${esc(money(d.total))} is left to refund (${esc(money(before))} already refunded).` : `The order came to <strong>${esc(money(d.total))}</strong>.`}</p>
+  <label class="form-label" for="shp-refund-amount">Amount <span data-help="Leave the whole amount for a full refund. A smaller amount is a part refund: the order stays as it is, with what was given back on it, and you can refund the rest later."></span></label>
+  <input class="form-input" id="shp-refund-amount" inputmode="decimal" data-model="amount.value" aria-describedby="shp-refund-hint">
+  <p class="shp-muted" id="shp-refund-hint">${via && d.paymentRef ? `The money goes back ${via} straight away.` : 'This only records the refund - give the money back the way it came.'}</p>
+  <label class="form-label" for="shp-refund-note">Reason <span class="shp-muted">(optional, kept on the order)</span></label>
+  <input class="form-input" id="shp-refund-note" maxlength="200" data-model="note.value" placeholder="Damaged in the post, one item missing…">
+  <label class="shp-check"><input type="checkbox" id="shp-restock"> Put the items back in stock <span class="shp-muted">(full refund only)</span></label>
+  <div class="shp-actions"><span class="shp-spacer"></span>
+    <button type="button" class="btn btn-sm btn-ghost" data-on-click="cancel">Cancel</button>
+    <button type="button" class="btn btn-sm btn-danger" data-on-click="save" data-bind-disabled="saving.value"><span data-icon="credit-card" data-icon-size="13"></span> Refund</button></div>
+</div>`,
+                before: (el) => {
+                    box = el.querySelector('#shp-restock');
+                    if (!d.stockTaken) box.disabled = true;
+                    box.addEventListener('change', () => { restock = box.checked; });
+                    syncBox();
+                },
+                cleanup: () => { stop?.(); resolve(null); },
+                methods: {
+                    cancel: () => panel?.close(true),
+                    async save() {
+                        if (f.saving.peek()) return;
+                        const amount = moneyOut(f.amount.peek());
+                        if (!Number.isInteger(amount) || amount <= 0 || amount > left) {
+                            E.toast(`Enter an amount between ${money(1)} and ${money(left)}.`, {type: 'error'});
+                            return;
+                        }
+                        const all = amount === left;
+                        f.saving.value = true;
+                        try {
+                            const r = await api.orders.refund(o.id, {amount: all ? undefined : amount, restock: all && restock, note: f.note.peek()});
+                            replace(r.order);
+                            refreshBadge();
+                            E.toast(`${orderLabel(d)} ${r.how}.`, {type: 'success'});
+                            resolve(r.order);
+                            panel?.close(true);
+                        } catch (err) {
+                            E.toast(err.message || String(err), {type: 'error'});
+                        } finally {
+                            f.saving.value = false;
+                        }
+                    }
+                }
+            }).then(p => { panel = p; p.panel.querySelector('#shp-refund-amount')?.focus(); });
+        });
     }
 
     async function remove(o) {
@@ -235,7 +285,7 @@ ${(d.lines || []).map(l => `<tr><td class="q">${l.qty}</td><td>${esc(l.name)}${l
             ...(can('paid') && s !== 'fulfilled' ? [{label: 'Mark paid…', icon: 'check-circle', run: () => markPaid(o)}] : []),
             ...(can('fulfilled') ? [{label: o.data.delivery === 'collect' ? 'Mark collected…' : 'Mark fulfilled…', icon: 'truck', run: () => fulfil(o)}] : []),
             ...(s === 'fulfilled' ? [{label: 'Back to "to fulfil"', icon: 'rotate-ccw', run: () => move(o, 'paid', {note: 'Reopened'})}] : []),
-            ...(can('refunded') ? [{label: 'Refund…', icon: 'credit-card', danger: true, run: () => refund(o)}] : []),
+            ...(can('refunded') ? [{label: refundedOf(o.data) ? 'Refund more…' : 'Refund…', icon: 'credit-card', danger: true, run: () => refund(o)}] : []),
             ...(can('cancelled') ? [{label: 'Cancel order…', icon: 'x-circle', danger: true, run: () => cancel(o)}] : [])
         ];
     }
@@ -301,6 +351,8 @@ ${(d.lines || []).map(l => `<tr><td class="q">${l.qty}</td><td>${esc(l.name)}${l
   <label class="form-label">Staff note <span data-help="Only you see this. Saved when you click away."></span></label>
   <textarea class="form-input" rows="2" data-model="staffNote.value" data-part="staff" placeholder="Wrapped as a gift, sent second class…"></textarea>
   ${d.paymentRef || d.providerRef ? `<p class="shp-muted shp-ref">Payment reference: <code>${esc(d.paymentRef || d.providerRef)}</code></p>` : ''}
+  ${Array.isArray(d.refunds) && d.refunds.length ? `<div class="shp-callout shp-refunds"><strong>Refunded ${esc(money(refundedOf(d)))}${refundedOf(d) < (d.total || 0) ? ` - ${esc(money((d.total || 0) - refundedOf(d)))} left to refund` : ' - in full'}</strong>
+    <ul>${d.refunds.map(r => `<li>${esc(money(r.amount))} · ${esc(fmtDateTime(r.at))} · ${esc(r.via || '')}${r.by ? ` by ${esc(r.by)}` : ''}${r.note ? ` - ${esc(r.note)}` : ''}${r.ref ? ` <code>${esc(r.ref)}</code>` : ''}</li>`).join('')}</ul></div>` : ''}
   ${d.commission ? `<p class="shp-muted shp-ref">Platform commission: ${esc(money(d.commission.amount))} (${esc(`${d.commission.percent}%${d.commission.fixed ? ` + ${money(d.commission.fixed)}` : ''}`)})${d.commission.reversed ? ' - returned with the refund' : ''}</p>` : ''}
   ${ext.length ? `<div class="shp-ext">${ext.map(x => `<span class="shp-chip is-muted">${esc(x.k)}: ${esc(String(x.v))}</span>`).join('')}</div>` : ''}
   <div data-part="ext-panels" hidden></div>

package/plugins/shopping-cart/admin/views/shop.js

@@ -15,7 +15,7 @@
 import {api, loadKit, setCurrency, store} from '../lib/kit.js';
 
 const ROUTE = /^#\/plugins\/shopping-cart(\/|$)/;
-const V = '1.6.0';
+const V = '1.6.2';
 const TABS = [
     {key: 'overview', label: 'Overview', icon: 'bar-chart', module: `/plugins/shopping-cart/admin/views/overview.js?v=${V}`},
     {key: 'orders', label: 'Orders', icon: 'receipt', module: `/plugins/shopping-cart/admin/views/orders.js?v=${V}`},

package/plugins/shopping-cart/docs/guide.md

@@ -69,10 +69,14 @@ Actions:
 
 Refunds:
 
-- Refunds are full refunds only. You cannot refund part of an order.
-- A Stripe or PayPal order is refunded through Stripe or PayPal first. The order is only marked refunded once they accept it.
+- **Refund…** asks how much. It starts at the whole amount still to refund; leave it for a full refund, or type less for a part refund.
+- Add a **Reason** if you like. It is kept on the order.
+- A part refund leaves the order as it is (Paid or Fulfilled). The order shows what was refunded, when and why, and how much is left. **Refund more…** gives back more, up to what is left.
+- When everything has been given back, the order becomes Refunded.
+- A Stripe or PayPal order is refunded through Stripe or PayPal first. The refund is only recorded once they accept it.
 - An offline order is only marked refunded. Give the money back yourself, the way it came.
-- Tick **Put the items back in stock** to return the stock.
+- Tick **Put the items back in stock** to return the stock. This is only offered for a full refund (or the last part of one).
+- Sales counts each refund on the day it was made. The CSV has a **Refunded amount** column.
 
 ### Sales
 

package/plugins/shopping-cart/lib/payments.js

@@ -273,8 +273,21 @@ export function paypalPaid(pp, order) {
     return {ref: pp.id, payment: capture.id};
 }
 
-export async function paypalRefund({creds, captureId}) {
-    return paypalCall(creds, 'POST', `/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {});
+/**
+ * Refund a capture - in full with no `amount`, or part of it (`amount` in
+ * minor units of `currency`, which PayPal wants as a decimal string).
+ * `requestId` becomes PayPal-Request-Id, so a retry after a timeout returns
+ * the first refund instead of making a second.
+ */
+export async function paypalRefund({creds, captureId, amount = 0, currency = '', requestId = ''}) {
+    const token = await paypalToken(creds);
+    const payload = amount && currency ? {amount: {value: fromMinor(amount, currency), currency_code: currency}} : {};
+    return call(`${paypalBase(creds.mode)}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
+        method: 'POST',
+        headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Prefer: 'return=representation',
+            ...(requestId ? {'PayPal-Request-Id': String(requestId).slice(0, 108)} : {})},
+        body: JSON.stringify(payload)
+    }, 'PayPal');
 }
 
 export async function paypalTest({creds}) {

package/plugins/shopping-cart/lib/refunds.js

@@ -0,0 +1,51 @@
+/**
+ * Refund maths. PURE - how much of an order has gone back, how much may still
+ * go back, and what one more refund does to it.
+ *
+ * An order carries `refunds: [{at, amount, by, note, via, ref}]` (minor units)
+ * and `refunded` (their sum). Orders refunded before 1.6.2 have neither - just
+ * `status: 'refunded'` and `refundedAt` - so a missing list on a refunded order
+ * reads as one refund of the total, dated `refundedAt`.
+ *
+ * @module shopping-cart/lib/refunds
+ */
+
+/** Every refund of an order, legacy whole-order refunds included. */
+export function refundsOf(d) {
+    if (Array.isArray(d?.refunds)) return d.refunds;
+    if (d?.status === 'refunded') return [{at: d.refundedAt || d.paidAt || '', amount: d.total || 0, via: 'refunded', legacy: true}];
+    return [];
+}
+
+/** Minor units already given back. */
+export const refundedSoFar = (d) => refundsOf(d).reduce((n, r) => n + (Number(r.amount) || 0), 0);
+
+/** Minor units that may still go back. */
+export const refundable = (d) => Math.max(0, (Number(d?.total) || 0) - refundedSoFar(d));
+
+/**
+ * What one more refund of `requested` minor units does. `requested` empty
+ * (null, undefined, '') means "the rest" - a full refund of what is left.
+ *
+ * @param {object} d - order data
+ * @param {number|string|null} [requested]
+ * @returns {{amount: number, before: number, after: number, remaining: number, full: boolean}}
+ * @throws {Error & {status: number}} 400 for a bad amount, 409 when nothing is left to refund
+ */
+export function refundPlan(d, requested = null) {
+    const bad = (status, message) => Object.assign(new Error(message), {status});
+    const total = Number(d?.total) || 0;
+    const before = refundedSoFar(d);
+    const left = total - before;
+    if (left <= 0) throw bad(409, 'This order has been refunded in full already.');
+    let amount;
+    if (requested === null || requested === undefined || requested === '') amount = left;
+    else {
+        amount = typeof requested === 'number' ? requested : Number(String(requested).trim());
+        // Minor units only: the admin UI converts what was typed, so a fraction here is a bug, not a penny.
+        if (!Number.isInteger(amount) || amount <= 0) throw bad(400, 'The refund amount must be a whole number of minor units above zero.');
+        if (amount > left) throw bad(400, `Only ${left} is left to refund on this order.`);
+    }
+    const after = before + amount;
+    return {amount, before, after, remaining: total - after, full: after >= total};
+}

package/plugins/shopping-cart/lib/sales.js

@@ -19,6 +19,8 @@
  * @module shopping-cart/lib/sales
  */
 
+import {refundsOf} from './refunds.js';
+
 export const SOURCES = {shop: 'Shop', downloads: 'Downloads & keys', takeaway: 'Takeaway', addons: 'Other add-ons'};
 const PROVIDERS = {stripe: 'Card (Stripe)', paypal: 'PayPal', offline: 'Paid offline', free: 'Free'};
 const TOOK = new Set(['paid', 'fulfilled', 'refunded']);
@@ -123,13 +125,14 @@ export function salesReport(orders, {from, to, by = 'day', timeZone = 'Europe/Lo
             const p = periods.get(periodOf(paidDate, by));
             if (p) { p.orders++; p.takings += f.total; p.commission += c; }
         }
-        if (d.status === 'refunded') {
-            const refDate = dateIn(d.refundedAt || d.paidAt || o.meta?.createdAt, timeZone);
+        // Each refund (part or whole) counts on its own day; an order refunded before 1.6.2 reads as one of the total.
+        for (const r of refundsOf(d)) {
+            const refDate = dateIn(r.at || d.refundedAt || d.paidAt || o.meta?.createdAt, timeZone);
             if (inRange(refDate)) {
-                totals.refunds += d.total || 0;
+                totals.refunds += r.amount || 0;
                 totals.refundCount++;
                 const p = periods.get(periodOf(refDate, by));
-                if (p) p.refunds += d.total || 0;
+                if (p) p.refunds += r.amount || 0;
             }
         }
         if (d.commission?.reversed) {
@@ -173,19 +176,23 @@ const pounds = (n) => ((n || 0) / 100).toFixed(2);
 
 /** One row per order sold or refunded in the range - for the accountant. */
 export function salesCsv(orders, {from, to, timeZone = 'Europe/London'}) {
-    const rows = [['Order', 'Paid', 'Status', 'Refunded', 'Sources', 'Payment', 'Customer', 'Subtotal', 'Discount', 'Delivery', 'Tax added', 'Tax included', 'Total', 'Commission', 'Commission rate']];
+    const rows = [['Order', 'Paid', 'Status', 'Refunded', 'Sources', 'Payment', 'Customer', 'Subtotal', 'Discount', 'Delivery', 'Tax added', 'Tax included', 'Total', 'Commission', 'Commission rate', 'Refunded amount']];
+    // "Refunded" is the day of the last refund (part refunds included), so the row shows up in that period too.
+    const lastRefund = (o) => { const r = refundsOf(o.data); return r.length ? dateIn(r[r.length - 1].at || o.data.refundedAt || o.data.paidAt || o.meta?.createdAt, timeZone) : ''; };
     const list = orders.filter(o => TOOK.has(o.data?.status)).filter(o => {
         const paid = dateIn(o.data.paidAt || o.meta?.createdAt, timeZone);
-        const refunded = o.data.refundedAt ? dateIn(o.data.refundedAt, timeZone) : '';
+        const refunded = lastRefund(o);
         return (paid >= from && paid <= to) || (refunded && refunded >= from && refunded <= to);
     }).sort((a, b) => String(a.data.paidAt || a.meta?.createdAt).localeCompare(String(b.data.paidAt || b.meta?.createdAt)));
     for (const o of list) {
         const d = o.data;
         const f = orderFigures(o);
-        rows.push([`#${d.number}`, dateIn(d.paidAt || o.meta?.createdAt, timeZone), d.status, d.refundedAt ? dateIn(d.refundedAt, timeZone) : '',
+        const back = refundsOf(d).reduce((n, r) => n + (r.amount || 0), 0);
+        rows.push([`#${d.number}`, dateIn(d.paidAt || o.meta?.createdAt, timeZone), d.status, lastRefund(o),
             [...new Set((d.lines || []).map(l => SOURCES[sourceOf(o, l)]))].join('; '), PROVIDERS[d.provider] || d.provider, d.customer?.name || d.email || '',
             pounds(f.subtotal), pounds(f.discount), pounds(f.delivery), pounds(f.taxAdded), pounds(f.taxIncluded), pounds(f.total),
-            d.commission ? pounds(d.commission.reversed ? 0 : d.commission.amount) : '', d.commission ? `${d.commission.percent}% + ${pounds(d.commission.fixed)}` : '']);
+            d.commission ? pounds(d.commission.reversed ? 0 : d.commission.amount) : '', d.commission ? `${d.commission.percent}% + ${pounds(d.commission.fixed)}` : '',
+            back ? pounds(back) : '']);
     }
     return rows.map(r => r.map(csvCell).join(',')).join('\r\n') + '\r\n';
 }

package/plugins/shopping-cart/lib/shop.js

@@ -143,9 +143,13 @@ export function cleanSettings(input, current) {
     return {settings: out, errors};
 }
 
+/** Moved by every write (withLock, removeProduct, saveSettings) - see withLock. */
+let generation = 0;
+
 export async function saveSettings(next) {
     const state = getPluginStates()[NAME] || {};
     savePluginState(NAME, {settings: {...(state.settings || {}), ...next}});
+    generation++;
 }
 
 /** The payment methods a shopper can choose now, in order. */
@@ -224,20 +228,31 @@ export const updateProductExt = (id, owner, fn) => withLock(async () => {
 });
 
 export async function removeProduct(id) {
+    generation++;
     await deleteEntry(PRODUCTS, id);
+    generation++;
     await refreshShelf();
 }
 
 // ---- Orders --------------------------------------------------------------------
 
 let chain = Promise.resolve();
-/** Run `fn` after every write already queued - order writes never interleave. */
+/**
+ * Run `fn` after every write already queued - order writes never interleave.
+ * It also moves the write generation as each write starts and ends, which is
+ * what the badge cache (and Takeaway's, through services.writeGeneration) is
+ * checked against: an answer worked out across a write is never kept.
+ */
 export function withLock(fn) {
-    const run = chain.then(fn, fn);
-    chain = run.catch(() => {});
+    const go = () => { generation++; return fn(); };
+    const run = chain.then(go, go);
+    chain = run.catch(() => {}).then(() => { generation++; });
     return run;
 }
 
+/** Changes whenever an order, product or the settings are written. */
+export const writeGeneration = () => generation;
+
 export async function allOrders() {
     const {entries = []} = await listEntries(ORDERS, {limit: 0, sort: 'createdAt', order: 'desc'});
     return entries;
@@ -416,6 +431,26 @@ export async function moveOrderNow(id, to, {by = 'admin', note = '', restock = f
     }
 }
 
+/**
+ * Record money given back without moving the order - a PARTIAL refund. The
+ * caller holds the lock (refundOrder wraps the provider call and this in one).
+ * A full refund goes through `moveOrderNow(id, 'refunded')` after this.
+ *
+ * @param {string} id
+ * @param {{at: string, amount: number, by: string, note: string, via: string, ref: string}} entry
+ * @param {string} line - the history line ("Refunded £5.00 through Stripe - damaged lid")
+ */
+export async function recordRefundNow(id, entry, line) {
+    const had = await getOrder(id);
+    if (!had) throw Object.assign(new Error('No such order.'), {status: 404});
+    const d = had.data;
+    const refunds = [...(Array.isArray(d.refunds) ? d.refunds : []), entry];
+    const refunded = refunds.reduce((n, r) => n + (Number(r.amount) || 0), 0);
+    // The history keeps the order's status: a part refund is a note on a paid order, not a move.
+    const history = [...(d.history || []), {at: entry.at, status: d.status, by: entry.by, note: String(line || '').slice(0, 500), refund: entry.amount}];
+    return updateEntry(ORDERS, id, {...d, refunds, refunded, history});
+}
+
 /** The admin's own note and the tracking details - no status change. */
 export const annotateOrder = (id, {staffNote, tracking}) => withLock(() => patchOrder(id, {
     ...(staffNote !== undefined ? {staffNote: String(staffNote).slice(0, 4000)} : {}),

package/plugins/shopping-cart/plugin.js

@@ -38,9 +38,10 @@ import {badge, summarise} from './lib/summary.js';
 import * as pay from './lib/payments.js';
 import {
     NAME, allOrders, allProducts, annotateOrder, cleanSettings, cleanTracking, createOrder, ensureCollections, extendOrder,
-    getOrder, getProduct, liveSettings, markPaid, maskSettings, methodsOf, moveOrder, moveOrderNow, publicOrder, removeOrder,
-    refreshShelf, removeProduct, saveProduct, saveSettings, setProviderRef, settingsNow, shelfNow, tokenOk, updateProductExt, withLock
+    getOrder, getProduct, liveSettings, markPaid, maskSettings, methodsOf, moveOrder, moveOrderNow, publicOrder, recordRefundNow, removeOrder,
+    refreshShelf, removeProduct, saveProduct, saveSettings, setProviderRef, settingsNow, shelfNow, tokenOk, updateProductExt, withLock, writeGeneration
 } from './lib/shop.js';
+import {refundPlan} from './lib/refunds.js';
 import {cardHtml, esc, gridHtml} from './lib/render.js';
 
 /** The Site URL setting as an origin, or ''. */
@@ -202,7 +203,7 @@ export default async function shoppingCart(fastify, options) {
     // What extensions may use: the Cart's own data, read the Cart's way.
     registry.services = {
         name: NAME,
-        liveSettings, allOrders, getOrder, allProducts, getProduct, extendOrder, publicOrder,
+        liveSettings, allOrders, getOrder, allProducts, getProduct, extendOrder, publicOrder, writeGeneration,
         formatMoney, orderLabel,
         /** The Site URL as an origin, or '' - sync, for the shopper-facing paths. Email links: `linkBase`. */
         siteBase: () => siteBase(null),
@@ -263,9 +264,18 @@ export default async function shoppingCart(fastify, options) {
             .header('Cache-Control', 'no-store').send(salesCsv(orders, {from, to, timeZone: s.timeZone || 'Europe/London'}));
     });
 
+    // Polled every minute from every admin tab, and it reads every order and product: one answer
+    // is kept for a minute unless anything is written (writeGeneration, moved by every write in
+    // lib/shop.js - admin, checkout, webhooks and extensions alike). One answer for everyone: the
+    // badge is the same for every reader.
+    let badgeMemo = {at: 0, gen: -1, value: null};
     fastify.get('/count', can('read'), async () => {
+        const gen = writeGeneration();
+        if (badgeMemo.gen === gen && Date.now() - badgeMemo.at < 60_000) return badgeMemo.value;
         const [orders, settings, products] = await Promise.all([allOrders(), liveSettings(), allProducts()]);
-        return badge(orders, settings, Date.now(), products);
+        const value = badge(orders, settings, Date.now(), products);
+        if (writeGeneration() === gen) badgeMemo = {at: Date.now(), gen, value};
+        return value;
     });
 
     fastify.get('/extensions', can('read'), async () => ({
@@ -385,47 +395,65 @@ export default async function shoppingCart(fastify, options) {
     });
 
     /**
-     * Refund an order in full. With Stripe or PayPal the money goes back
-     * through them first; only when they say yes is the order marked refunded.
-     * An offline order is marked only - the money goes back the way it came.
+     * Refund an order - the rest of it, or `amount` minor units of what is left. With Stripe or PayPal the
+     * money goes back through them first; only when they say yes is the refund recorded. An offline order is
+     * recorded only - the money goes back the way it came. A refund that leaves nothing outstanding moves the
+     * order to `refunded` (stock back when `restock`); a part refund keeps the status and adds to `refunds`.
+     * Throws {status, message}.
      */
-    /** Refund an order in full (see above). Throws {status, message}. */
-    async function refundOrder(id, {restock = false, note = '', viaProvider = true, by = 'admin'} = {}) {
+    async function refundOrder(id, {amount = null, restock = false, note = '', viaProvider = true, by = 'admin'} = {}) {
         const bad = (status, message) => Object.assign(new Error(message), {status});
         // The whole refund runs under the order lock: two refunds at once would both reach the provider, and a
         // write landing between the provider's yes and ours would be lost. The provider call carries an
-        // Idempotency-Key from the order id, so a retry after a timeout returns the first refund, not a second.
-        const {order, from, how} = await withLock(async () => {
+        // idempotency key from the order id and the refund's ordinal, so a retry after a timeout returns the first
+        // refund, not a second - and the next part refund (a new ordinal) is a new request.
+        const {order, from, how, plan} = await withLock(async () => {
             const o = await getOrder(id);
             if (!o) throw bad(404, 'No such order.');
             const d = o.data;
             if (!['paid', 'fulfilled'].includes(d.status)) throw bad(409, 'Only a paid order can be refunded.');
+            const p = refundPlan(d, amount);
+            const seq = (Array.isArray(d.refunds) ? d.refunds.length : 0) + 1;
             const s = await liveSettings();
             let via = 'marked refunded';
+            let ref = '';
             try {
                 if (viaProvider && d.provider === 'stripe' && d.paymentRef) {
                     if (!s.stripeSecretKey) throw bad(409, 'Stripe is not set up any more - refund it in Stripe, then mark it refunded here.');
-                    await pay.stripeRefund({secretKey: s.stripeSecretKey, paymentIntent: d.paymentRef, idempotencyKey: `${NAME}-refund-${o.id}`});
+                    const r = await pay.stripeRefund({secretKey: s.stripeSecretKey, paymentIntent: d.paymentRef, amount: p.amount,
+                        idempotencyKey: `${NAME}-refund-${o.id}-${seq}`});
                     via = 'refunded through Stripe';
+                    ref = String(r?.id || '');
                 } else if (viaProvider && d.provider === 'paypal' && d.paymentRef) {
                     if (!s.paypalClientId || !s.paypalSecret) throw bad(409, 'PayPal is not set up any more - refund it in PayPal, then mark it refunded here.');
-                    await pay.paypalRefund({creds: {clientId: s.paypalClientId, secret: s.paypalSecret, mode: s.paypalMode}, captureId: d.paymentRef});
+                    const r = await pay.paypalRefund({creds: {clientId: s.paypalClientId, secret: s.paypalSecret, mode: s.paypalMode}, captureId: d.paymentRef,
+                        amount: p.amount, currency: d.currency, requestId: `${NAME}-refund-${o.id}-${seq}`});
                     via = 'refunded through PayPal';
+                    ref = String(r?.id || '');
                 }
             } catch (err) {
                 throw bad(err.status || 502, err.status === 409 ? err.message : `Not refunded: ${err.message}`);
             }
-            const moved = await moveOrderNow(o.id, 'refunded', {by, note: [via, String(note || '')].filter(Boolean).join(' - '), restock: Boolean(restock)});
-            return {...moved, how: via};
+            const now = new Date().toISOString();
+            const money = formatMoney(p.amount, d.currency);
+            const words = [p.full && !p.before ? via : `${money} ${via}`, String(note || '')].filter(Boolean).join(' - ');
+            await recordRefundNow(o.id, {at: now, amount: p.amount, by, note: String(note || '').slice(0, 500), via, ref}, words);
+            if (!p.full) {
+                const kept = await getOrder(o.id);
+                return {order: kept, from: d.status, how: `${via} (${money}; ${formatMoney(p.remaining, d.currency)} left to refund)`, plan: p};
+            }
+            const moved = await moveOrderNow(o.id, 'refunded', {by, note: p.before ? `the last ${money}` : words, restock: Boolean(restock)});
+            return {...moved, how: via, plan: p};
         });
-        announceMove(order, from, 'refunded');
-        return {order, how};
+        if (plan.full) announceMove(order, from, 'refunded');
+        return {order, how, refund: {amount: plan.amount, refunded: plan.after, remaining: plan.remaining, full: plan.full}};
     }
 
+    /** `amount` (minor units) refunds part of what is left; left out, the rest goes back. */
     fastify.post('/orders/:id/refund', can('manage'), async (request, reply) => {
-        const {restock = false, note = '', viaProvider = true} = request.body || {};
+        const {amount = null, restock = false, note = '', viaProvider = true} = request.body || {};
         try {
-            return await refundOrder(request.params.id, {restock, note, viaProvider, by: request.user?.name || request.user?.email || 'admin'});
+            return await refundOrder(request.params.id, {amount, restock, note, viaProvider, by: request.user?.name || request.user?.email || 'admin'});
         } catch (err) {
             return fail(reply, err.status || 500, err.message);
         }

package/plugins/shopping-cart/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shopping-cart",
   "displayName": "Shopping Cart",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "tier": "free",
   "description": "Sell from your site: products with options, stock and pictures, a storefront and a cart that follows shoppers from page to page, and checkout with Stripe, PayPal or payment offline. Orders to fulfil in the sidebar, refunds from the order.",
   "author": "Domma CMS",
@@ -45,7 +45,7 @@
     ],
     "views": {
       "plugin-shopping-cart": {
-        "entry": "shopping-cart/admin/views/shop.js?v=1.6.0",
+        "entry": "shopping-cart/admin/views/shop.js?v=1.6.2",
         "exportName": "shopView"
       }
     }