domma-cms 0.84.1 → 0.85.0

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

@@ -0,0 +1,436 @@
+/**
+ * The Shop's data: products and orders in their collections, the live
+ * settings, order numbers, and the moves an order makes - paid, fulfilled,
+ * cancelled, refunded - with the stock that goes with them.
+ *
+ * Every write to an order goes through `withLock`, one at a time. A Stripe
+ * webhook and the shopper's own return can arrive in the same instant, and
+ * both say "paid": the second must find the first's work done, or the stock
+ * is taken twice.
+ *
+ * @module shopping-cart/lib/shop
+ */
+
+import {randomBytes} from 'crypto';
+import {createCollection, createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
+import {getPluginSettings, getPluginStates, savePluginState} from '../../../server/services/plugins.js';
+import {cleanProduct} from '../public/lib/products.js';
+import {NEXT, SOLD, canMove} from '../public/lib/orders.js';
+import {currencyOf} from '../public/lib/money.js';
+import defaults from '../config.js';
+
+export const NAME = 'shopping-cart';
+export const PRODUCTS = 'shop-products';
+export const ORDERS = 'shop-orders';
+
+/** Keys the settings slideover may write, and which of them are secret. */
+export const SETTING_KEYS = Object.keys(defaults);
+export const SECRET_KEYS = ['stripeSecretKey', 'stripeWebhookSecret', 'paypalSecret'];
+export const MASK = '••••••••';
+
+// ---- Setup ---------------------------------------------------------------------
+
+/** Make the collections that are missing. Every boot: a plugin switched on by copy never has onEnable run. */
+export async function ensureCollections() {
+    const dir = new URL('../collections/', import.meta.url);
+    const fs = await import('fs/promises');
+    for (const slug of [PRODUCTS, ORDERS]) {
+        if (await getCollection(slug)) continue;
+        const schema = JSON.parse(await fs.readFile(new URL(`${slug}.json`, dir), 'utf8'));
+        await createCollection(schema);
+        console.log(`[shopping-cart] Created collection: ${slug}`);
+    }
+}
+
+// ---- Settings ------------------------------------------------------------------
+
+/** The settings as they are NOW - read per request, so a change needs no restart. */
+export async function liveSettings() {
+    const s = await getPluginSettings(NAME);
+    return {...defaults, ...s, currency: currencyOf(s.currency), shopPath: cleanPath(s.shopPath)};
+}
+
+/** The same, synchronously - for shortcodes, which cannot wait. */
+export function settingsNow() {
+    const s = getPluginStates()[NAME]?.settings || {};
+    return {...defaults, ...s, currency: currencyOf(s.currency), shopPath: cleanPath(s.shopPath)};
+}
+
+/** "/shop" from "shop/", "/Shop//", "" - one leading slash, no trailing one. */
+export function cleanPath(p) {
+    const t = '/' + String(p || '/shop').toLowerCase().replace(/[^a-z0-9/_-]/g, '').replace(/\/+/g, '/').replace(/^\/|\/$/g, '');
+    return t === '/' || /^\/(admin|api|plugins|dist|media|assets|login)(\/|$)/.test(t) ? '/shop' : t;
+}
+
+/** For the browser: every setting, secrets masked (or '' when unset). */
+export function maskSettings(s) {
+    const out = {...s};
+    for (const k of SECRET_KEYS) out[k] = s[k] ? MASK : '';
+    return out;
+}
+
+/**
+ * Clean a settings save. A masked secret keeps the stored value; an empty one clears it.
+ *
+ * @returns {{settings: object, errors: Object<string, string>}}
+ */
+export function cleanSettings(input, current) {
+    const errors = {};
+    const out = {};
+    const str = (k, max = 300) => String(input[k] ?? current[k] ?? '').trim().slice(0, max);
+    const bool = (k) => (input[k] === undefined ? Boolean(current[k]) : Boolean(input[k]));
+    const minor = (k) => {
+        const v = input[k] ?? current[k];
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 0 || n > 1e9) { errors[k] = 'An amount, 0 or more.'; return current[k] ?? 0; }
+        return n;
+    };
+    out.shopTitle = str('shopTitle', 80) || 'Shop';
+    out.shopPath = cleanPath(input.shopPath ?? current.shopPath);
+    out.shopIntro = str('shopIntro', 1000);
+    out.currency = currencyOf(input.currency ?? current.currency);
+    out.columns = [2, 3, 4].includes(Number(input.columns)) ? Number(input.columns) : (current.columns || 3);
+    out.showSearch = bool('showSearch');
+    out.showCategories = bool('showCategories');
+    out.floatingCart = bool('floatingCart');
+    out.cartPosition = ['right', 'left'].includes(input.cartPosition) ? input.cartPosition : (current.cartPosition || 'right');
+    out.lowStockAt = Math.max(0, Math.min(1000, Math.round(Number(input.lowStockAt ?? current.lowStockAt) || 0)));
+    out.showStockLeft = bool('showStockLeft');
+    out.termsUrl = str('termsUrl', 300);
+    if (out.termsUrl && !/^(\/(?!\/)|https?:\/\/)/.test(out.termsUrl)) errors.termsUrl = 'A page on this site (/terms) or a full https:// address.';
+
+    const countries = Array.isArray(input.countries) ? input.countries : (current.countries || ['GB']);
+    out.countries = [...new Set(countries.map(c => String(c).toUpperCase()).filter(c => /^[A-Z]{2}$/.test(c)))].slice(0, 250);
+    if (!out.countries.length) errors.countries = 'Pick at least one country you deliver to.';
+    out.shippingFlat = minor('shippingFlat');
+    out.shippingLabel = str('shippingLabel', 60) || 'Delivery';
+    out.freeShippingOver = minor('freeShippingOver');
+    out.allowCollection = bool('allowCollection');
+    out.collectionLabel = str('collectionLabel', 60) || 'Collect in person';
+
+    const rate = Number(input.taxRate ?? current.taxRate);
+    if (!Number.isFinite(rate) || rate < 0 || rate > 100) errors.taxRate = 'A percentage from 0 to 100.';
+    out.taxRate = Number.isFinite(rate) && rate >= 0 && rate <= 100 ? Math.round(rate * 1000) / 1000 : (current.taxRate || 0);
+    out.taxLabel = str('taxLabel', 30) || 'Tax';
+    out.pricesIncludeTax = bool('pricesIncludeTax');
+    out.taxShipping = bool('taxShipping');
+
+    out.stripeEnabled = bool('stripeEnabled');
+    out.paypalEnabled = bool('paypalEnabled');
+    out.paypalMode = input.paypalMode === 'live' ? 'live' : input.paypalMode === 'sandbox' ? 'sandbox' : (current.paypalMode || 'sandbox');
+    out.paypalClientId = str('paypalClientId', 200);
+    out.offlineEnabled = bool('offlineEnabled');
+    out.offlineLabel = str('offlineLabel', 60) || 'Pay offline';
+    out.offlineInstructions = str('offlineInstructions', 2000);
+    for (const k of SECRET_KEYS) {
+        const v = input[k];
+        out[k] = v === undefined || v === MASK ? (current[k] || '') : String(v).trim().slice(0, 300);
+    }
+    if (out.stripeSecretKey && !/^(sk|rk)_(test|live)_[A-Za-z0-9]{10,}$/.test(out.stripeSecretKey)) errors.stripeSecretKey = 'A Stripe secret key starts sk_test_ or sk_live_.';
+    if (out.stripeWebhookSecret && !/^whsec_[A-Za-z0-9]{10,}$/.test(out.stripeWebhookSecret)) errors.stripeWebhookSecret = 'A webhook signing secret starts whsec_.';
+    if (out.stripeEnabled && !out.stripeSecretKey) errors.stripeEnabled = 'Stripe needs its secret key.';
+    if (out.paypalEnabled && (!out.paypalClientId || !out.paypalSecret)) errors.paypalEnabled = 'PayPal needs its client id and secret.';
+    return {settings: out, errors};
+}
+
+export async function saveSettings(next) {
+    const state = getPluginStates()[NAME] || {};
+    savePluginState(NAME, {settings: {...(state.settings || {}), ...next}});
+}
+
+/** The payment methods a shopper can choose now, in order. */
+export function methodsOf(s) {
+    const out = [];
+    if (s.stripeEnabled && s.stripeSecretKey) out.push({id: 'stripe', label: 'Card, Apple Pay or Google Pay'});
+    if (s.paypalEnabled && s.paypalClientId && s.paypalSecret) out.push({id: 'paypal', label: 'PayPal'});
+    if (s.offlineEnabled) out.push({id: 'offline', label: s.offlineLabel || 'Pay offline'});
+    return out;
+}
+
+// ---- Products ------------------------------------------------------------------
+
+export async function allProducts() {
+    const {entries = []} = await listEntries(PRODUCTS, {limit: 0});
+    shelf = entries;
+    return entries;
+}
+
+/**
+ * The products as last read, for the shortcodes: the CMS runs shortcode
+ * handlers synchronously, so they cannot wait on the collection. Refreshed at
+ * boot and after every product or stock write made here.
+ */
+let shelf = [];
+export const shelfNow = () => shelf;
+export const refreshShelf = () => allProducts().catch(() => shelf);
+
+export const getProduct = (id) => getEntry(PRODUCTS, id);
+
+/** A slug no other product has: "mug", "mug-2", … */
+async function uniqueSlug(slug, exceptId = null) {
+    const taken = new Set((await allProducts()).filter(e => e.id !== exceptId).map(e => e.data?.slug));
+    if (!taken.has(slug)) return slug;
+    for (let i = 2; i < 1000; i++) if (!taken.has(`${slug}-${i}`)) return `${slug}-${i}`;
+    return `${slug}-${Date.now()}`;
+}
+
+export async function saveProduct(input, {id = null, currency = 'GBP', by = null} = {}) {
+    const {data, errors} = cleanProduct(input, {currency, minor: true});
+    if (Object.keys(errors).length) return {errors};
+    data.slug = await uniqueSlug(data.slug, id);
+    if (id) {
+        const had = await getProduct(id);
+        if (!had) return {notFound: true};
+        const entry = await updateEntry(PRODUCTS, id, data);
+        await refreshShelf();
+        return {entry};
+    }
+    const entry = await createEntry(PRODUCTS, data, {createdBy: by, source: 'plugin'});
+    await refreshShelf();
+    return {entry};
+}
+
+export async function removeProduct(id) {
+    await deleteEntry(PRODUCTS, id);
+    await refreshShelf();
+}
+
+// ---- Orders --------------------------------------------------------------------
+
+let chain = Promise.resolve();
+/** Run `fn` after every write already queued - order writes never interleave. */
+export function withLock(fn) {
+    const run = chain.then(fn, fn);
+    chain = run.catch(() => {});
+    return run;
+}
+
+export async function allOrders() {
+    const {entries = []} = await listEntries(ORDERS, {limit: 0, sort: 'createdAt', order: 'desc'});
+    return entries;
+}
+
+export const getOrder = (id) => getEntry(ORDERS, id);
+
+/** The next order number: stored in plugin state, never below any order that exists. */
+async function nextNumber() {
+    const state = getPluginStates()[NAME] || {};
+    let n = Number(state.orderSeq) || 0;
+    if (!n) {
+        const orders = await allOrders();
+        n = Math.max(1000, ...orders.map(o => Number(o.data?.number) || 0));
+    }
+    n += 1;
+    savePluginState(NAME, {orderSeq: n});
+    return n;
+}
+
+/**
+ * A new order from a quote and what the shopper typed.
+ *
+ * @returns {Promise<{id, data}>}
+ */
+export function createOrder({quote, checkout, provider, delivery, code = ''}) {
+    return withLock(async () => {
+        const now = new Date().toISOString();
+        const data = {
+            number: await nextNumber(),
+            status: 'pending',
+            token: randomBytes(18).toString('hex'),
+            currency: quote.currency,
+            lines: quote.lines.map(l => ({
+                productId: l.productId, variantId: l.variantId, name: l.name, variantName: l.variantName,
+                optionName: l.optionName, slug: l.slug, image: l.image, sku: l.sku, unitPrice: l.unitPrice,
+                qty: l.qty, lineTotal: l.lineTotal, shippable: l.shippable, weight: l.weight, taxClass: l.taxClass, category: l.category || ''
+            })),
+            subtotal: quote.subtotal,
+            adjustments: quote.adjustments,
+            discount: quote.discount,
+            shipping: quote.shipping,
+            tax: quote.tax,
+            taxIncluded: quote.taxIncluded,
+            total: quote.total,
+            requiresShipping: quote.requiresShipping,
+            delivery,
+            customer: checkout.customer,
+            email: checkout.customer.email,
+            address: checkout.address,
+            note: checkout.note,
+            code,
+            provider,
+            providerRef: '',
+            paymentRef: '',
+            stockTaken: false,
+            history: [{at: now, status: 'pending', by: 'shopper', note: `Checkout with ${provider}`}]
+        };
+        return createEntry(ORDERS, data, {source: 'plugin'});
+    });
+}
+
+/** Merge `patch` into an order's data. Inside the lock. */
+async function patchOrder(id, patch) {
+    const had = await getOrder(id);
+    if (!had) throw Object.assign(new Error('No such order.'), {status: 404});
+    return updateEntry(ORDERS, id, {...had.data, ...patch});
+}
+
+/** Record the provider's reference for a pending order (session / PayPal order id). */
+export const setProviderRef = (id, providerRef) => withLock(() => patchOrder(id, {providerRef}));
+
+/** Stock out (-1) or back in (+1) for an order's lines. */
+async function moveStock(order, sign) {
+    const byProduct = new Map();
+    for (const l of order.lines || []) {
+        if (!byProduct.has(l.productId)) byProduct.set(l.productId, []);
+        byProduct.get(l.productId).push(l);
+    }
+    for (const [productId, lines] of byProduct) {
+        const entry = await getProduct(productId);
+        const p = entry?.data;
+        if (!p || !p.trackStock) continue;
+        const next = {...p, variants: (p.variants || []).map(v => ({...v}))};
+        for (const l of lines) {
+            if (next.variants.length) {
+                const v = next.variants.find(x => x.id === l.variantId);
+                if (v) v.stock = Math.max(0, (Number(v.stock) || 0) + sign * l.qty);
+            } else {
+                next.stock = Math.max(0, (Number(next.stock) || 0) + sign * l.qty);
+            }
+        }
+        await updateEntry(PRODUCTS, productId, next);
+    }
+    await refreshShelf();
+}
+
+/**
+ * Money received. Idempotent: an order already paid (or further on) is left
+ * as it is and `changed` is false, so the webhook and the return can race.
+ *
+ * @param {string} id
+ * @param {{provider?: string, ref?: string, payment?: string, by?: string, note?: string}} info
+ * @returns {Promise<{order: object, changed: boolean, from?: string}>}
+ */
+export function markPaid(id, info = {}) {
+    return withLock(async () => {
+        const had = await getOrder(id);
+        if (!had) throw Object.assign(new Error('No such order.'), {status: 404});
+        const d = had.data;
+        if (!['pending', 'awaiting'].includes(d.status)) return {order: had, changed: false};
+        if (!d.stockTaken) await moveStock(d, -1);
+        const now = new Date().toISOString();
+        const order = await updateEntry(ORDERS, id, {
+            ...d,
+            status: 'paid',
+            paidAt: now,
+            stockTaken: true,
+            ...(info.ref ? {providerRef: info.ref} : {}),
+            ...(info.payment ? {paymentRef: info.payment} : {}),
+            history: [...(d.history || []), {at: now, status: 'paid', by: info.by || d.provider, note: info.note || ''}]
+        });
+        return {order, changed: true, from: d.status};
+    });
+}
+
+/**
+ * Move an order by hand (the admin). Only the moves in NEXT; stock follows:
+ * taken when it becomes paid, given back on a refund when `restock` is set.
+ *
+ * @returns {Promise<{order: object, from: string}>}
+ */
+export function moveOrder(id, to, {by = 'admin', note = '', restock = false, tracking = null} = {}) {
+    return withLock(async () => {
+        const had = await getOrder(id);
+        if (!had) throw Object.assign(new Error('No such order.'), {status: 404});
+        const d = had.data;
+        if (!canMove(d.status, to)) {
+            throw Object.assign(new Error(`An order that is ${d.status} cannot become ${to}. It can become: ${(NEXT[d.status] || []).join(', ') || 'nothing'}.`), {status: 409});
+        }
+        const now = new Date().toISOString();
+        const patch = {status: to, history: [...(d.history || []), {at: now, status: to, by, note: String(note || '').slice(0, 500)}]};
+        if (to === 'paid' && !d.stockTaken) { await moveStock(d, -1); patch.stockTaken = true; }
+        if (to === 'paid' && !d.paidAt) patch.paidAt = now;
+        if (to === 'fulfilled') {
+            patch.fulfilledAt = now;
+            if (tracking) patch.tracking = tracking;
+        }
+        if (to === 'cancelled') patch.cancelledAt = now;
+        if (to === 'refunded') {
+            patch.refundedAt = now;
+            if (restock && d.stockTaken) { await moveStock(d, +1); patch.stockTaken = false; patch.restocked = true; }
+        }
+        const order = await updateEntry(ORDERS, id, {...d, ...patch});
+        return {order, from: d.status};
+    });
+}
+
+/** 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)} : {}),
+    ...(tracking !== undefined ? {tracking} : {})
+}));
+
+/** Extensions keep their own facts on an order (emails sent, a code used) under `ext.<owner>`. */
+export const extendOrder = (id, owner, facts) => withLock(async () => {
+    const had = await getOrder(id);
+    if (!had) return null;
+    const ext = {...(had.data.ext || {}), [owner]: {...(had.data.ext?.[owner] || {}), ...facts}};
+    return updateEntry(ORDERS, id, {...had.data, ext});
+});
+
+/** Only an order that never took money can be deleted. */
+export const removeOrder = (id) => withLock(async () => {
+    const had = await getOrder(id);
+    if (!had) throw Object.assign(new Error('No such order.'), {status: 404});
+    if (SOLD.has(had.data.status) || had.data.status === 'refunded') {
+        throw Object.assign(new Error('A paid order is a record of a sale - refund or keep it, but it cannot be deleted.'), {status: 409});
+    }
+    await deleteEntry(ORDERS, id);
+});
+
+/** Tracking details, cleaned: carrier, number, and an https link. */
+export function cleanTracking(t) {
+    if (!t || typeof t !== 'object') return null;
+    const url = String(t.url || '').trim();
+    const out = {
+        carrier: String(t.carrier || '').trim().slice(0, 60),
+        number: String(t.number || '').trim().slice(0, 80),
+        url: /^https:\/\/[^\s"'<>]+$/.test(url) ? url.slice(0, 400) : ''
+    };
+    return out.carrier || out.number || out.url ? out : null;
+}
+
+// ---- What a shopper may see of their order ------------------------------------
+
+export function publicOrder(entry) {
+    const d = entry.data;
+    return {
+        id: entry.id,
+        number: d.number,
+        status: d.status,
+        currency: d.currency,
+        lines: d.lines.map(l => ({productId: l.productId, variantId: l.variantId || '', name: l.name, variantName: l.variantName, optionName: l.optionName, qty: l.qty,
+            unitPrice: l.unitPrice, lineTotal: l.lineTotal, image: l.image, slug: l.slug})),
+        subtotal: d.subtotal,
+        adjustments: (d.adjustments || []).map(a => ({stage: a.stage, label: a.label, amount: a.amount, included: Boolean(a.included)})),
+        total: d.total,
+        customer: {name: d.customer?.name || ''},
+        email: d.email,
+        address: d.address,
+        delivery: d.delivery,
+        provider: d.provider,
+        tracking: d.tracking || null,
+        placedAt: entry.meta?.createdAt,
+        paidAt: d.paidAt || null,
+        fulfilledAt: d.fulfilledAt || null
+    };
+}
+
+/** Does this token open this order's receipt? Constant-time. */
+export function tokenOk(order, token) {
+    const a = Buffer.from(String(order?.data?.token || ''));
+    const b = Buffer.from(String(token || ''));
+    if (!a.length || a.length !== b.length) return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+    return diff === 0;
+}

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

@@ -0,0 +1,127 @@
+/**
+ * The Shop's Overview figures and the sidebar badge. PURE: orders and
+ * products in, plain numbers and text out.
+ *
+ * Sales are orders that took money and kept it (paid or fulfilled), dated by
+ * when they were PAID - an order placed on Monday and paid on Tuesday is
+ * Tuesday's sale.
+ *
+ * @module shopping-cart/lib/summary
+ */
+
+import {SOLD, orderLabel} from '../public/lib/orders.js';
+import {formatMoney} from '../public/lib/money.js';
+import {totalStock} from '../public/lib/products.js';
+
+const DAY = 86400000;
+
+/** "2026-09-26" in the server's time zone. */
+export const dayKey = (t) => {
+    const d = new Date(t);
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
+
+const soldAt = (o) => new Date(o.data.paidAt || o.meta?.createdAt).getTime();
+
+/**
+ * @param {{id, data, meta}[]} orders
+ * @param {{id, data}[]} products
+ * @param {object} settings
+ * @param {number} [now]
+ */
+export function summarise(orders, products, settings, now = Date.now()) {
+    const cur = settings.currency;
+    const sold = orders.filter(o => SOLD.has(o.data?.status));
+    const within = (days) => sold.filter(o => soldAt(o) >= now - days * DAY);
+    const sum = (list) => list.reduce((s, o) => s + (o.data.total || 0), 0);
+    const startToday = new Date(now); startToday.setHours(0, 0, 0, 0);
+
+    const today = sold.filter(o => soldAt(o) >= startToday.getTime());
+    const d30 = within(30);
+    const prev30 = sold.filter(o => soldAt(o) < now - 30 * DAY && soldAt(o) >= now - 60 * DAY);
+
+    // Thirty days of sales, oldest first, including the empty days.
+    const series = [];
+    const byDay = new Map();
+    for (const o of d30) {
+        const k = dayKey(soldAt(o));
+        const had = byDay.get(k) || {revenue: 0, orders: 0};
+        byDay.set(k, {revenue: had.revenue + (o.data.total || 0), orders: had.orders + 1});
+    }
+    for (let i = 29; i >= 0; i--) {
+        const k = dayKey(now - i * DAY);
+        series.push({day: k, ...(byDay.get(k) || {revenue: 0, orders: 0})});
+    }
+
+    const units = new Map();
+    for (const o of d30) {
+        for (const l of o.data.lines || []) {
+            const had = units.get(l.productId) || {productId: l.productId, name: l.name, qty: 0, revenue: 0};
+            had.qty += l.qty;
+            had.revenue += l.lineTotal;
+            units.set(l.productId, had);
+        }
+    }
+    const topProducts = [...units.values()].sort((a, b) => b.revenue - a.revenue).slice(0, 5);
+
+    const lowAt = Number(settings.lowStockAt) || 0;
+    const lowStock = products
+        .filter(p => p.data?.status === 'active' && p.data?.trackStock)
+        .map(p => ({id: p.id, name: p.data.name, stock: totalStock(p.data),
+            variants: (p.data.variants || []).filter(v => (Number(v.stock) || 0) <= lowAt).map(v => `${v.name}: ${v.stock ?? 0}`)}))
+        .filter(p => p.stock <= lowAt || p.variants.length)
+        .sort((a, b) => a.stock - b.stock);
+
+    const toFulfil = orders.filter(o => o.data?.status === 'paid');
+    const awaiting = orders.filter(o => o.data?.status === 'awaiting');
+    const abandoned = orders.filter(o => o.data?.status === 'pending' && new Date(o.meta?.createdAt).getTime() < now - 3600000
+        && new Date(o.meta?.createdAt).getTime() >= now - 7 * DAY);
+
+    const revenue30 = sum(d30);
+    const revenuePrev = sum(prev30);
+    return {
+        currency: cur,
+        today: {revenue: sum(today), orders: today.length},
+        days30: {revenue: revenue30, orders: d30.length, average: d30.length ? Math.round(revenue30 / d30.length) : 0,
+            change: revenuePrev ? Math.round((revenue30 - revenuePrev) / revenuePrev * 100) : null},
+        allTime: {revenue: sum(sold), orders: sold.length},
+        series,
+        topProducts,
+        lowStock: lowStock.slice(0, 10),
+        lowStockCount: lowStock.length,
+        toFulfil: toFulfil.length,
+        awaiting: awaiting.length,
+        abandoned: abandoned.length,
+        products: {total: products.length, active: products.filter(p => p.data?.status === 'active').length},
+        recent: orders.slice(0, 8).map(o => ({id: o.id, number: o.data.number, status: o.data.status, total: o.data.total,
+            name: o.data.customer?.name || o.data.email, at: o.meta?.createdAt, items: (o.data.lines || []).reduce((s, l) => s + l.qty, 0)}))
+    };
+}
+
+/** The sidebar badge: paid orders waiting to be sent. Details in the hover. */
+export function badge(orders, settings, now = Date.now()) {
+    const cur = settings.currency;
+    const toFulfil = orders.filter(o => o.data?.status === 'paid')
+        .sort((a, b) => new Date(a.data.paidAt || a.meta?.createdAt) - new Date(b.data.paidAt || b.meta?.createdAt));
+    const awaiting = orders.filter(o => o.data?.status === 'awaiting').length;
+    const n = toFulfil.length;
+    const oldest = n ? now - new Date(toFulfil[0].data.paidAt || toFulfil[0].meta?.createdAt).getTime() : 0;
+    return {
+        count: n,
+        label: n ? `${n} order${n === 1 ? '' : 's'} to fulfil` : 'No orders waiting',
+        // Red only when something has waited more than two days.
+        ...(oldest > 2 * DAY ? {tone: 'danger'} : {}),
+        details: {
+            title: 'Shop',
+            rows: [
+                {label: 'To fulfil', value: String(n)},
+                ...(awaiting ? [{label: 'Awaiting payment', value: String(awaiting)}] : [])
+            ],
+            items: toFulfil.slice(0, 6).map(o => ({
+                text: `${orderLabel(o.data)} ${o.data.customer?.name || o.data.email || ''}`.trim(),
+                meta: formatMoney(o.data.total, cur)
+            })),
+            empty: 'Nothing to send.'
+        }
+    };
+}