@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/data/currencies.ts

@@ -0,0 +1,46 @@
+/**
+ * Common currencies (code, name, symbol, standard minor-unit decimals).
+ * A reference /data/currencies dataset (subset of the
+ * most-used currencies; extend freely — this is plain static data).
+ */
+export interface CurrencyInfo {
+  code: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+}
+
+export const CURRENCIES: CurrencyInfo[] = [
+  { code: "USD", name: "US Dollar", symbol: "$", decimals: 2 },
+  { code: "EUR", name: "Euro", symbol: "€", decimals: 2 },
+  { code: "GBP", name: "Pound Sterling", symbol: "£", decimals: 2 },
+  { code: "JPY", name: "Japanese Yen", symbol: "¥", decimals: 0 },
+  { code: "CNY", name: "Chinese Yuan", symbol: "¥", decimals: 2 },
+  { code: "AUD", name: "Australian Dollar", symbol: "A$", decimals: 2 },
+  { code: "CAD", name: "Canadian Dollar", symbol: "C$", decimals: 2 },
+  { code: "CHF", name: "Swiss Franc", symbol: "CHF", decimals: 2 },
+  { code: "HKD", name: "Hong Kong Dollar", symbol: "HK$", decimals: 2 },
+  { code: "SGD", name: "Singapore Dollar", symbol: "S$", decimals: 2 },
+  { code: "SEK", name: "Swedish Krona", symbol: "kr", decimals: 2 },
+  { code: "NOK", name: "Norwegian Krone", symbol: "kr", decimals: 2 },
+  { code: "DKK", name: "Danish Krone", symbol: "kr", decimals: 2 },
+  { code: "NZD", name: "New Zealand Dollar", symbol: "NZ$", decimals: 2 },
+  { code: "ILS", name: "Israeli New Shekel", symbol: "₪", decimals: 2 },
+  { code: "AED", name: "UAE Dirham", symbol: "د.إ", decimals: 2 },
+  { code: "INR", name: "Indian Rupee", symbol: "₹", decimals: 2 },
+  { code: "BRL", name: "Brazilian Real", symbol: "R$", decimals: 2 },
+  { code: "MXN", name: "Mexican Peso", symbol: "MX$", decimals: 2 },
+  { code: "ZAR", name: "South African Rand", symbol: "R", decimals: 2 },
+  { code: "PLN", name: "Polish Złoty", symbol: "zł", decimals: 2 },
+  { code: "CZK", name: "Czech Koruna", symbol: "Kč", decimals: 2 },
+  { code: "HUF", name: "Hungarian Forint", symbol: "Ft", decimals: 0 },
+  { code: "RON", name: "Romanian Leu", symbol: "lei", decimals: 2 },
+  { code: "TRY", name: "Turkish Lira", symbol: "₺", decimals: 2 },
+  { code: "RUB", name: "Russian Ruble", symbol: "₽", decimals: 2 },
+  { code: "KRW", name: "South Korean Won", symbol: "₩", decimals: 0 },
+  { code: "THB", name: "Thai Baht", symbol: "฿", decimals: 2 },
+  { code: "PHP", name: "Philippine Peso", symbol: "₱", decimals: 2 },
+  { code: "MYR", name: "Malaysian Ringgit", symbol: "RM", decimals: 2 },
+  { code: "IDR", name: "Indonesian Rupiah", symbol: "Rp", decimals: 0 },
+  { code: "VND", name: "Vietnamese Dong", symbol: "₫", decimals: 0 },
+];

package/base44/shared/commerce/email-templates.ts

@@ -0,0 +1,240 @@
+/**
+ * HTML rendering for transactional order emails. Simple, inline-styled,
+ * 600px table layout that renders acceptably in every mail client.
+ * Subjects/headings follow standard commerce conventions and can be overridden per type
+ * in the `emails` settings group.
+ */
+import { formatMoney } from "./money.ts";
+
+interface EmailCopy {
+  subject: string;
+  heading: string;
+  intro: string;
+}
+
+/** Default copy per email type; {placeholders} substituted at render time. */
+const DEFAULT_COPY: Record<string, EmailCopy> = {
+  new_order: {
+    subject: "[{store_name}]: New order #{order_number}",
+    heading: "New Order: #{order_number}",
+    intro: "You have received the following order from {customer_name}:",
+  },
+  cancelled_order: {
+    subject: "[{store_name}]: Order #{order_number} has been cancelled",
+    heading: "Order Cancelled: #{order_number}",
+    intro: "The following order has been cancelled. Order details:",
+  },
+  failed_order: {
+    subject: "[{store_name}]: Order #{order_number} has failed",
+    heading: "Order Failed: #{order_number}",
+    intro: "Payment for the following order has failed. Order details:",
+  },
+  on_hold_order: {
+    subject: "Your {store_name} order has been received!",
+    heading: "Thank you for your order",
+    intro: "Your order is on hold until we confirm that payment has been received. Order details below for your reference:",
+  },
+  processing_order: {
+    subject: "Your {store_name} order has been received!",
+    heading: "Thank you for your order",
+    intro: "We have received your order and it is now being processed. Order details below for your reference:",
+  },
+  completed_order: {
+    subject: "Your {store_name} order is now complete",
+    heading: "Thanks for shopping with us",
+    intro: "Your order is now complete. Order details below for your reference:",
+  },
+  refunded_order: {
+    subject: "Your {store_name} order has been refunded",
+    heading: "Order Refunded: #{order_number}",
+    intro: "Your order has been refunded. Details below for your reference:",
+  },
+  partial_refund: {
+    subject: "Your {store_name} order has been partially refunded",
+    heading: "Order Partially Refunded: #{order_number}",
+    intro: "Your order has been partially refunded. Details below for your reference:",
+  },
+  customer_invoice: {
+    subject: "Invoice for order #{order_number} from {store_name}",
+    heading: "Invoice for order #{order_number}",
+    intro: "Details of your order are below:",
+  },
+  customer_note: {
+    subject: "Note added to your {store_name} order #{order_number}",
+    heading: "A note has been added to your order",
+    intro: "The following note has been added to your order:",
+  },
+};
+
+function substitute(text: string, order: any, general: Record<string, any>): string {
+  const customerName = [order.billing?.first_name, order.billing?.last_name].filter(Boolean).join(" ") || "customer";
+  const out = (text || "")
+    .replaceAll("{order_number}", String(order.order_number ?? ""))
+    .replaceAll("{customer_name}", customerName)
+    .replaceAll("{store_name}", String(general.store_name || ""))
+    .replaceAll("{order_total}", formatMoney(order.total ?? 0, general));
+  // An unnamed store must not leave debris behind: "[]: New order", "Your  order",
+  // "Invoice #12 from ". A missing name drops out of the sentence instead.
+  return out
+    .replace(/\[\s*\]\s*:?\s*/g, "")
+    .replace(/\s+from\s*$/i, "")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+}
+
+function esc(s: unknown): string {
+  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+const cell = 'style="padding:8px 12px;border-bottom:1px solid #e5e5e5;font-size:14px;color:#333;"';
+const cellR = 'style="padding:8px 12px;border-bottom:1px solid #e5e5e5;font-size:14px;color:#333;text-align:right;"';
+
+function addressBlock(title: string, a: any, general: Record<string, any>): string {
+  if (!a || (!a.address_1 && !a.first_name && !a.city)) return "";
+  const lines = [
+    [a.first_name, a.last_name].filter(Boolean).join(" "),
+    a.company,
+    a.address_1,
+    a.address_2,
+    [a.city, a.state, a.postcode].filter(Boolean).join(", "),
+    a.country,
+    a.email,
+    a.phone,
+  ].filter(Boolean).map(esc);
+  return `<td style="vertical-align:top;padding:12px;width:50%;">
+    <h3 style="margin:0 0 8px;font-size:15px;color:#333;">${esc(title)}</h3>
+    <p style="margin:0;font-size:13px;color:#555;line-height:1.5;">${lines.join("<br/>")}</p>
+  </td>`;
+}
+
+export interface RenderExtra {
+  note?: string;
+  refund?: { amount: number; reason?: string };
+  paymentInstructions?: { title: string; lines: string[] };
+  additionalContent?: string;
+}
+
+export interface RenderedEmail {
+  subject: string;
+  heading: string;
+  html: string;
+}
+
+/**
+ * Render an order email. `settings` is the groups object (uses `emails` for
+ * overrides and `general` for store name / money format).
+ */
+export function renderOrderEmail(
+  type: string,
+  order: any,
+  settings: Record<string, any>,
+  extra: RenderExtra = {},
+): RenderedEmail {
+  const general = settings.general ?? {};
+  const typeCfg = (settings.emails ?? {})[type] ?? {};
+  const copy = DEFAULT_COPY[type] ?? DEFAULT_COPY.customer_invoice;
+
+  const subject = substitute(typeCfg.subject || copy.subject, order, general);
+  const heading = substitute(typeCfg.heading || copy.heading, order, general);
+  const intro = substitute(copy.intro, order, general);
+  const money = (n: number) => esc(formatMoney(n ?? 0, general));
+
+  const itemRows = (order.line_items || []).map((li: any) => `
+    <tr>
+      <td ${cell}>${esc(li.name)}${li.sku ? ` <span style="color:#999;">(${esc(li.sku)})</span>` : ""}${
+        (li.attributes || []).length
+          ? `<br/><span style="color:#777;font-size:12px;">${li.attributes.map((a: any) => `${esc(a.name)}: ${esc(a.option)}`).join(", ")}</span>`
+          : ""
+      }</td>
+      <td ${cellR}>${li.quantity}</td>
+      <td ${cellR}>${money(li.total)}</td>
+    </tr>`).join("");
+
+  const totalsRows: Array<[string, string]> = [["Subtotal", money(order.subtotal ?? 0)]];
+  if (order.discount_total) totalsRows.push(["Discount", `-${money(order.discount_total)}`]);
+  for (const fl of order.fee_lines || []) totalsRows.push([esc(fl.name || "Fee"), money(fl.total)]);
+  if ((order.shipping_lines || []).length) {
+    const title = order.shipping_lines.map((s: any) => esc(s.method_title)).join(", ");
+    totalsRows.push([`Shipping (${title})`, money(order.shipping_total ?? 0)]);
+  }
+  for (const tl of order.tax_lines || []) {
+    totalsRows.push([esc(tl.label || "Tax"), money(round2Safe(tl.tax_total + tl.shipping_tax_total))]);
+  }
+  totalsRows.push(["<strong>Total</strong>", `<strong>${money(order.total ?? 0)}</strong>`]);
+  if (order.total_refunded) totalsRows.push(["Refunded", `-${money(order.total_refunded)}`]);
+
+  const totalsHtml = totalsRows.map(([label, value]) => `
+    <tr>
+      <td colspan="2" ${cellR}>${label}</td>
+      <td ${cellR}>${value}</td>
+    </tr>`).join("");
+
+  const noteHtml = extra.note
+    ? `<div style="margin:16px 0;padding:12px;background:#fdf6e3;border:1px solid #f0e0b0;border-radius:4px;font-size:13px;color:#555;">${esc(extra.note)}</div>`
+    : "";
+
+  const refundHtml = extra.refund
+    ? `<p style="font-size:13px;color:#555;">Refund amount: <strong>${money(extra.refund.amount)}</strong>${extra.refund.reason ? ` — ${esc(extra.refund.reason)}` : ""}</p>`
+    : "";
+
+  const payHtml = extra.paymentInstructions
+    ? `<div style="margin:16px 0;padding:12px;background:#f5f8fb;border:1px solid #d4e0ec;border-radius:4px;">
+        <h3 style="margin:0 0 8px;font-size:14px;color:#333;">${esc(extra.paymentInstructions.title)}</h3>
+        <p style="margin:0;font-size:13px;color:#555;line-height:1.6;">${extra.paymentInstructions.lines.map(esc).join("<br/>")}</p>
+      </div>`
+    : "";
+
+  const customerNoteHtml = order.customer_note
+    ? `<p style="font-size:13px;color:#555;"><strong>Customer note:</strong> ${esc(order.customer_note)}</p>`
+    : "";
+
+  const additional = typeCfg.additional_content || extra.additionalContent
+    ? `<p style="font-size:13px;color:#555;">${esc(typeCfg.additional_content || extra.additionalContent)}</p>`
+    : "";
+
+  const html = `
+<div style="background:#f7f7f7;padding:24px 0;font-family:Helvetica,Arial,sans-serif;">
+  <table role="presentation" width="600" align="center" cellpadding="0" cellspacing="0" style="background:#ffffff;border-radius:6px;overflow:hidden;margin:0 auto;">
+    <tr>
+      <td style="background:#557da1;padding:24px;">
+        <h1 style="margin:0;color:#ffffff;font-size:22px;font-weight:600;">${esc(general.store_name || "Your order")}</h1>
+      </td>
+    </tr>
+    <tr>
+      <td style="padding:24px;">
+        <h2 style="margin:0 0 12px;font-size:18px;color:#557da1;">${esc(heading)}</h2>
+        <p style="font-size:14px;color:#555;line-height:1.5;">${esc(intro)}</p>
+        ${noteHtml}${refundHtml}
+        <h3 style="margin:20px 0 8px;font-size:15px;color:#333;">Order #${esc(order.order_number)} (${esc((order.created_date || "").slice(0, 10))})</h3>
+        <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="border:1px solid #e5e5e5;border-collapse:collapse;">
+          <tr>
+            <th ${cell.replace("color:#333", "color:#333;text-align:left")}>Product</th>
+            <th ${cellR}>Qty</th>
+            <th ${cellR}>Total</th>
+          </tr>
+          ${itemRows}
+          ${totalsHtml}
+        </table>
+        ${payHtml}${customerNoteHtml}${additional}
+        <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="margin-top:20px;">
+          <tr>
+            ${addressBlock("Billing address", order.billing, general)}
+            ${addressBlock("Shipping address", order.shipping, general)}
+          </tr>
+        </table>
+      </td>
+    </tr>
+    <tr>
+      <td style="padding:16px 24px;background:#fafafa;border-top:1px solid #eee;">
+        <p style="margin:0;font-size:12px;color:#999;">${general.store_name ? `${esc(general.store_name)} — ` : ""}powered by the Base44 commerce template</p>
+      </td>
+    </tr>
+  </table>
+</div>`;
+
+  return { subject, heading, html };
+}
+
+function round2Safe(n: number): number {
+  return Math.round(((Number(n) || 0) + Number.EPSILON) * 100) / 100;
+}

package/base44/shared/commerce/emails.ts

@@ -0,0 +1,225 @@
+/**
+ * Transactional email dispatch (the standard commerce email set, minus reset_password /
+ * new_account which Base44 auth handles). Reads the `emails` settings group,
+ * renders via email-templates.ts, sends with Core.SendEmail, logs to EmailLog,
+ * and records lifecycle sends on order.emails_sent to prevent duplicates.
+ *
+ * Persistence note: this module OWNS order.emails_sent (it updates that field
+ * on the Order record itself); orders.ts transitionOrder never writes it.
+ */
+import { getSettings } from "./settings.ts";
+import { renderOrderEmail, RenderExtra } from "./email-templates.ts";
+
+/** Types sent to store admins. */
+const ADMIN_TYPES = new Set(["new_order", "cancelled_order", "failed_order"]);
+/** Types sent to the customer. */
+const CUSTOMER_TYPES = new Set([
+  "failed_order", "on_hold_order", "processing_order", "completed_order",
+  "refunded_order", "partial_refund", "customer_invoice", "customer_note",
+]);
+/** Lifecycle types that only ever fire once per order (deduped via emails_sent). */
+const ONCE_TYPES = new Set([
+  "new_order", "cancelled_order", "failed_order", "on_hold_order",
+  "processing_order", "completed_order", "refunded_order",
+]);
+
+interface Recipient {
+  to: string;
+  target: "admin" | "customer";
+}
+
+/** Settings hold either an array (admin_recipients) or a comma-separated string. */
+function toAddresses(value: any): string[] {
+  const parts = Array.isArray(value) ? value : String(value ?? "").split(/[,;]/);
+  return parts.map((p) => String(p ?? "").trim()).filter(Boolean);
+}
+
+/**
+ * Addresses of the app's admin users — the fallback when nothing is configured,
+ * so a store that never filled in Settings → Emails is not silent. Resolved at
+ * send time (never seeded) so promoting an admin is enough to start receiving
+ * order mail. Memoized per isolate: a checkout only pays for it once.
+ */
+let adminUsersCache: Promise<string[]> | null = null;
+export function adminUserEmails(sr: any): Promise<string[]> {
+  adminUsersCache ??= (async () => {
+    try {
+      const users = await sr.entities.User.filter({ role: "admin" }, undefined, 50, 0, ["email"]);
+      return toAddresses((users ?? []).map((u: any) => u?.email));
+    } catch (e) {
+      console.error("adminUserEmails failed:", e);
+      return [];
+    }
+  })();
+  return adminUsersCache;
+}
+
+function dedupeByAddress(list: Recipient[]): Recipient[] {
+  const seen = new Set<string>();
+  return list.filter(({ to }) => {
+    const key = to.toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export interface SendOrderEmailOpts {
+  settings?: Record<string, any>; // pre-fetched groups (emails + general)
+  extra?: RenderExtra;
+  force?: boolean;                // bypass the emails_sent dedupe (manual re-send)
+}
+
+/**
+ * Send one of the transactional order emails. Returns
+ * {sent, reason?} — never throws (email failures must not break checkout).
+ */
+export async function sendOrderEmail(
+  sr: any,
+  type: string,
+  order: any,
+  opts: SendOrderEmailOpts = {},
+): Promise<{ sent: boolean; reason?: string }> {
+  try {
+    const settings = opts.settings ?? (await getSettings(sr, "emails", "general"));
+    const cfg = settings.emails ?? {};
+    const typeCfg = cfg[type] ?? {};
+
+    if (typeCfg.enabled === false) return { sent: false, reason: "disabled" };
+    if (!opts.force && ONCE_TYPES.has(type) && (order.emails_sent || []).includes(type)) {
+      return { sent: false, reason: "already_sent" };
+    }
+
+    const targets: Recipient[] = [];
+    if (ADMIN_TYPES.has(type)) {
+      // Only an override holding a real address wins — a blank one must not
+      // shadow admin_recipients and send to "".
+      const perType = toAddresses(typeCfg.recipient);
+      const configured = perType.length ? perType : toAddresses(cfg.admin_recipients);
+      const admins = configured.length ? configured : await adminUserEmails(sr);
+      for (const to of admins) targets.push({ to, target: "admin" });
+    }
+    if (CUSTOMER_TYPES.has(type)) {
+      for (const to of toAddresses(order?.billing?.email)) targets.push({ to, target: "customer" });
+    }
+
+    const recipients = dedupeByAddress(targets);
+    if (!recipients.length) {
+      const why: string[] = [];
+      if (ADMIN_TYPES.has(type)) why.push("no admin recipients configured and no app user has the admin role");
+      if (CUSTOMER_TYPES.has(type)) why.push("the order has no billing email");
+      await logEmail(sr, {
+        type,
+        recipient: "",
+        target: ADMIN_TYPES.has(type) ? "admin" : "customer",
+        order,
+        success: false,
+        error: `no recipient — ${why.join("; ")}`,
+      });
+      return { sent: false, reason: "no_recipient" };
+    }
+
+    const { subject, html } = renderOrderEmail(type, order, settings, opts.extra ?? {});
+    const fromName = cfg.from_name || settings.general?.store_name || undefined;
+
+    let anySent = false;
+    for (const { to, target } of recipients) {
+      try {
+        await sr.integrations.Core.SendEmail({ to, subject, body: html, from_name: fromName });
+        await logEmail(sr, { type, recipient: to, target, subject, order, success: true });
+        anySent = true;
+      } catch (e) {
+        await logEmail(sr, {
+          type, recipient: to, target, subject, order,
+          success: false, error: String((e as Error)?.message ?? e),
+        });
+      }
+    }
+
+    if (anySent && ONCE_TYPES.has(type)) {
+      const sent = [...(order.emails_sent || []), type];
+      order.emails_sent = sent;
+      await sr.entities["commerce.Order"].update(order.id, { emails_sent: sent });
+    }
+    return { sent: anySent };
+  } catch (e) {
+    console.error(`sendOrderEmail(${type}) failed:`, e);
+    return { sent: false, reason: "error" };
+  }
+}
+
+/**
+ * Low/out-of-stock notifications to the inventory recipient
+ * (kind: "low_stock" | "out_of_stock" | "backorder").
+ */
+export async function sendStockEmail(sr: any, kind: string, product: any, opts: { settings?: Record<string, any> } = {}): Promise<void> {
+  try {
+    const settings = opts.settings ?? (await getSettings(sr, "inventory", "emails", "general"));
+    const inv = settings.inventory ?? {};
+    if (kind === "low_stock" && inv.notify_low_stock === false) return;
+    if (kind === "out_of_stock" && inv.notify_out_of_stock === false) return;
+    const to = toAddresses(inv.notification_recipient)[0]
+      ?? toAddresses(settings.emails?.admin_recipients)[0]
+      ?? (await adminUserEmails(sr))[0];
+    if (!to) {
+      await logEmail(sr, {
+        type: kind,
+        recipient: "",
+        target: "admin",
+        success: false,
+        error: "no recipient — no inventory recipient, no admin recipients, and no app user has the admin role",
+      });
+      return;
+    }
+
+    const storeName = settings.general?.store_name || "";
+    const labels: Record<string, string> = {
+      low_stock: "is low in stock",
+      out_of_stock: "is out of stock",
+      backorder: "is on backorder",
+    };
+    const subject = `${storeName ? `[${storeName}] ` : ""}Product ${labels[kind] ?? kind}: ${product.name}`;
+    const body = `<p><strong>${product.name}</strong> (${product.sku || "no SKU"}) ${labels[kind] ?? kind}.</p>
+<p>Remaining stock: ${product.stock_quantity ?? "n/a"}</p>`;
+    try {
+      await sr.integrations.Core.SendEmail({ to, subject, body, from_name: settings.emails?.from_name });
+      await logEmail(sr, { type: kind, recipient: to, target: "admin", subject, success: true });
+    } catch (e) {
+      await logEmail(sr, {
+        type: kind, recipient: to, target: "admin", subject,
+        success: false, error: String((e as Error)?.message ?? e),
+      });
+      throw e;
+    }
+  } catch (e) {
+    console.error(`sendStockEmail(${kind}) failed:`, e);
+  }
+}
+
+/**
+ * Write one EmailLog row. `order_id` is the id users are shown (order_number);
+ * the record id goes to `order_record_id`.
+ */
+async function logEmail(sr: any, entry: {
+  type: string;
+  recipient: string;
+  target: "admin" | "customer";
+  subject?: string;
+  order?: any;
+  success: boolean;
+  error?: string;
+}): Promise<void> {
+  try {
+    const { order } = entry;
+    await sr.entities["commerce.EmailLog"].create({
+      email_type: entry.type,
+      recipient: entry.recipient,
+      target: entry.target,
+      subject: entry.subject ?? "",
+      order_id: String(order?.order_number ?? order?.id ?? ""),
+      order_record_id: order?.id ?? "",
+      success: entry.success,
+      error: entry.error ?? "",
+    });
+  } catch { /* logging must never break the caller */ }
+}

package/base44/shared/commerce/money.ts

@@ -0,0 +1,66 @@
+/**
+ * Monetary helpers. Every money value in this template flows through round2()
+ * so stored totals are always 2-dp numbers (Base44-idiomatic numeric totals).
+ */
+import { CURRENCIES } from "./data/currencies.ts";
+
+/** Round to 2 decimal places (half-up, EPSILON-guarded against FP drift). */
+export function round2(n: number): number {
+  const v = Number(n) || 0;
+  return Math.round((v + (v >= 0 ? Number.EPSILON : -Number.EPSILON)) * 100) / 100;
+}
+
+/**
+ * Distribute `total` across `weights` proportionally and cents-exact using the
+ * largest-remainder method, so the shares always sum to exactly round2(total).
+ * Used when spreading a fixed_cart coupon across eligible lines.
+ */
+export function distributeProportionally(total: number, weights: number[]): number[] {
+  const sum = weights.reduce((a, b) => a + (Number(b) || 0), 0);
+  const totalCents = Math.round(round2(total) * 100);
+  if (sum <= 0 || totalCents <= 0 || !weights.length) return weights.map(() => 0);
+  const raw = weights.map((w) => ((Number(w) || 0) / sum) * totalCents);
+  const cents = raw.map((r) => Math.floor(r));
+  let remainder = totalCents - cents.reduce((a, b) => a + b, 0);
+  // hand leftover cents to the largest fractional parts first
+  const order = raw
+    .map((r, i) => ({ i, frac: r - Math.floor(r) }))
+    .sort((a, b) => b.frac - a.frac);
+  for (const { i } of order) {
+    if (remainder <= 0) break;
+    cents[i] += 1;
+    remainder -= 1;
+  }
+  return cents.map((c) => c / 100);
+}
+
+/**
+ * Format an amount per the store's `general` settings values:
+ * {currency, currency_position, thousand_sep, decimal_sep, num_decimals}.
+ * Positions: left | right | left_space | right_space.
+ */
+export function formatMoney(amount: number, general: Record<string, unknown> = {}): string {
+  const code = String(general.currency ?? "USD");
+  const currency = CURRENCIES.find((c) => c.code === code);
+  const symbol = currency?.symbol ?? code;
+  const decimals = Number(general.num_decimals ?? currency?.decimals ?? 2);
+  const thousandSep = String(general.thousand_sep ?? ",");
+  const decimalSep = String(general.decimal_sep ?? ".");
+  const position = String(general.currency_position ?? "left");
+
+  const negative = amount < 0;
+  const fixed = Math.abs(round2(amount)).toFixed(decimals);
+  const [intPart, fracPart] = fixed.split(".");
+  const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousandSep);
+  const num = fracPart ? `${grouped}${decimalSep}${fracPart}` : grouped;
+
+  let out: string;
+  switch (position) {
+    case "right":       out = `${num}${symbol}`; break;
+    case "left_space":  out = `${symbol} ${num}`; break;
+    case "right_space": out = `${num} ${symbol}`; break;
+    case "left":
+    default:            out = `${symbol}${num}`;
+  }
+  return negative ? `-${out}` : out;
+}