@stacksjs/defaults 0.75.38 → 0.75.40

package/ai/skills/stacks-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-ai
-description: Use when integrating AI capabilities into a Stacks application - using Anthropic/OpenAI/Ollama/AWS Bedrock drivers, image generation (DALL-E), vision analysis, RAG/vector search, embeddings, MCP (Model Context Protocol) clients, text summarization, sentiment analysis, content classification, personalization, or the buddy AI assistant. Covers @stacksjs/ai and config/ai.ts.
+description: Use when integrating AI capabilities into a Stacks application - using Anthropic/OpenAI/Ollama/AWS Bedrock drivers, image generation (DALL-E), vision analysis, RAG/vector search, embeddings, text-to-speech and speech-to-text, MCP (Model Context Protocol) clients, text summarization, sentiment analysis, content classification, personalization, or the buddy AI assistant. Covers @stacksjs/ai and config/ai.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -23,6 +23,7 @@ ai/src/
 │   ├── ollama.ts         # Local LLM driver
 │   └── bedrock.ts        # AWS Bedrock utilities
 ├── image.ts              # Image generation & vision
+├── speech.ts             # Provider-neutral text-to-speech & speech-to-text
 ├── search.ts             # RAG, embeddings, vector index
 ├── mcp.ts                # Model Context Protocol client
 ├── personalization.ts    # Sentiment, classification, recommendations
@@ -77,6 +78,28 @@ if (configuration.configured) {
 }
 ```
 
+## Speech (Text-to-Speech, Speech-to-Text)
+
+Provider-neutral, in `ai/src/speech.ts`. The driver is the `driver` option, else
+`default` from `config/ai.ts`. Only `openai` implements speech (`SPEECH_DRIVERS`);
+any other driver throws naming itself and the supported ones - do not catch that
+and fall back to a different provider.
+
+```typescript
+import { speechToText, storeSpeech, textToSpeech } from '@stacksjs/ai'
+
+const speech = await textToSpeech('Hello', { voice: 'nova', format: 'mp3', speed: 1.1 })
+// { audio: Uint8Array, mimeType: 'audio/mpeg', format, driver, model, voice }
+await storeSpeech(speech, 'audio/hello.mp3', { disk: 'public' }) // disk name or adapter
+const { text } = await speechToText(Bun.file('memo.m4a'), { language: 'en' })
+```
+
+Defaults: model `gpt-4o-mini-tts`, voice `alloy`, format `mp3`, speed omitted
+(provider default 1.0); transcription model `whisper-1`. `instructions` is
+rejected for `tts-1` / `tts-1-hd`. OpenAI caps input at 4096 characters per
+request. HTTP failures throw with the status and a body snippet. In tests, mock
+`globalThis.fetch` and pass `config` explicitly (see `ai/tests/speech.test.ts`).
+
 ## Ollama Driver (Local LLMs)
 
 ```typescript

package/ai/skills/stacks-commerce/SKILL.md

@@ -79,7 +79,7 @@ Each sub-module typically provides:
 | Model | Key Fields | Relationships |
 |-------|-----------|---------------|
 | Product | name, price, inventoryCount, allergens(JSON) | belongsTo: Category, Manufacturer; hasMany: Review, ProductUnit, ProductVariant |
-| ProductVariant | SKU, options, pricing | belongsTo: Product |
+| ProductVariant | variant, type, options, status, sku (unique per product), price / compareAtPrice (minor units; null price inherits the product's), inventoryCount (null = untracked) | belongsTo: Product |
 | ProductUnit | unit pricing | belongsTo: Product |
 | Category | name, slug, isActive, displayOrder | hasMany: Product |
 | Cart | status, total, currency(USD), expiresAt | hasMany: CartItem; belongsTo: Customer |

package/ai/skills/stacks-config/SKILL.md

@@ -127,7 +127,7 @@ they name: `defineEvents` and `defineListener` from `@stacksjs/events`,
 ### Other
 | File | Type | Key Settings |
 |------|------|-------------|
-| `buddy-bot.ts` | BuddyBotConfig | repository, dashboard, workflows |
+| `buddy-bot.ts` | BuddyConfig (`@buddysh/buddy`) | repository, dashboard, workflows |
 | `cli.ts` | BinaryConfig | name, command, description |
 | `deps.ts` | PantryConfig | system dependencies (bun, sqlite, redis, etc.) |
 | `errors.ts` | ErrorConfig | comprehensive validation error messages |

package/ai/skills/stacks-database/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Database package: `storage/framework/core/database/src/`
 - Configuration: `config/database.ts`
 - QB config: `config/query-builder.ts`
-- Migrations: `database/migrations/` (229 migration files, `.sql` format)
+- Migrations: `database/migrations/` (231 migration files, `.sql` format)
 - QB state: `.qb/`
 - ORM: `storage/framework/orm/`
 

package/ai/skills/stacks-dependencies/SKILL.md

@@ -95,11 +95,43 @@ bun run upgrade            # Upgrade dependencies
 bun run build:reset        # Full reset: rm deps → reinstall → generate → lint → build
 ```
 
+## Lockfiles
+
+A Stacks project commits two lockfiles, and they describe one tree:
+
+- `bun.lock` resolves `node_modules/`, which the app root reads.
+- `pantry.lock` records the system toolchain (Bun itself, SQLite, curl, git)
+  **and** every npm package, which `pantry/` holds and the framework source
+  resolves from.
+
+Since pantry 0.11.65 an npm range resolves to `bun.lock`'s pin whenever that
+pin satisfies it, so the two agree on every package they both name. Since
+0.11.60 the file is platform-independent: `pantry install` on macOS writes what
+CI writes on Linux, foreign-platform records included.
+
+**Regenerating.** Change the ranges, run `bun install`, then `pantry install`,
+on any platform, and commit `bun.lock` and `pantry.lock` with the manifests.
+Check `head -2 bun.lock` says `lockfileVersion: 2`; an older Bun on PATH
+downgrades it.
+
+**Who else writes them.**
+
+- `buddy release` regenerates both and refuses to commit a `pantry.lock` that
+  violates a range it records or drops the root `system` block.
+- The dependency bot (`@buddysh/buddy` 0.11.5+, via `better-dx`) runs
+  `pantry install` after the JS manager on its Linux runner, so dependency pull
+  requests arrive with both lockfiles current.
+
+**The guards.** CI's `compile` job installs and fails if either lockfile
+changed, and `lockfile-matches-manifests.test.ts` compares the ranges both
+lockfiles record against the manifests. Either failure means a lockfile was
+not regenerated with its manifest, not that the guard is wrong.
+
 ## Dependency Update System
 
-- **buddy-bot** handles dependency updates — NOT renovatebot
-- Automated PR creation for dependency updates
-- Configured via `config/buddy-bot.ts`
+- **buddy-bot** (`@buddysh/buddy`, shipped by `better-dx`) handles dependency updates, NOT renovatebot
+- Automated PR creation for dependency updates, run as `bunx @buddysh/buddy` in `.github/workflows/buddy-bot.yml`
+- Configured via `config/buddy-bot.ts` (read as the pre-rename fallback for `config/buddy.ts`, which in a Stacks app would read as the Stacks CLI's config)
 
 ## Gotchas
 - **buddy-bot, not renovatebot** — Stacks uses its own dependency update bot

package/ai/skills/stacks-env/SKILL.md

@@ -164,7 +164,10 @@ allowing your own machine must not also allow CI.
 
 The answer is the same in a web or API server, the dashboard, a worker and a
 Buddy command, because all of them read the same variable. Browser integrations
-receive only the resolved public label, never server credentials.
+receive only the resolved public label, never server credentials. With the
+AnalyticsHQ driver that label is the tag's `data-environment` attribute, which
+the tracker attaches to every pageview, custom event and Web Vitals beacon, so
+`staging` traffic is distinguishable without a second site id.
 
 `APP_ENV` is a configuration label, not proof of deployment identity: a local
 command launched with `APP_ENV=production` qualifies. It prevents accidents; it

package/ai/skills/stacks-migrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 229 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 231 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -119,6 +119,6 @@ The framework includes migrations for all built-in models:
 - Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
 - If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
-- 229 migration files exist by default for all framework models
+- 231 migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)
 - For the database API (queries, connections), see the `stacks-database` skill

package/ai/skills/stacks-models/SKILL.md

@@ -88,7 +88,7 @@ generated model types stay precise.
 | `guarded` | Block mass assignment |
 | `hidden` | Exclude from JSON serialization (passwords, tokens) |
 | `foreignKey` | Disable, infer, or configure the FK constraint |
-| `factory` | `(faker) => value`, used by seeders and tests |
+| `factory` | `(faker, attributes) => value`, used by seeders and tests. `attributes` holds what this record's earlier-declared factories produced, so one value can depend on another: `(faker, { discountType }) => ...` |
 | `validation` | `{ rule, message? }` - `rule` from `schema`, `message` keyed by rule name |
 
 ### Traits
@@ -294,7 +294,7 @@ list, or `buddy list` for what a given project resolves.
 
 ### Commerce (20+ models)
 - **Product** — name(max100), description, price(min1), imageUrl, isAvailable, inventoryCount, preparationTime, allergens(JSON), nutritionalInfo(JSON) | belongsTo: Category, Manufacturer | hasMany: Review, ProductUnit, ProductVariant, LicenseKey, WaitlistProduct, Coupon | seeder: 10, dashboard: highlighted
-- **ProductVariant** — SKU, options, pricing
+- **ProductVariant** — variant, type, options, status, sku (unique per product), price / compareAtPrice (minor units, null price inherits the product's), inventoryCount (null = untracked) | belongsTo: Product | seeder: 50
 - **ProductUnit** — unit-specific pricing
 - **Cart** — status(active|abandoned|converted|expired), totalItems, subtotal, taxAmount, discountAmount, total, expiresAt, currency(USD), notes | hasMany: CartItem | belongsTo: Customer, Coupon
 - **CartItem** — quantity(min1), unitPrice, totalPrice, taxRate, taxAmount, discountPercentage, productName, productSku | belongsTo: Cart

package/app/Actions/Commerce/Product/ProductStoreAction.ts

@@ -1,7 +1,9 @@
 import { Action } from '@stacksjs/actions'
 
 import { products } from '@stacksjs/commerce'
+import { toSnakeCaseKeys } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { commerceMinorAmountError } from '../commerce-action'
 
 export default new Action({
   name: 'ProductItem Store',
@@ -10,7 +12,13 @@ export default new Action({
   model: Product,
   async handle(request: RequestInstance) {
     await request.validate()
-    const data = request.all()
+    const priceError = commerceMinorAmountError(request, 'price', 'Price', { required: true, min: 1 })
+    if (priceError)
+      return priceError
+    // The dashboard sends camelCase (`imageUrl`); the table is snake_case, as
+    // ProductUpdateAction already accounts for. Without this every product
+    // added from the dashboard failed with "no column named imageUrl".
+    const data = toSnakeCaseKeys(request.all())
 
     const model = await products.items.store(data)
 

package/app/Actions/Commerce/Product/ProductUpdateAction.ts

@@ -2,7 +2,7 @@ import { Action } from '@stacksjs/actions'
 import { products } from '@stacksjs/commerce'
 import { toSnakeCaseKeys } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
-import { commerceIdentifier, commerceNotFound } from '../commerce-action'
+import { commerceIdentifier, commerceMinorAmountError, commerceNotFound } from '../commerce-action'
 
 export default new Action({
   name: 'Product Update',
@@ -16,6 +16,9 @@ export default new Action({
     const { id } = identifier
 
     await request.validate()
+    const priceError = commerceMinorAmountError(request, 'price', 'Price', { min: 1 })
+    if (priceError)
+      return priceError
     const data = toSnakeCaseKeys(request.all())
 
     const model = await products.items.update(id, data)

package/app/Actions/Commerce/commerce-action.test.ts

@@ -1,6 +1,6 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { describe, expect, test } from 'bun:test'
-import { commerceIdentifier, commerceNotFound } from './commerce-action'
+import { commerceIdentifier, commerceMinorAmountError, commerceNotFound } from './commerce-action'
 
 function request(id: string): RequestInstance {
   return {
@@ -29,3 +29,32 @@ describe('commerce action responses', () => {
     })
   })
 })
+
+function body(fields: Record<string, unknown>): RequestInstance {
+  return {
+    get: (name: string) => fields[name],
+  } as unknown as RequestInstance
+}
+
+describe('commerce minor-unit amounts (stacksjs/stacks#2851)', () => {
+  test('accepts an integer number of minor units', () => {
+    expect(commerceMinorAmountError(body({ price: 1999 }), 'price', 'Price', { required: true, min: 1 })).toBeUndefined()
+    expect(commerceMinorAmountError(body({ price: '1999' }), 'price', 'Price', { required: true, min: 1 })).toBeUndefined()
+  })
+
+  test('rejects a decimal, which would be stored as a fraction of a cent', async () => {
+    const result = commerceMinorAmountError(body({ price: 19.99 }), 'price', 'Price', { required: true, min: 1 })
+    expect(result?.status).toBe(422)
+    expect(await result?.json()).toEqual({
+      message: 'Price must be a whole number of minor units, for example 1999 for 19.99.',
+      errors: { price: ['Price must be a whole number of minor units, for example 1999 for 19.99.'] },
+    })
+    expect(commerceMinorAmountError(body({ price: '19.99' }), 'price', 'Price')?.status).toBe(422)
+  })
+
+  test('enforces the minimum and presence only when asked', () => {
+    expect(commerceMinorAmountError(body({ price: 0 }), 'price', 'Price', { min: 1 })?.status).toBe(422)
+    expect(commerceMinorAmountError(body({}), 'price', 'Price', { required: true })?.status).toBe(422)
+    expect(commerceMinorAmountError(body({}), 'price', 'Price')).toBeUndefined()
+  })
+})

package/app/Actions/Commerce/commerce-action.ts

@@ -21,3 +21,47 @@ export function commerceIdentifier(
 export function commerceNotFound(resource: string, id: number): Response {
   return response.json({ message: `${resource} ${id} was not found.` }, 404)
 }
+
+export interface CommerceMinorAmountOptions {
+  /** Whether a missing value is an error (create) or leaves the column alone (update). */
+  required?: boolean
+  /** Smallest accepted amount in minor units. Defaults to 0. */
+  min?: number
+}
+
+/**
+ * A 422 when `request.<field>` is not an integer number of minor units.
+ *
+ * Money columns hold integer minor units (`1999` is $19.99), and model
+ * validation only says "a number", so `19.99` used to be stored as nineteen
+ * cents and 99 hundredths and then totalled as such (stacksjs/stacks#2851).
+ * The dashboard converts what people type before sending it; this stops any
+ * other caller writing a decimal.
+ */
+export function commerceMinorAmountError(
+  request: RequestInstance,
+  field: string,
+  label: string,
+  options: CommerceMinorAmountOptions = {},
+): Response | undefined {
+  const raw = request.get(field) as unknown
+  if (raw === undefined || raw === null || raw === '') {
+    if (!options.required)
+      return undefined
+    return minorAmountResponse(field, `${label} is required.`)
+  }
+
+  const amount = typeof raw === 'string' && /^\d+$/.test(raw.trim()) ? Number(raw) : raw
+  if (typeof amount !== 'number' || !Number.isSafeInteger(amount))
+    return minorAmountResponse(field, `${label} must be a whole number of minor units, for example 1999 for 19.99.`)
+
+  const min = options.min ?? 0
+  if (amount < min)
+    return minorAmountResponse(field, `${label} must be at least ${min}.`)
+
+  return undefined
+}
+
+function minorAmountResponse(field: string, message: string): Response {
+  return response.json({ message, errors: { [field]: [message] } }, 422)
+}

package/app/Actions/Dashboard/Analytics/sales-analytics.test.ts

@@ -63,4 +63,23 @@ describe('sales analytics', () => {
       currency: 'USD',
     }])
   })
+
+  test('averages integer minor units to a whole minor unit (stacksjs/stacks#2851)', () => {
+    const result = buildSalesAnalytics(
+      [
+        { id: '1', status: 'DELIVERED', totalAmount: 1999, currency: 'USD', createdAt: '2026-07-29T10:00:00.000Z' },
+        { id: '2', status: 'DELIVERED', totalAmount: 1000, currency: 'USD', createdAt: '2026-07-29T10:30:00.000Z' },
+      ],
+      [],
+      [],
+      [],
+      [],
+      'day',
+      now,
+    )
+
+    // 1499.5 cents would render as $15.00 anyway; the payload should not carry
+    // an amount no column can hold.
+    expect(result.currencyTotals[0]).toMatchObject({ gross: 2999, net: 2999, average: 1500 })
+  })
 })

package/app/Actions/Dashboard/Analytics/sales-analytics.ts

@@ -111,7 +111,8 @@ export function buildSalesAnalytics(
       gross: total.gross,
       cancelled: total.cancelled,
       net: total.gross - total.cancelled,
-      average: total.orders > 0 ? Math.round((total.gross / total.orders) * 100) / 100 : 0,
+      // Amounts are integer minor units, so the average rounds to a whole one.
+      average: total.orders > 0 ? Math.round(total.gross / total.orders) : 0,
     }))
     .sort((left, right) => right.net - left.net)
 

package/app/Actions/Dashboard/Commerce/CommercePosCheckoutAction.ts

@@ -112,7 +112,8 @@ async function existingReceipt(order: any) {
   }))
   const taxAmount = receiptNumber(field(order, 'tax_amount', 'taxAmount'), source, 'tax_amount', { min: 0 })
   const totalAmount = receiptNumber(field(order, 'total_amount', 'totalAmount'), source, 'total_amount', { min: 0 })
-  const subtotal = Math.round((totalAmount - taxAmount + Number.EPSILON) * 100) / 100
+  // Integer minor units, as the sale was recorded (stacksjs/stacks#2851).
+  const subtotal = totalAmount - taxAmount
   if (subtotal < 0)
     throw new TypeError(`${source}.tax_amount cannot exceed total_amount.`)
   const taxRate = deriveCommercePosTaxRate(subtotal, taxAmount)
@@ -137,7 +138,7 @@ async function existingReceipt(order: any) {
         name,
         quantity,
         unitPrice,
-        lineTotal: Math.round((unitPrice * quantity + Number.EPSILON) * 100) / 100,
+        lineTotal: unitPrice * quantity,
         specialInstructions: receiptOptionalText(
           field(item, 'special_instructions', 'specialInstructions'),
           itemSource,

package/app/Actions/Dashboard/Commerce/commerce-dashboard.test.ts

@@ -64,13 +64,13 @@ describe('commerce dashboard', () => {
   test('builds aligned metrics and chart buckets without counting cancelled revenue', () => {
     const result = buildCommerceDashboard(
       [
-        { id: '1', status: 'DELIVERED', totalAmount: 100, currency: 'USD', customerId: '9', createdAt: '2026-07-29 10:00:00' },
-        { id: '2', status: 'CANCELED', totalAmount: 60, currency: 'USD', customerId: '', createdAt: '2026-07-29 11:00:00' },
-        { id: '3', status: 'DELIVERED', totalAmount: 50, currency: 'USD', customerId: '9', createdAt: '2026-07-28 10:00:00' },
+        { id: '1', status: 'DELIVERED', totalAmount: 10000, currency: 'USD', customerId: '9', createdAt: '2026-07-29 10:00:00' },
+        { id: '2', status: 'CANCELED', totalAmount: 6000, currency: 'USD', customerId: '', createdAt: '2026-07-29 11:00:00' },
+        { id: '3', status: 'DELIVERED', totalAmount: 5000, currency: 'USD', customerId: '9', createdAt: '2026-07-28 10:00:00' },
       ],
       [
-        { orderId: '1', productId: '4', quantity: 2, price: 50 },
-        { orderId: '2', productId: '4', quantity: 1, price: 60 },
+        { orderId: '1', productId: '4', quantity: 2, price: 5000 },
+        { orderId: '2', productId: '4', quantity: 1, price: 6000 },
       ],
       [{ id: '4', name: 'Native Kit' }],
       [{ id: '9', name: 'Ada Lovelace' }],
@@ -82,6 +82,7 @@ describe('commerce dashboard', () => {
     expect(result.stats.map(stat => stat.value)).toEqual(['$100.00', '2', '$100.00', '100.0%'])
     expect(result.charts.labels).toHaveLength(13)
     expect(result.charts.orders.reduce((sum, value) => sum + value, 0)).toBe(2)
+    // Stored in cents, charted in dollars.
     expect(result.charts.revenue[0].data.reduce((sum, value) => sum + value, 0)).toBe(100)
     expect(result.topProducts).toEqual([
       { id: '4:USD', name: 'Native Kit', sales: 2, revenue: '$100.00' },
@@ -98,12 +99,12 @@ describe('commerce dashboard', () => {
   test('keeps currencies separate in revenue, averages, charts, and product totals', () => {
     const result = buildCommerceDashboard(
       [
-        { id: '1', status: 'DELIVERED', totalAmount: 100, currency: 'USD', customerId: '', createdAt: '2026-07-29T08:00:00.000Z' },
-        { id: '2', status: 'DELIVERED', totalAmount: 80, currency: 'EUR', customerId: '', createdAt: '2026-07-29T09:00:00.000Z' },
+        { id: '1', status: 'DELIVERED', totalAmount: 10000, currency: 'USD', customerId: '', createdAt: '2026-07-29T08:00:00.000Z' },
+        { id: '2', status: 'DELIVERED', totalAmount: 8000, currency: 'EUR', customerId: '', createdAt: '2026-07-29T09:00:00.000Z' },
       ],
       [
-        { orderId: '1', productId: '4', quantity: 2, price: 50 },
-        { orderId: '2', productId: '4', quantity: 1, price: 80 },
+        { orderId: '1', productId: '4', quantity: 2, price: 5000 },
+        { orderId: '2', productId: '4', quantity: 1, price: 8000 },
       ],
       [{ id: '4', name: 'Native Kit' }],
       [],
@@ -119,6 +120,25 @@ describe('commerce dashboard', () => {
     expect(result.topProducts).toHaveLength(2)
   })
 
+  test('shows integer minor units in each currency precision (stacksjs/stacks#2851)', () => {
+    const result = buildCommerceDashboard(
+      [
+        { id: '1', status: 'DELIVERED', totalAmount: 1999, currency: 'USD', customerId: '', createdAt: '2026-07-29T08:00:00.000Z' },
+        { id: '2', status: 'DELIVERED', totalAmount: 1999, currency: 'JPY', customerId: '', createdAt: '2026-07-29T09:00:00.000Z' },
+      ],
+      [{ orderId: '1', productId: '4', quantity: 1, price: 1999 }],
+      [{ id: '4', name: 'Native Kit' }],
+      [],
+      'today',
+      now,
+    )
+
+    expect(result.stats[0].detail).toContain('$19.99')
+    expect(result.stats[0].detail).toContain('¥1,999')
+    expect(result.topProducts[0]?.revenue).toBe('$19.99')
+    expect(result.charts.revenue.find(series => series.currency === 'USD')?.data.reduce((sum, value) => sum + value, 0)).toBe(19.99)
+  })
+
   test('compares the selected range with the immediately preceding range', () => {
     const result = buildCommerceDashboard(
       [

package/app/Actions/Dashboard/Commerce/commerce-dashboard.ts

@@ -1,3 +1,4 @@
+import { formatCurrency, minorToMajor } from '@stacksjs/commerce/money'
 import {
   commerceCurrency,
   commerceIdentifier,
@@ -45,6 +46,7 @@ export interface CommerceDashboardStat {
 
 export interface CommerceDashboardChartSeries {
   labels: string[]
+  /** Major units per bucket (19.99, not 1999): chart axes are read by people. */
   revenue: Array<{ currency: string, data: number[] }>
   orders: number[]
 }
@@ -239,18 +241,9 @@ function percentChange(current: number, previous: number): string {
   return `${sign}${percentage.toFixed(1)}%`
 }
 
+/** Order amounts are integer minor units (stacksjs/stacks#2851). */
 function formatMoney(amount: number, code: string): string {
-  try {
-    return new Intl.NumberFormat('en-US', {
-      style: 'currency',
-      currency: code,
-      minimumFractionDigits: 2,
-      maximumFractionDigits: 2,
-    }).format(amount)
-  }
-  catch {
-    return `${code} ${amount.toFixed(2)}`
-  }
+  return formatCurrency(amount, code, 'en-US')
 }
 
 function formatCurrencyTotals(totals: Map<string, number>): { value: string, detail: string } {
@@ -505,7 +498,7 @@ export function buildCommerceDashboard(
       labels: buckets.map(bucket => bucket.label),
       revenue: [...revenueSeries.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([code, data]) => ({ currency: code, data })),
+        .map(([code, data]) => ({ currency: code, data: data.map(amount => minorToMajor(amount, code)) })),
       orders: orderSeries,
     },
     topProducts: [...productTotals.entries()]

package/app/Actions/Dashboard/Commerce/commerce-delivery.test.ts

@@ -84,6 +84,21 @@ describe('commerce delivery overview', () => {
     })
   })
 
+  test('formats shipping rates in the currency\'s own minor unit (stacksjs/stacks#2851)', () => {
+    const methods = (currency: string) => buildDeliveryOverview(
+      [{ id: 1, name: 'Express', status: 'active', base_rate: 1500, free_shipping: 5000 }],
+      [],
+      [],
+      [],
+      currency,
+      now,
+    ).methods[0]
+
+    // A yen has no minor unit, so 1500 is 1,500 yen, not 15.
+    expect(methods('JPY')).toMatchObject({ baseRate: '¥1,500', freeShipping: '¥5,000' })
+    expect(methods('USD')).toMatchObject({ baseRate: '$15.00', freeShipping: '$50.00' })
+  })
+
   test('rejects corrupt delivery records and missing courier relationships', () => {
     expect(() => buildDeliveryOverview(
       [{ id: 1, name: 'Ground', status: 'active', base_rate: 'free', free_shipping: null }],

package/app/Actions/Dashboard/Commerce/commerce-delivery.ts

@@ -1,3 +1,5 @@
+import { formatCurrency } from '@stacksjs/commerce/money'
+
 export interface DeliveryOverviewStat {
   label: string
   value: string
@@ -45,16 +47,12 @@ export interface DeliveryOverviewResult {
 
 const DAY_MS = 24 * 60 * 60 * 1000
 
-function formatMoney(cents: number, currency: string): string {
-  try {
-    return new Intl.NumberFormat('en-US', {
-      style: 'currency',
-      currency,
-    }).format(cents / 100)
-  }
-  catch {
-    return `${currency} ${(cents / 100).toFixed(2)}`
-  }
+/**
+ * Shipping rates and thresholds are integer minor units. Dividing by 100 was
+ * right for USD and EUR and a hundred times off for JPY (stacksjs/stacks#2851).
+ */
+function formatMoney(minor: number, currency: string): string {
+  return formatCurrency(minor, currency, 'en-US')
 }
 
 export function deliveryTimestamp(input: unknown, source = 'DeliveryRoute', field = 'last_active'): number {

package/app/Actions/Dashboard/Commerce/commerce-pos.test.ts

@@ -25,13 +25,13 @@ describe('dashboard commerce POS helpers', () => {
     expect(result.error).toContain('between 1 and 999')
   })
 
-  it('recomputes server-authoritative totals from persisted prices', () => {
+  it('recomputes server-authoritative totals from persisted prices, in minor units', () => {
     const sale = calculateCommercePosSale([
       {
         id: '4',
         name: 'Widget',
         description: '',
-        price: 12.5,
+        price: 1250,
         isAvailable: true,
         inventoryCount: 20,
         preparationTime: 4,
@@ -40,9 +40,29 @@ describe('dashboard commerce POS helpers', () => {
         categoryName: 'Unassigned category',
       },
     ], [{ productId: 4, quantity: 3, specialInstructions: '' }], 8.25)
-    expect(sale.subtotal).toBe(37.5)
-    expect(sale.taxAmount).toBe(3.09)
-    expect(sale.totalAmount).toBe(40.59)
+    // $12.50 x 3 = $37.50; 8.25% of it is 309.375 cents, which rounds to 309.
+    expect(sale.lines[0]?.lineTotal).toBe(3750)
+    expect(sale.subtotal).toBe(3750)
+    expect(sale.taxAmount).toBe(309)
+    expect(sale.totalAmount).toBe(4059)
+  })
+
+  it('refuses a product whose price is not integer minor units (stacksjs/stacks#2851)', () => {
+    expect(() => calculateCommercePosSale([
+      {
+        id: '4',
+        name: 'Widget',
+        description: '',
+        price: 12.5,
+        isAvailable: true,
+        inventoryCount: 20,
+        preparationTime: 4,
+        allergens: [],
+        categoryId: '',
+        categoryName: 'Unassigned category',
+      },
+    ], [{ productId: 4, quantity: 1, specialInstructions: '' }], 0))
+      .toThrow('expected integer minor units')
   })
 
   it('chooses an active default tax rate', () => {
@@ -81,7 +101,7 @@ describe('dashboard commerce POS helpers', () => {
         id: '4',
         name: 'Widget',
         description: '',
-        price: 12.5,
+        price: 1250,
         isAvailable: true,
         inventoryCount: 2,
         preparationTime: 4,

package/app/Actions/Dashboard/Commerce/commerce-pos.ts

@@ -51,8 +51,13 @@ export class CommercePosAvailabilityError extends Error {
   }
 }
 
+/**
+ * Amounts are integer minor units, as `products.price` is (stacksjs/stacks#2851).
+ * Line totals and sums of integers are already whole; tax is the one product
+ * that can land between two units, and it rounds to the nearest one.
+ */
 function money(value: number): number {
-  return Math.round((value + Number.EPSILON) * 100) / 100
+  return Math.round(value)
 }
 
 function value(record: any, ...keys: string[]): unknown {
@@ -206,8 +211,8 @@ export function calculateCommercePosSale(
     const id = Number(product.id)
     if (!Number.isSafeInteger(id) || id <= 0)
       throw new TypeError(`Product id "${product.id}" is invalid.`)
-    if (!Number.isFinite(product.price) || product.price < 0)
-      throw new TypeError(`Product ${id} has an invalid price.`)
+    if (!Number.isSafeInteger(product.price) || product.price < 0)
+      throw new TypeError(`Product ${id} has an invalid price: expected integer minor units.`)
     if (!Number.isSafeInteger(product.inventoryCount) || product.inventoryCount < 0)
       throw new TypeError(`Product ${id} has an invalid inventory count.`)
     return [id, product] as const