@stacksjs/defaults 0.75.37 → 0.75.40

package/app/Actions/Dashboard/Marketing/campaign-records.ts

@@ -44,7 +44,9 @@ export interface CampaignRecord {
   openRate: number
   clickRate: number
   conversionRate: number
+  /** Integer minor units of `currency` (1999 is $19.99). */
   budget: number
+  /** Integer minor units of `currency`. */
   spent: number
   currency: string
   startDate: string
@@ -224,8 +226,11 @@ export function campaignWriteData(input: Record<string, unknown>, defaultCurrenc
   end_date: string | null
 } {
   const emailListId = Number(input.emailListId ?? input.email_list_id)
+  // Integer minor units of the campaign's currency: the dialog converts what
+  // was typed through @stacksjs/commerce/money before sending it, and
+  // validateCampaignWriteData refuses anything that is not a whole amount.
   const budget = text(input.budget).trim()
-  const spent = Number(input.spent)
+  const spent = text(input.spent).trim()
   return {
     name: text(input.name).trim(),
     description: text(input.description).trim() || null,
@@ -238,8 +243,8 @@ export function campaignWriteData(input: Record<string, unknown>, defaultCurrenc
     from_address: text(input.fromAddress ?? input.from_address).trim() || null,
     email_list_id: Number.isInteger(emailListId) && emailListId > 0 ? emailListId : null,
     scheduled_at: text(input.scheduledAt ?? input.scheduled_at).trim() || null,
-    budget: budget ? Math.max(0, Number(budget) || 0) : null,
-    spent: Number.isFinite(spent) ? Math.max(0, spent) : 0,
+    budget: budget ? Number(budget) : null,
+    spent: spent ? Number(spent) : 0,
     currency: text(input.currency).trim().toUpperCase() || defaultCurrency,
     start_date: text(input.startDate ?? input.start_date).trim() || null,
     end_date: text(input.endDate ?? input.end_date).trim() || null,
@@ -267,6 +272,10 @@ export function validateCampaignWriteData(
     if (scheduledAt <= now.getTime())
       return 'Campaign schedule time must be in the future.'
   }
+  if (data.budget !== null && !isMinorAmount(data.budget))
+    return 'Campaign budgets must be a whole number of minor units, for example 1999 for 19.99.'
+  if (!isMinorAmount(data.spent))
+    return 'Campaign spend must be a whole number of minor units, for example 1999 for 19.99.'
   if (data.start_date && data.end_date) {
     const startsAt = new Date(data.start_date.replace(' ', 'T')).getTime()
     const endsAt = new Date(data.end_date.replace(' ', 'T')).getTime()
@@ -275,3 +284,8 @@ export function validateCampaignWriteData(
   }
   return ''
 }
+
+/** A non-negative whole number of minor units, which is all a money column holds. */
+function isMinorAmount(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0
+}

package/app/Actions/Storefront/AddToCartAction.ts

@@ -1,8 +1,10 @@
 import { Action } from '@stacksjs/actions'
+import { config } from '@stacksjs/config'
 import { db } from '@stacksjs/database/runtime'
 import { response } from '@stacksjs/router'
 import { randomUUIDv7 } from 'bun'
 import { readCartCookie, writeCartCookie } from '../../Storefront/CartCookie'
+import { storefrontCurrency } from '../../Storefront/StorefrontMoney'
 
 const CART_COOKIE = 'stacks_cart'
 const COOKIE_OPTS = {
@@ -64,7 +66,8 @@ export default new Action({
           total_items: 0,
           subtotal: 0,
           total: 0,
-          currency: 'USD',
+          // The store's currency: unit_price and the totals are minor units of it.
+          currency: storefrontCurrency(config.commerce?.currency),
           session_token: token,
           checkout_step: 'cart',
         })

package/app/Actions/Storefront/GetCartAction.ts

@@ -2,6 +2,7 @@ import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database/runtime'
 import { response } from '@stacksjs/router'
 import { readCartCookie } from '../../Storefront/CartCookie'
+import { storefrontCurrency, storefrontMoney } from '../../Storefront/StorefrontMoney'
 
 const CART_COOKIE = 'stacks_cart'
 
@@ -9,6 +10,10 @@ const CART_COOKIE = 'stacks_cart'
  * Read-only cart endpoint used by the slide-in CartDrawer to refresh
  * its contents after an add/remove. Returns the same shape the drawer
  * renders directly so the client doesn't have to do any reshaping.
+ *
+ * Amounts are integer minor units of `currency` (1999 is $19.99), and each
+ * comes with a `*Label` already formatted through `@stacksjs/commerce/money`,
+ * so the drawer never formats money itself.
  */
 export default new Action({
   name: 'GetCartAction',
@@ -39,20 +44,30 @@ export default new Action({
       .selectAll()
       .execute()
 
-    const items = rawItems.map((row: any) => ({
-      id: row.id,
-      slug: row.product_sku,
-      name: row.product_name,
-      image: row.product_image,
-      qty: Number(row.quantity),
-      price: Number(row.unit_price),
-      lineTotal: Number(row.total_price || 0),
-    }))
+    const currency = storefrontCurrency(cart.currency)
+    const items = rawItems.map((row: any) => {
+      const price = Number(row.unit_price)
+      const lineTotal = Number(row.total_price || 0)
+      return {
+        id: row.id,
+        slug: row.product_sku,
+        name: row.product_name,
+        image: row.product_image,
+        qty: Number(row.quantity),
+        price,
+        priceLabel: storefrontMoney(price, currency),
+        lineTotal,
+        lineTotalLabel: storefrontMoney(lineTotal, currency),
+      }
+    })
+    const subtotal = Number(cart.subtotal || 0)
 
     return response.json({
       items,
       total_items: Number(cart.total_items || 0),
-      subtotal: Number(cart.subtotal || 0),
+      subtotal,
+      subtotalLabel: storefrontMoney(subtotal, currency),
+      currency,
     })
   },
 })

package/app/Actions/Storefront/PlaceOrderAction.ts

@@ -4,6 +4,7 @@ import { db } from '@stacksjs/database/runtime'
 import { response } from '@stacksjs/router'
 import { sendOrderConfirmation } from '../../Mail/OrderConfirmation'
 import { readCartCookie } from '../../Storefront/CartCookie'
+import { storefrontCurrency } from '../../Storefront/StorefrontMoney'
 import { totalsFor } from './_shipping'
 
 const CART_COOKIE = 'stacks_cart'
@@ -73,8 +74,10 @@ export default new Action({
         .executeTakeFirst()
     }
 
+    // Integer minor units of the cart's currency, like every amount here.
+    const currency = storefrontCurrency(cart.currency)
     const itemsSubtotal = items.reduce((s: number, i: any) => s + Number(i.total_price || 0), 0)
-    const { subtotal, shipping, total } = totalsFor(itemsSubtotal)
+    const { subtotal, shipping, total } = totalsFor(itemsSubtotal, currency)
 
     const fullAddress = [
       cart.shipping_address,
@@ -88,6 +91,7 @@ export default new Action({
         status: 'paid',
         order_type: 'shipping',
         total_amount: total,
+        currency,
         delivery_fee: shipping,
         delivery_address: fullAddress,
       })
@@ -169,6 +173,7 @@ export default new Action({
         qty: Number(row.quantity),
         lineTotal: Number(row.total_price || 0),
       })),
+      currency,
       subtotal,
       shipping,
       total,

package/app/Actions/Storefront/_shipping.ts

@@ -1,64 +1,90 @@
+import { currencyExponent, decimalToMinor } from '@stacksjs/commerce/money'
+
 /**
- * Shipping rules used by both the cart view and the place-order action.
+ * Shipping rules used by both the cart and checkout views and the
+ * place-order action.
+ *
+ * Centralized so the price the shopper sees and the total they're charged
+ * can't drift: the views read their totals through
+ * `app/Storefront/StorefrontMoney.ts`, which calls {@link totalsFor} here.
  *
- * Centralized so a copy in cart.stx and another in PlaceOrderAction.ts
- * can't drift — when finance changes "free shipping over $40" to
- * "free over $50" you don't want one of the two surfaces (the price
- * the shopper sees vs. the total they're charged) to lag the other.
+ * Every amount in and out is integer minor units of the cart's currency,
+ * like `cart_items.total_price` and `orders.total_amount` (1999 is $19.99).
+ * The thresholds were plain numbers compared against those cents, so the
+ * default "free over 40" meant free over 40 cents and the flat rate was
+ * five cents.
  *
- * Override per-app by setting `STOREFRONT_FREE_SHIPPING_THRESHOLD` and
- * `STOREFRONT_FLAT_SHIPPING` in the environment, or by editing this
- * file in the application's own `app/Actions/Storefront/_shipping.ts`
- * if the rule needs more logic than two numbers (per-region, weight-
- * based, etc.).
+ * Override per-app with `STOREFRONT_FREE_SHIPPING_THRESHOLD` and
+ * `STOREFRONT_FLAT_SHIPPING`, written as major-unit decimals the way a
+ * person says them (`40`, `4.99`) and converted to the currency's minor
+ * unit here, or by editing this file in the application's own
+ * `app/Actions/Storefront/_shipping.ts` if the rule needs more logic than
+ * two numbers (per-region, weight-based, etc.).
  */
 
-const DEFAULT_FREE_SHIPPING_THRESHOLD = 40
-const DEFAULT_FLAT_SHIPPING = 5
+const DEFAULT_FREE_SHIPPING_THRESHOLD = '40'
+const DEFAULT_FLAT_SHIPPING = '5'
 
-export const FREE_SHIPPING_THRESHOLD = numFromEnv(
-  'STOREFRONT_FREE_SHIPPING_THRESHOLD',
-  DEFAULT_FREE_SHIPPING_THRESHOLD,
-)
+/** Subtotal, in minor units of `currency`, at or above which shipping is free. */
+export function freeShippingThreshold(currency: string): number {
+  return minorFromEnv('STOREFRONT_FREE_SHIPPING_THRESHOLD', DEFAULT_FREE_SHIPPING_THRESHOLD, currency)
+}
 
-export const FLAT_SHIPPING = numFromEnv(
-  'STOREFRONT_FLAT_SHIPPING',
-  DEFAULT_FLAT_SHIPPING,
-)
+/** The flat shipping fee, in minor units of `currency`. */
+export function flatShipping(currency: string): number {
+  return minorFromEnv('STOREFRONT_FLAT_SHIPPING', DEFAULT_FLAT_SHIPPING, currency)
+}
 
 /**
- * Compute the shipping fee for a given subtotal. Empty cart → 0,
- * otherwise free at/above the threshold, otherwise the flat rate.
+ * The shipping fee for a subtotal, both in minor units of `currency`.
+ * Empty cart → 0, otherwise free at/above the threshold, otherwise the
+ * flat rate.
  */
-export function shippingFor(subtotal: number): number {
+export function shippingFor(subtotal: number, currency: string): number {
   if (!Number.isFinite(subtotal) || subtotal <= 0)
     return 0
-  if (subtotal >= FREE_SHIPPING_THRESHOLD)
+  if (subtotal >= freeShippingThreshold(currency))
     return 0
-  return FLAT_SHIPPING
+  return flatShipping(currency)
 }
 
 /**
- * Return `{ subtotal, shipping, total }` for a given subtotal — the
- * shape both the cart view and the place-order action want, with the
- * shipping rule applied consistently.
+ * `{ subtotal, shipping, total, remainingForFree }` for a subtotal, all in
+ * minor units of `currency`: the shape both the views and the place-order
+ * action want, with the shipping rule applied consistently.
  */
-export function totalsFor(subtotal: number): {
+export function totalsFor(subtotal: number, currency: string): {
   subtotal: number
   shipping: number
   total: number
+  remainingForFree: number
 } {
-  const sub = Number.isFinite(subtotal) ? subtotal : 0
-  const shipping = shippingFor(sub)
-  return { subtotal: sub, shipping, total: sub + shipping }
+  const sub = Number.isFinite(subtotal) ? Math.round(subtotal) : 0
+  const shipping = shippingFor(sub, currency)
+  return {
+    subtotal: sub,
+    shipping,
+    total: sub + shipping,
+    remainingForFree: shipping > 0 ? Math.max(0, freeShippingThreshold(currency) - sub) : 0,
+  }
 }
 
-function numFromEnv(name: string, fallback: number): number {
+function minorFromEnv(name: string, fallback: string, currency: string): number {
+  const exponent = currencyExponent(currency)
   const raw = (typeof process !== 'undefined' && process.env)
     ? process.env[name]
     : undefined
-  if (raw === undefined || raw === '')
-    return fallback
-  const parsed = Number(raw)
-  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback
+
+  if (raw !== undefined && raw.trim() !== '') {
+    try {
+      const parsed = decimalToMinor(raw, exponent)
+      if (parsed !== null)
+        return parsed
+    }
+    catch {
+      // An unreadable value falls back to the default, as it always has.
+    }
+  }
+
+  return decimalToMinor(fallback, exponent) ?? 0
 }

package/app/Broadcasts/OrderShipped.ts

@@ -43,7 +43,7 @@ const orderData = {
     { id: 'prod_1', name: 'Widget', quantity: 2 },
     { id: 'prod_2', name: 'Gadget', quantity: 1 },
   ],
-  totalAmount: 99.99,
+  totalAmount: 9999, // integer minor units: $99.99
   shippingAddress: {
     street: '123 Main St',
     city: 'Anytown',

package/app/Mail/OrderConfirmation.ts

@@ -1,9 +1,11 @@
+import { formatCurrency } from '@stacksjs/commerce/money'
 import { config } from '@stacksjs/config'
 import { escapeHtml, mail, safe, template } from '@stacksjs/email'
 
 export interface OrderConfirmationItem {
   name: string
   qty: number
+  /** Integer minor units of the order's currency. */
   lineTotal: number
 }
 
@@ -12,6 +14,8 @@ export interface OrderConfirmationOptions {
   orderId: number | string
   customerName?: string
   items: OrderConfirmationItem[]
+  /** The amounts below are integer minor units of this currency (1999 is $19.99). */
+  currency?: string
   subtotal: number
   shipping: number
   total: number
@@ -33,6 +37,8 @@ export async function sendOrderConfirmation(options: OrderConfirmationOptions):
   const appName = config.app.name || 'PetStore'
   const fromAddress = config.email.from?.address || 'hello@stacksjs.com'
 
+  const currency = options.currency || 'USD'
+
   const { html, text } = await template('order-confirmation', {
     variables: {
       orderId: options.orderId,
@@ -41,10 +47,15 @@ export async function sendOrderConfirmation(options: OrderConfirmationOptions):
       // A template variable is a scalar - an array would be interpolated as
       // "[object Object],[object Object]". The rows are rendered here and
       // marked safe, with every value the customer supplied escaped first.
-      itemRows: safe(renderItemRows(options.items)),
+      itemRows: safe(renderItemRows(options.items, currency)),
       subtotal: options.subtotal,
       shipping: options.shipping,
       total: options.total,
+      // Formatted here, through @stacksjs/commerce/money, so the template
+      // never has to know the amounts are minor units or which currency.
+      subtotalLabel: formatCurrency(options.subtotal, currency),
+      shippingLabel: formatCurrency(options.shipping, currency),
+      totalLabel: formatCurrency(options.total, currency),
       shippingAddress: options.shippingAddress || '',
       appName,
     },
@@ -60,15 +71,11 @@ export async function sendOrderConfirmation(options: OrderConfirmationOptions):
   })
 }
 
-function formatMoney(amount: number): string {
-  return (amount / 100).toFixed(2)
-}
-
-function renderItemRows(items: OrderConfirmationItem[]): string {
+function renderItemRows(items: OrderConfirmationItem[], currency: string): string {
   return items
     .map(item => `<tr>
       <td style="padding: 12px 0; color: #d4d4d4; font-size: 15px;">${escapeHtml(item.name)} &times; ${Number(item.qty) || 0}</td>
-      <td style="padding: 12px 0; color: #ececec; font-size: 15px; text-align: right;">${formatMoney(Number(item.lineTotal) || 0)}</td>
+      <td style="padding: 12px 0; color: #ececec; font-size: 15px; text-align: right;">${escapeHtml(formatCurrency(Number(item.lineTotal) || 0, currency))}</td>
     </tr>`)
     .join('\n')
 }

package/app/Models/Campaign.ts

@@ -267,13 +267,17 @@ export default defineModel({
       factory: faker => faker.number.float({ min: 0.5, max: 8, fractionDigits: 1 }),
     },
 
+    // Integer minor units of `currency`, like every money column (1999 is
+    // $19.99). The columns are INTEGER; a decimal here was stored as a REAL by
+    // SQLite and truncated by MySQL and Postgres.
     budget: {
       required: false,
       fillable: true,
       validation: {
-        rule: schema.number().min(0),
+        rule: schema.number().integer().min(0),
       },
-      factory: faker => faker.number.float({ min: 100, max: 10000, fractionDigits: 2 }),
+      // $100 to $10,000.
+      factory: faker => faker.number.int({ min: 10000, max: 1000000 }),
     },
 
     spent: {
@@ -281,9 +285,10 @@ export default defineModel({
       fillable: true,
       default: 0,
       validation: {
-        rule: schema.number().min(0),
+        rule: schema.number().integer().min(0),
       },
-      factory: faker => faker.number.float({ min: 0, max: 5000, fractionDigits: 2 }),
+      // Within the budget drawn above, so a seeded campaign is never over it.
+      factory: (faker, { budget }) => faker.number.int({ min: 0, max: Number(budget) || 0 }),
     },
 
     currency: {

package/app/Models/commerce/Cart.ts

@@ -65,7 +65,8 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 1000 }),
+      // Integer minor units, like every commerce amount: 1999 is $19.99.
+      factory: faker => faker.number.int({ min: 1000, max: 20000 }),
     },
 
     taxAmount: {
@@ -75,7 +76,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 200 }),
+      factory: faker => faker.number.int({ min: 0, max: 1500 }),
     },
 
     discountAmount: {
@@ -85,7 +86,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 100 }),
+      factory: faker => faker.number.int({ min: 0, max: 1000 }),
     },
 
     total: {
@@ -95,7 +96,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 1200 }),
+      factory: faker => faker.number.int({ min: 1000, max: 21500 }),
     },
 
     expiresAt: {

package/app/Models/commerce/CartItem.ts

@@ -52,7 +52,8 @@ export default defineModel({
       validation: {
         rule: schema.number().required().min(0),
       },
-      factory: faker => faker.number.int({ min: 1, max: 1000 }),
+      // Integer minor units, in the same range as Product.price.
+      factory: faker => faker.number.int({ min: 100, max: 10000 }),
     },
 
     totalPrice: {
@@ -61,7 +62,7 @@ export default defineModel({
       validation: {
         rule: schema.number().required().min(0),
       },
-      factory: faker => faker.number.int({ min: 1, max: 1000 }),
+      factory: faker => faker.number.int({ min: 100, max: 50000 }),
     },
 
     taxRate: {
@@ -79,7 +80,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 50 }),
+      factory: faker => faker.number.int({ min: 0, max: 1000 }),
     },
 
     discountPercentage: {
@@ -97,7 +98,8 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 25 }),
+      // At most $1.00, so it never exceeds the smallest unit price above.
+      factory: faker => faker.number.int({ min: 0, max: 100 }),
     },
 
     productName: {

package/app/Models/commerce/Coupon.ts

@@ -106,7 +106,11 @@ export default defineModel({
           min: 'Discount value must be greater than 0.01',
         },
       },
-      factory: faker => faker.number.int({ min: 5, max: 50 }),
+      // A percentage stays a plain number; a fixed amount is integer minor units
+      // ($5 to $50). discountType is declared above, so the seeder has drawn it.
+      factory: (faker, { discountType }) => discountType === 'fixed_amount'
+        ? faker.helpers.arrayElement([500, 1000, 1500, 2000, 2500, 5000])
+        : faker.number.int({ min: 5, max: 50 }),
     },
 
     minOrderAmount: {
@@ -118,7 +122,8 @@ export default defineModel({
           min: 'Min order amount must be greater than 0',
         },
       },
-      factory: faker => faker.number.int({ min: 0, max: 50 }),
+      // Integer minor units: no minimum, or $25 to $100.
+      factory: faker => faker.helpers.arrayElement([0, 2500, 5000, 7500, 10000]),
     },
 
     maxDiscountAmount: {
@@ -130,7 +135,8 @@ export default defineModel({
           min: 'Max discount amount must be greater than 0',
         },
       },
-      factory: faker => faker.number.int({ min: 5, max: 100 }),
+      // Integer minor units: $10 to $100.
+      factory: faker => faker.number.int({ min: 1000, max: 10000 }),
     },
 
     freeProductId: {

package/app/Models/commerce/Customer.ts

@@ -82,7 +82,8 @@ export default defineModel({
           min: 'Total spent cannot be negative',
         },
       },
-      factory: faker => faker.number.int({ min: 0, max: 2000 }),
+      // Integer minor units: $0 to $5,000.
+      factory: faker => faker.number.int({ min: 0, max: 500000 }),
     },
 
     lastOrder: {

package/app/Models/commerce/GiftCard.ts

@@ -57,7 +57,8 @@ export default defineModel({
       validation: {
         rule: schema.number().required().min(1),
       },
-      factory: faker => faker.number.int({ min: 100, max: 2000 }),
+      // Integer minor units, in the denominations cards are actually sold in: $25 to $250.
+      factory: faker => faker.helpers.arrayElement([2500, 5000, 10000, 15000, 20000, 25000]),
     },
 
     currentBalance: {
@@ -66,7 +67,9 @@ export default defineModel({
       validation: {
         rule: schema.number().required().min(0),
       },
-      factory: () => 1,
+      // Drawn below the smallest initial balance above, so a seeded card never
+      // holds more than it was issued with.
+      factory: faker => faker.number.int({ min: 0, max: 2500 }),
     },
 
     currency: {

package/app/Models/commerce/Order.ts

@@ -64,7 +64,8 @@ export default defineModel({
       validation: {
         rule: schema.number().required().min(0),
       },
-      factory: faker => faker.number.int({ min: 100, max: 2000 }),
+      // Integer minor units, like every commerce amount: 1999 is $19.99.
+      factory: faker => faker.number.int({ min: 1000, max: 50000 }),
     },
 
     currency: {
@@ -84,7 +85,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 10, max: 200 }),
+      factory: faker => faker.number.int({ min: 0, max: 4000 }),
     },
 
     discountAmount: {
@@ -94,7 +95,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 150 }),
+      factory: faker => faker.number.int({ min: 0, max: 2000 }),
     },
 
     deliveryFee: {
@@ -104,7 +105,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 100 }),
+      factory: faker => faker.helpers.arrayElement([0, 299, 499, 799]),
     },
 
     tipAmount: {
@@ -114,7 +115,7 @@ export default defineModel({
       validation: {
         rule: schema.number().min(0),
       },
-      factory: faker => faker.number.int({ min: 0, max: 200 }),
+      factory: faker => faker.number.int({ min: 0, max: 1500 }),
     },
 
     orderType: {

package/app/Models/commerce/OrderItem.ts

@@ -36,7 +36,8 @@ export default defineModel({
           min: 'Price cannot be negative',
         },
       },
-      factory: faker => faker.number.int({ min: 5, max: 50 }),
+      // Integer minor units, in the same range as Product.price.
+      factory: faker => faker.number.int({ min: 100, max: 10000 }),
     },
 
     special_instructions: {