domma-cms 0.84.0 → 0.85.0

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

@@ -0,0 +1,281 @@
+/**
+ * Stripe and PayPal, spoken to over their REST APIs with `fetch` - no SDK to
+ * install, nothing to keep in step. Both are HOSTED checkouts: the shopper
+ * types card details on Stripe's or PayPal's page, never on ours, so no card
+ * number ever reaches this server.
+ *
+ *   Stripe:  create a Checkout Session -> shopper pays there -> back to the
+ *            receipt page, which asks Stripe whether the session is paid.
+ *            The webhook (checkout.session.completed) catches a shopper who
+ *            closed the tab before coming back.
+ *   PayPal:  create an order -> shopper approves there -> back to our return
+ *            route, which CAPTURES it (that is when the money moves).
+ *
+ * Either way an order is only marked paid on the provider's word, for the
+ * order's own amount and currency - never on a query string.
+ *
+ * @module shopping-cart/lib/payments
+ */
+
+import {createHmac, timingSafeEqual} from 'crypto';
+import {fromMinor} from '../public/lib/money.js';
+
+const TIMEOUT = 15000;
+
+export class PaymentError extends Error {
+    constructor(message, {status = 502, provider = ''} = {}) {
+        super(message);
+        this.status = status;
+        this.provider = provider;
+    }
+}
+
+/** A provider's error body, as one readable line. */
+function reason(body, fallback) {
+    return body?.error?.message || body?.message || body?.details?.[0]?.description || body?.error_description
+        || body?.name || fallback;
+}
+
+async function call(url, init, provider) {
+    let res;
+    try {
+        res = await fetch(url, {...init, signal: AbortSignal.timeout(TIMEOUT)});
+    } catch (err) {
+        throw new PaymentError(`${provider} could not be reached (${err.name === 'TimeoutError' ? 'timed out' : err.message}).`, {provider});
+    }
+    let body = null;
+    try { body = await res.json(); } catch { /* an empty or HTML answer */ }
+    if (!res.ok) throw Object.assign(new PaymentError(`${provider}: ${reason(body, `HTTP ${res.status}`)}`, {provider, status: res.status >= 500 ? 502 : 400}), {body, httpStatus: res.status});
+    return body;
+}
+
+// ---- Stripe ------------------------------------------------------------------
+
+const STRIPE = 'https://api.stripe.com/v1';
+
+/** Stripe's form encoding, nested keys and arrays included: a[b][0][c]=d. */
+export function stripeForm(obj, prefix = '', out = new URLSearchParams()) {
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined || v === null) continue;
+        const key = prefix ? `${prefix}[${k}]` : k;
+        if (typeof v === 'object') stripeForm(v, key, out);
+        else out.append(key, String(v));
+    }
+    return out;
+}
+
+function stripeInit(secretKey, method = 'GET', form = null) {
+    return {
+        method,
+        headers: {
+            Authorization: `Bearer ${secretKey}`,
+            ...(form ? {'Content-Type': 'application/x-www-form-urlencoded'} : {}),
+            'Stripe-Version': '2024-06-20'
+        },
+        ...(form ? {body: form.toString()} : {})
+    };
+}
+
+/** "sk_test_…" or "sk_live_…" / restricted "rk_…": which mode a key is for. */
+export const stripeMode = (key) => (/^(sk|rk)_live_/.test(key || '') ? 'live' : /^(sk|rk)_test_/.test(key || '') ? 'test' : '');
+
+/**
+ * The Checkout Session's line items. Itemised when the lines add up to the
+ * total on their own (plus delivery and added tax); one "Order #n" line when a
+ * discount is in play, since Stripe only discounts through its own coupons.
+ */
+export function stripeLineItems(order) {
+    const cur = String(order.currency).toLowerCase();
+    const item = (name, amount, qty = 1, description = '', image = '') => ({
+        quantity: qty,
+        price_data: {
+            currency: cur,
+            unit_amount: amount,
+            product_data: {name: name.slice(0, 250), ...(description ? {description: description.slice(0, 500)} : {}),
+                ...(image ? {images: {0: image}} : {})}
+        }
+    });
+    const discount = order.adjustments.some(a => a.stage === 'discount' && a.amount < 0);
+    const odd = order.adjustments.some(a => !a.included && a.amount < 0 && a.stage !== 'discount');
+    if (discount || odd) {
+        const what = order.lines.map(l => `${l.qty} × ${l.name}${l.variantName ? ` (${l.variantName})` : ''}`).join(', ');
+        return [item(`Order #${order.number}`, order.total, 1, what)];
+    }
+    const items = order.lines.map(l => item(l.variantName ? `${l.name} (${l.variantName})` : l.name, l.unitPrice, l.qty, '',
+        /^https:\/\//.test(l.image || '') ? l.image : ''));
+    for (const a of order.adjustments) {
+        if (a.included || a.amount <= 0) continue;
+        items.push(item(a.label, a.amount));
+    }
+    return items;
+}
+
+/**
+ * Start a Stripe Checkout Session for an order.
+ *
+ * @returns {Promise<{id: string, url: string}>}
+ */
+export async function stripeCreateSession({secretKey, order, successUrl, cancelUrl, shopName = ''}) {
+    const items = stripeLineItems(order);
+    const form = stripeForm({
+        mode: 'payment',
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+        client_reference_id: order.id,
+        customer_email: order.customer?.email || undefined,
+        metadata: {orderId: order.id, orderNumber: order.number},
+        payment_intent_data: {metadata: {orderId: order.id, orderNumber: order.number},
+            description: `${shopName ? `${shopName} ` : ''}order #${order.number}`.slice(0, 1000)},
+        line_items: Object.fromEntries(items.map((x, i) => [i, x]))
+    });
+    const s = await call(`${STRIPE}/checkout/sessions`, stripeInit(secretKey, 'POST', form), 'Stripe');
+    if (!s?.url) throw new PaymentError('Stripe did not return a payment page.', {provider: 'Stripe'});
+    return {id: s.id, url: s.url};
+}
+
+/** A session as Stripe has it now. */
+export async function stripeGetSession({secretKey, sessionId}) {
+    if (!/^cs_[A-Za-z0-9_]{8,200}$/.test(String(sessionId))) throw new PaymentError('Not a Stripe session.', {status: 400, provider: 'Stripe'});
+    return call(`${STRIPE}/checkout/sessions/${sessionId}`, stripeInit(secretKey), 'Stripe');
+}
+
+/**
+ * Did this session pay for this order, in full? Returns the payment reference
+ * when it did, null when it has not (yet).
+ */
+export function stripeSessionPaid(session, order) {
+    if (!session || session.payment_status !== 'paid') return null;
+    if (session.client_reference_id !== order.id && session.metadata?.orderId !== order.id) return null;
+    if (String(session.currency).toUpperCase() !== order.currency || Number(session.amount_total) !== order.total) return null;
+    return {ref: session.id, payment: typeof session.payment_intent === 'string' ? session.payment_intent : session.payment_intent?.id || ''};
+}
+
+export async function stripeRefund({secretKey, paymentIntent, amount}) {
+    const form = stripeForm({payment_intent: paymentIntent, ...(amount ? {amount} : {})});
+    return call(`${STRIPE}/refunds`, stripeInit(secretKey, 'POST', form), 'Stripe');
+}
+
+/** Can this key talk to Stripe? */
+export async function stripeTest({secretKey}) {
+    await call(`${STRIPE}/balance`, stripeInit(secretKey), 'Stripe');
+    return {ok: true, mode: stripeMode(secretKey)};
+}
+
+/**
+ * Verify a webhook's `Stripe-Signature` header over the raw body.
+ *
+ * @param {Buffer|string} raw
+ * @param {string} header - "t=…,v1=…[,v1=…]"
+ * @param {string} secret - "whsec_…"
+ * @param {number} [toleranceSec]
+ * @param {number} [nowSec]
+ */
+export function stripeVerify(raw, header, secret, toleranceSec = 300, nowSec = Math.floor(Date.now() / 1000)) {
+    if (!secret || !header) return false;
+    const parts = String(header).split(',').map(s => s.split('='));
+    const t = parts.find(([k]) => k === 't')?.[1];
+    const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
+    if (!t || !sigs.length || !/^\d+$/.test(t)) return false;
+    if (Math.abs(nowSec - Number(t)) > toleranceSec) return false;
+    const expected = createHmac('sha256', secret).update(`${t}.`).update(raw).digest();
+    return sigs.some(s => {
+        const got = Buffer.from(s, 'hex');
+        return got.length === expected.length && timingSafeEqual(got, expected);
+    });
+}
+
+// ---- PayPal ------------------------------------------------------------------
+
+const PAYPAL = {sandbox: 'https://api-m.sandbox.paypal.com', live: 'https://api-m.paypal.com'};
+const tokens = new Map();
+
+const paypalBase = (mode) => PAYPAL[mode === 'live' ? 'live' : 'sandbox'];
+
+async function paypalToken({clientId, secret, mode}) {
+    const key = `${mode}:${clientId}`;
+    const had = tokens.get(key);
+    if (had && had.until > Date.now()) return had.token;
+    const body = await call(`${paypalBase(mode)}/v1/oauth2/token`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Basic ${Buffer.from(`${clientId}:${secret}`).toString('base64')}`,
+            'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        body: 'grant_type=client_credentials'
+    }, 'PayPal');
+    tokens.set(key, {token: body.access_token, until: Date.now() + Math.max(60, (body.expires_in || 300) - 60) * 1000});
+    return body.access_token;
+}
+
+async function paypalCall(creds, method, path, payload) {
+    const token = await paypalToken(creds);
+    return call(`${paypalBase(creds.mode)}${path}`, {
+        method,
+        headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Prefer: 'return=representation'},
+        ...(payload ? {body: JSON.stringify(payload)} : {})
+    }, 'PayPal');
+}
+
+/**
+ * Create a PayPal order for ours; the shopper approves it at `url`.
+ *
+ * @returns {Promise<{id: string, url: string}>}
+ */
+export async function paypalCreateOrder({creds, order, returnUrl, cancelUrl, shopName = ''}) {
+    const o = await paypalCall(creds, 'POST', '/v2/checkout/orders', {
+        intent: 'CAPTURE',
+        purchase_units: [{
+            reference_id: order.id,
+            custom_id: order.id,
+            description: `${shopName ? `${shopName} ` : ''}order #${order.number}`.slice(0, 127),
+            amount: {currency_code: order.currency, value: fromMinor(order.total, order.currency)}
+        }],
+        payment_source: {paypal: {experience_context: {
+            return_url: returnUrl,
+            cancel_url: cancelUrl,
+            user_action: 'PAY_NOW',
+            shipping_preference: 'NO_SHIPPING',
+            ...(shopName ? {brand_name: shopName.slice(0, 127)} : {})
+        }}}
+    });
+    const url = (o.links || []).find(l => l.rel === 'payer-action' || l.rel === 'approve')?.href;
+    if (!url) throw new PaymentError('PayPal did not return a payment page.', {provider: 'PayPal'});
+    return {id: o.id, url};
+}
+
+/**
+ * Capture an approved PayPal order - this is when the money moves. Already
+ * captured (a refresh, a second tab) reads the order instead of failing.
+ */
+export async function paypalCapture({creds, paypalOrderId}) {
+    if (!/^[A-Z0-9]{8,40}$/.test(String(paypalOrderId))) throw new PaymentError('Not a PayPal order.', {status: 400, provider: 'PayPal'});
+    try {
+        return await paypalCall(creds, 'POST', `/v2/checkout/orders/${paypalOrderId}/capture`, {});
+    } catch (err) {
+        if (err.httpStatus === 422 && JSON.stringify(err.body || {}).includes('ORDER_ALREADY_CAPTURED')) {
+            return paypalCall(creds, 'GET', `/v2/checkout/orders/${paypalOrderId}`);
+        }
+        throw err;
+    }
+}
+
+/** Did this PayPal order pay for ours, in full? {ref, payment} or null. */
+export function paypalPaid(pp, order) {
+    if (!pp || pp.status !== 'COMPLETED') return null;
+    const unit = (pp.purchase_units || [])[0] || {};
+    if (unit.reference_id !== order.id && unit.custom_id !== order.id) return null;
+    const capture = (unit.payments?.captures || []).find(c => c.status === 'COMPLETED');
+    if (!capture) return null;
+    if (capture.amount?.currency_code !== order.currency || capture.amount?.value !== fromMinor(order.total, order.currency)) return null;
+    return {ref: pp.id, payment: capture.id};
+}
+
+export async function paypalRefund({creds, captureId}) {
+    return paypalCall(creds, 'POST', `/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {});
+}
+
+export async function paypalTest({creds}) {
+    tokens.delete(`${creds.mode}:${creds.clientId}`);
+    await paypalToken(creds);
+    return {ok: true, mode: creds.mode === 'live' ? 'live' : 'sandbox'};
+}

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

@@ -0,0 +1,232 @@
+/**
+ * The price of a basket - the ONE place a total is worked out. The storefront
+ * shows what this returns and checkout charges what this returns; the prices a
+ * browser sends are never read, only product ids, options and quantities.
+ *
+ *   subtotal (lines at today's prices, capped at the stock there is)
+ *     -> discount  -> shipping  -> tax   (the stages)
+ *     -> total
+ *
+ * Each stage has a built-in handler (none / a flat rate / a flat tax rate,
+ * from the Cart's settings) that an extension can replace - Shopping Cart Pro
+ * brings discount codes, shipping zones and tax rules this way (see
+ * extensions.js). A handler gets the basket so far and returns adjustments:
+ * `{label, amount}` in minor units, negative for a discount; `included: true`
+ * for tax already inside the prices (shown, not added).
+ *
+ * @module shopping-cart/lib/pricing
+ */
+
+import {includedTax, percentOf} from '../public/lib/money.js';
+import {available, unitPrice, variantOf} from '../public/lib/products.js';
+
+export const STAGES = ['discount', 'shipping', 'tax'];
+export const MAX_LINES = 100;
+export const MAX_QTY = 999;
+
+/**
+ * What a browser sent, as lines: `[{productId, variantId, qty}]`, the same
+ * product and option merged, junk dropped.
+ *
+ * @param {unknown} raw
+ * @returns {{productId: string, variantId: string, qty: number}[]}
+ */
+export function cleanLines(raw) {
+    const out = new Map();
+    for (const l of Array.isArray(raw) ? raw : []) {
+        const productId = String(l?.productId ?? l?.id ?? '').slice(0, 64);
+        const variantId = String(l?.variantId ?? '').slice(0, 32);
+        const qty = Math.floor(Number(l?.qty));
+        if (!/^[\w-]{1,64}$/.test(productId) || !(qty > 0)) continue;
+        const key = `${productId}:${variantId}`;
+        const had = out.get(key);
+        out.set(key, {productId, variantId, qty: Math.min(MAX_QTY, (had?.qty || 0) + qty)});
+        if (out.size >= MAX_LINES) break;
+    }
+    return [...out.values()];
+}
+
+// ---- The built-in handlers -------------------------------------------------
+
+/** No discounts in the free Cart: Pro's codes replace this. */
+export function builtInDiscount() {
+    return [];
+}
+
+/**
+ * One delivery rate, free over a threshold, and collection when offered.
+ * Nothing to ship (every line a download or a service) -> no delivery line.
+ */
+export function builtInShipping({requiresShipping, settings, input, runningTotal}) {
+    if (!requiresShipping) return [];
+    if (settings.allowCollection && input.delivery === 'collect') {
+        return [{label: settings.collectionLabel || 'Collection', amount: 0}];
+    }
+    const over = Number(settings.freeShippingOver) || 0;
+    if (over > 0 && runningTotal >= over) return [{label: 'Free delivery', amount: 0}];
+    const rate = Number(settings.shippingFlat) || 0;
+    return [{label: settings.shippingLabel || 'Delivery', amount: rate}];
+}
+
+/**
+ * One tax rate for everything. Inclusive prices (UK VAT, most of Europe) show
+ * the tax held inside the total; exclusive prices (US sales tax) add it.
+ */
+export function builtInTax({settings, runningTotal, adjustments}) {
+    const rate = Number(settings.taxRate) || 0;
+    if (rate <= 0) return [];
+    const shipping = adjustments.filter(a => a.stage === 'shipping').reduce((s, a) => s + a.amount, 0);
+    const base = Math.max(0, settings.taxShipping ? runningTotal : runningTotal - shipping);
+    const label = settings.taxLabel || 'Tax';
+    if (settings.pricesIncludeTax) {
+        return [{label: `Includes ${label} (${rate}%)`, amount: includedTax(base, rate), included: true}];
+    }
+    return [{label: `${label} (${rate}%)`, amount: percentOf(base, rate)}];
+}
+
+export const BUILT_IN = {discount: builtInDiscount, shipping: builtInShipping, tax: builtInTax};
+
+/** A handler's answer, trusted no further than this. */
+function cleanAdjustments(result, stage) {
+    const list = Array.isArray(result) ? result : Array.isArray(result?.adjustments) ? result.adjustments : [];
+    return list
+        .filter(a => a && Number.isFinite(Number(a.amount)))
+        .slice(0, 20)
+        .map(a => ({
+            stage,
+            label: String(a.label || stage).slice(0, 120),
+            amount: Math.round(Number(a.amount)),
+            ...(a.included ? {included: true} : {}),
+            ...(a.code ? {code: String(a.code).slice(0, 60)} : {}),
+            ...(a.ref ? {ref: String(a.ref).slice(0, 60)} : {})
+        }));
+}
+
+/**
+ * Price a basket.
+ *
+ * @param {object} args
+ * @param {{productId, variantId, qty}[]} args.lines - cleanLines() output
+ * @param {Map<string, {id, data}>} args.products     - by id, every product the lines name
+ * @param {object} args.settings                      - the Cart's live settings
+ * @param {object} [args.input]                       - {code, country, region, postcode, delivery}
+ * @param {Object<string, Function>} [args.handlers]  - stage -> handler; missing = built in
+ * @returns {Promise<object>} the quote
+ */
+export async function priceBasket({lines, products, settings, input = {}, handlers = {}}) {
+    const currency = settings.currency || 'GBP';
+    const out = [];
+    const problems = [];
+
+    for (const l of lines) {
+        const entry = products.get(l.productId);
+        const p = entry?.data;
+        if (!p || p.status !== 'active') {
+            problems.push({productId: l.productId, variantId: l.variantId, message: 'No longer on sale - taken out.'});
+            continue;
+        }
+        const v = variantOf(p, l.variantId);
+        if (!v) {
+            problems.push({productId: l.productId, variantId: l.variantId, message: `${p.name}: that option is gone - taken out.`});
+            continue;
+        }
+        const can = available(p, l.variantId);
+        let qty = l.qty;
+        if (can <= 0) {
+            problems.push({productId: l.productId, variantId: l.variantId, message: `${p.name}${v.name ? ` (${v.name})` : ''} is sold out.`});
+            continue;
+        }
+        if (qty > can) {
+            problems.push({productId: l.productId, variantId: l.variantId, message: `Only ${can} of ${p.name}${v.name ? ` (${v.name})` : ''} left - quantity lowered.`});
+            qty = can;
+        }
+        const unit = unitPrice(p, l.variantId);
+        out.push({
+            productId: l.productId,
+            variantId: l.variantId,
+            name: p.name,
+            variantName: v.name || '',
+            optionName: p.optionName || '',
+            slug: p.slug,
+            image: p.images?.[0] || '',
+            sku: v.sku || p.sku || '',
+            unitPrice: unit,
+            qty,
+            lineTotal: unit * qty,
+            available: can === Infinity ? null : can,
+            shippable: p.shippable !== false,
+            weight: Number.isInteger(p.weight) ? p.weight : null,
+            taxClass: p.taxClass || 'standard',
+            category: p.category || ''
+        });
+    }
+
+    const subtotal = out.reduce((s, l) => s + l.lineTotal, 0);
+    const requiresShipping = out.some(l => l.shippable);
+    const weight = out.reduce((s, l) => s + (l.weight || 0) * l.qty, 0);
+    const adjustments = [];
+    const notes = [];
+    let shippingChoices = [];
+    let runningTotal = subtotal;
+
+    for (const stage of STAGES) {
+        const handler = typeof handlers[stage] === 'function' ? handlers[stage] : BUILT_IN[stage];
+        let result;
+        try {
+            result = await handler({
+                stage, lines: out, subtotal, runningTotal, currency, settings, input,
+                adjustments: [...adjustments], requiresShipping, weight
+            });
+        } catch (err) {
+            // An extension that throws must not take checkout down with it:
+            // fall back to the built-in rule for this stage and say so.
+            result = await BUILT_IN[stage]({stage, lines: out, subtotal, runningTotal, currency, settings, input,
+                adjustments: [...adjustments], requiresShipping, weight});
+            notes.push({stage, message: `The ${stage} rules failed (${err?.message || err}); the standard ${stage} was used.`, internal: true});
+        }
+        let adds = cleanAdjustments(result, stage);
+        // A discount can take the basket to nothing, never below it.
+        if (stage === 'discount') {
+            let room = runningTotal;
+            adds = adds.map(a => {
+                const amount = Math.max(-room, Math.min(0, a.amount));
+                room += amount;
+                return {...a, amount};
+            });
+        }
+        for (const a of adds) {
+            adjustments.push(a);
+            if (!a.included) runningTotal += a.amount;
+        }
+        for (const m of result?.problems || []) problems.push({stage, message: String(m?.message || m).slice(0, 200)});
+        for (const m of result?.notes || []) notes.push({stage, message: String(m?.message || m).slice(0, 200)});
+        // A shipping handler may offer delivery services to choose between: [{id, label, amount}].
+        if (stage === 'shipping' && Array.isArray(result?.choices)) {
+            shippingChoices = result.choices.slice(0, 10)
+                .filter(c => c && c.id && Number.isFinite(Number(c.amount)))
+                .map(c => ({id: String(c.id).slice(0, 40), label: String(c.label || c.id).slice(0, 80), amount: Math.round(Number(c.amount))}));
+        }
+    }
+
+    const total = Math.max(0, runningTotal);
+    const tax = adjustments.filter(a => a.stage === 'tax').reduce((s, a) => s + a.amount, 0);
+    return {
+        currency,
+        lines: out,
+        problems,
+        notes: notes.filter(n => !n.internal),
+        internalNotes: notes.filter(n => n.internal),
+        subtotal,
+        adjustments,
+        discount: adjustments.filter(a => a.stage === 'discount').reduce((s, a) => s + a.amount, 0),
+        shipping: adjustments.filter(a => a.stage === 'shipping').reduce((s, a) => s + a.amount, 0),
+        tax,
+        taxIncluded: adjustments.some(a => a.stage === 'tax' && a.included),
+        total,
+        requiresShipping,
+        shippingChoices,
+        shippingChoice: adjustments.find(a => a.stage === 'shipping')?.ref || '',
+        weight,
+        itemCount: out.reduce((s, l) => s + l.qty, 0)
+    };
+}