@amboras-dev/money 0.2.0 → 0.4.0

package/README.md

@@ -152,7 +152,9 @@ unit apart).
 **Formatting** (for people, not byte-stable across ICU): `formatMoney` (display digits, or
 `widen` / `trim-zero`; explicit locale, default `en-US`), `formatMoneyCompact`,
 `formatMoneyRange`, `moneyAxisFormatter`, `formatStored` (a possibly fractional stored amount,
-rounded half-up to a storage unit, then `formatMoney`).
+rounded half-up to a storage unit, then `formatMoney`). `rounding: 'down'` rounds toward zero
+instead, for an upper bound that must never read above itself (a refund cap of HUF 435050 shows
+`HUF 4,350`, not 4,351).
 
 Internals other entry points build on (never exported), each the only implementation of its concept:
 `internal/number-text.ts` `readNumberText` (the one separator engine), `internal/rational.ts`
@@ -168,18 +170,20 @@ import { money } from '@amboras-dev/money'
 import { ISO_MINOR_V2, conventionOf, decodeWire, encodeWire } from '@amboras-dev/money/wire'
 
 encodeWire('stripe', money(120000, 'JPY'), { convention: ISO_MINOR_V2 }) // 1200
-decodeWire('stripe', 1200, 'JPY', conventionOf(paymentIntent))          // { amount: 120000, currency: 'JPY' }
+decodeWire('stripe', 1200, 'JPY', { convention: conventionOf(paymentIntent) })   // { amount: 120000, currency: 'JPY' }
+decodeWire('stripe', -44, 'USD', { convention: ISO_MINOR_V2, allowNegative: true }) // signed balance read
 encodeWire('mollie', { amount: '107.8175', currency: 'USD' })             // '1.08': a fractional stored total
 ```
 
 A Medusa session amount can be fractional at storage scale (107.8175). `encodeWire` and `sameWireAmount` take it as a `FractionalMoney` and round it by the PSP's own rule: Stripe and Adyen to a whole storage unit first, whole-unit PSPs (MoMo, Payoo, VNPay, Paystack XOF) refuse it, a pre-cutover Razorpay payment refuses it, every other PSP rounds once, half-up, at its wire unit.
 
-- Codec: `encodeWire`, `decodeWire`, `tryDecodeWire` (never throws), `wireFactor`, `pspWireDigits`, `oneWireUnit`, `wireBreakdown` (line items that sum to the encoded total), `wireKeyPart`.
+- Codec: `encodeWire`, `decodeWire` (one options object `{ convention, allowNegative }`; a negative provider amount throws unless `allowNegative: true`), `tryDecodeWire` (never throws), `wireFactor`, `pspWireDigits`, `oneWireUnit`, `wireBreakdown` (line items that sum to the encoded total), `wireKeyPart`.
 - Cutover marker: `WIRE_SCALE_KEY`, `WIRE_SCALE_ISO_MINOR_V2`, `WIRE_SCALE_MARKER`, `ISO_MINOR_V2`, `PRE_CUTOVER`, `conventionOf` (gated PSPs need the convention; there is no hidden default).
-- Provider tables: `PSP_IDS`, `pspSupportsCurrency`, `assertPspCurrency`, `pspCurrencies` (what the codec scales), `pspDefaultCurrency`, `pspMinimumAmount`.
-- Presentment (eligibility): `pspPresentmentCurrencies(psp, { accountCountry })` (what an account can charge buyers in) and `pspPresentment(psp)` (the rules as data: union, currencies needing an account country, account countries limited to a list).
-- Comparison: `sameWireAmount` (a webhook amount against the expected Money or FractionalMoney, exactly at storage scale; `acceptLegacyIsoDigits`, `textOnly`).
-- Provider quirks: `verificationCharge`, `RAZORPAY_AFA_FREE_CAP`, `iyzicoPrice`, `authorizeNetReversibleAmount`, `jsonDecimalLiteral`.
+- Wire-rounding marker: `WIRE_ROUNDING_KEY`, `WIRE_ROUNDING_EXACT`, `WIRE_ROUNDING_MARKER` (stamped on new sessions of the PSPs Medusa encoded in floating point before 0.2.0), `mayHoldLegacyFloatRounding` (no marker: the session predates that deploy).
+- Provider tables: `PSP_IDS`, `pspSupportsCurrency`, `assertPspCurrency` (typed `PspCurrency<P>`: `AuthorizeNetCurrency`, `IyzicoCurrency`, `PaystackCurrency`, `'VND'` for the short fixed lists; `PAYSTACK_CURRENCIES` is Paystack's list as a tuple for validators and pickers), `pspCurrencies` (what the codec scales), `pspDefaultCurrency` (single-currency PSPs only), `pspHomeCurrency` (the currency every account charges without enabling anything: Razorpay INR, iyzico TRY, the VND rails), `pspHomeCountry` (the one country every account is registered in: iyzico TR, the VND rails VN), `pspMinimumAmount`.
+- Presentment (eligibility): `pspPresentmentCurrencies(psp, { accountCountry, includeOptIn })` (what an account can charge buyers in), `pspPresentment(psp)` (the rules as data: union, currencies needing an account country, account countries limited to a list, Paystack's per-country lists with USD as an explicit opt-in, and `optInCompanions`), `pspAccountCountryForCurrency` (Paystack NGN names NG; USD names nothing).
+- Comparison: `sameWireAmount` (a webhook amount against the expected Money or FractionalMoney, exactly at storage scale; `acceptLegacyIsoDigits`, `textOnly`, and `acceptLegacyFloatRounding` for the spelling Medusa's pre-0.2.0 float codec sent PayPal, Mollie, Airwallex, iyzico, Authorize.Net and Payoo: USD 1072.5 went as `'10.72'`, 0.2.0 sends `'10.73'`; pass `mayHoldLegacyFloatRounding(sessionData)`), and `legacyFloatRefundClamp` (a refund of such a capture lowered to what the PSP still holds, after any partial refunds: `'10.00'` where Medusa's remaining encodes `'10.01'`).
+- Provider quirks: `verificationCharge` (currency optional for Razorpay, INR only, and Mollie, EUR fallback), `RAZORPAY_AFA_FREE_CAP`, `iyzicoPrice`, `authorizeNetReversibleAmount`, `jsonDecimalLiteral`.
 - Provider text: `parseProviderAmount` (carrier quotes, dispute amounts; `decimalSeparator: 'auto'` is the `/input` rule).
 - Destinations: `destinationAmount` (pixels, ad platforms, email tools), `feedPrice`, `googleMicros`, `eventMoney` (ClickHouse `Int64` contract).
 - Plugin slots: `slotMoney`, `readSlotMoney`.
@@ -248,6 +252,8 @@ parseAmountInput('1,2345', 'USD')                         // { ok: false, reason
 parseAmountInput('99.000', 'VND')                         // 99000 (3-digit tail groups in a currency without decimals)
 parseAmountInput('12.99.', 'USD')                         // { ok: false, reason: 'unparseable' } (groups must be thousands or lakh)
 parseAmountInput('1.500', 'TND', { decimalSeparator: '.' }) // 1.5 (an <input type="number"> value: '.' is always the decimal)
+parseAmountInput('1.5', 'JPY', { decimalSeparator: '.' })   // { ok: false, reason: 'too_many_decimals' } (never rounded to 2)
+parseAmountInput('1.0', 'JPY', { decimalSeparator: '.' })   // 1 (trailing zeros carry no extra precision)
 formatAmountInput(money(1500, 'TND'), { decimalSeparator: '.' }) // '1.5' (the number input's prefill, read back exactly)
 formatAmountInput(money(123456789, 'USD'), { grouped: true, locale: 'de-DE' }) // '1.234.567,89'
 parseImportAmount('1.299,00')                             // '1299'
@@ -260,17 +266,20 @@ inputStep('KWD')                                          // '0.001'
 - `parseAmountInput(text, currency, { locale, decimalSeparator, allowNegative, allowZero, min, max, original })`: strips the currency's symbols and code and refuses more fraction digits than the currency stores.
   Without `locale` (the chat wizard and any field that has none) it reads the `'auto'` rule below, which is today's admin `parseMajorUnits` except the listed differences, and a currency storing 0 digits rounds a fraction half-up to a whole unit (`'1200.5'` JPY is 1201), as admin does.
   With `locale` it reads that locale's separators: the group separator is valid only in thousands groups (`'1,234,567'`) or Indian lakh groups (`'12,34,567'`: three digits on the right, then pairs), and only when every group fits (`'1,2345'` and `'12,3,456'` are `unparseable`), and extra digits are `too_many_decimals` in every currency.
+  The locale's decimal separator is never read as grouping: in a currency storing 0 digits, en-US `'1.234'`, `'19.999'` and `'1.000'` JPY are `too_many_decimals` (a thousands group to some, a fraction to others, and trailing zeros would let `'1.000'` through as ¥1); grouping uses the locale's group separator (`'1,234'` en-US, `'1.234'` de-DE).
   **Every number input (`<input type="number">`) must pass `{ decimalSeparator: '.' }`**: browsers always serialise its value with a `.` decimal and no grouping, so the free-text rule would misread it (TND and IQD `'1.500'` are 1,500 there, 1.5 here).
-  In `'.'` mode `.` is the decimal, `,` and grouping are `unparseable`, a zero whole part may be omitted (`'.5'` is 0.5), and a currency storing 0 digits rounds a fraction half-up to a whole unit, as admin `numericEntryToMinorUnits` does (`'1200.5'` JPY is 1201).
-  It equals that function on every `.`-only value within the storage digits (`test/input/input.test.ts`), except one class:
-  - `extra-fraction-digits`: in a currency storing 2 or 3 digits, more fraction digits than it stores is `too_many_decimals`, never rounded (`'1.239'` USD, admin 124 cents; KWD `'1.0005'`, admin 1001).
+  In `'.'` mode `.` is the decimal, `,` and grouping are `unparseable`, and a zero whole part may be omitted (`'.5'` is 0.5).
+  More fraction digits than the currency stores is `too_many_decimals` in every currency, never rounded: since 0.4.0 a currency storing 0 digits refuses any fraction (`'1.5'`, `'1.234'` and `'1200.5'` JPY and KRW; 0.3.0 rounded them half-up to ¥2, ¥1 and ¥1,201).
+  Trailing zeros carry no extra precision, so `'1.0'` and `'1.00'` JPY are ¥1, as with a locale; a sub-unit prefill (JPY 120050, `'1200.5'`) still reads back exactly through `original`.
+  It equals admin `numericEntryToMinorUnits` on every `.`-only value within the storage digits (`test/input/input.test.ts`), except one class:
+  - `extra-fraction-digits`: more fraction digits than the currency stores is `too_many_decimals`, never rounded (`'1.239'` USD, admin 124 cents; KWD `'1.0005'`, admin 1001; `'1.5'` JPY, admin ¥2).
   Failure reasons: `empty`, `unparseable`, `too_many_decimals`, `negative`, `zero`, `below_min`, `above_max`.
 - `formatAmountInput(m, { locale, decimalSeparator, grouped, digits })`: the field text for a stored amount, no symbol, exact: a sub-unit stored amount keeps its digits (JPY 120050, which Medusa writes today, is `'1200.5'`), never rounded on display.
   Without `locale` it prints the spelling `parseAmountInput` reads back without a locale: trailing fraction zeros dropped (USD `'12.5'`, KWD 1500 `'1.5'`, IQD 10000000 `'10000'`), and TND, which writes a decimal comma, with `,` as the decimal and `.` as the group (`'1,125'`, `'1.234,5'`).
   Two amounts have no such spelling and read back only through `original`: IQD with a three-digit fraction (`'1.125'` reads as 1,125, since IQD displays no decimals) and a sub-unit amount of a currency storing 0 digits (`'1200.5'` JPY reads as a whole 1,201).
   With `locale` it uses that locale's separators and the storage digits (`'12,50'` de-DE); `digits: 'storage'` or `'trim-zero'` overrides the zeros either way.
   With `decimalSeparator: '.'` (a number input's prefill) it prints `.` as the decimal, never groups and drops trailing zeros (TND 1500 is `'1.5'`), so `parseAmountInput(text, currency, { decimalSeparator: '.' })` reads it back exactly (a sub-unit JPY amount through `original`).
-  Prefill and save with `parseAmountInput(text, currency, { original: m })`: the untouched prefill text, or any text equal in value to `m`, returns `m` unchanged, so saving an untouched field never rewrites the amount.
+  Prefill and save with `parseAmountInput(text, currency, { original: m })`: the untouched prefill text, or any text equal in value to `m`, returns `m` unchanged, so saving an untouched field never rewrites the amount (an ambiguous zero-digit text such as en-US `'1.000'` JPY is refused even then).
 - `inputStep`, `inputPlaceholder`: from the storage digits, never a hardcoded `0.01`.
 - `parseImportAmount(text, { decimalSeparator: 'auto' | '.' | ',', currency, allowNegative, allowTrailingText })`: CSV, supplier, scraped and carrier text to `DecimalText` (major units), or `null`.
   `'auto'` is the only comma/dot rule in the package (`/ai` `moneyMentions`, `/wire` `parseProviderAmount` and `moneyTemplateOf` use it too), and it treats `.` and `,` the same way:
@@ -318,6 +327,7 @@ Framework-agnostic: no test runner or fast-check dependency.
   A positive amount whose wire rounds to 0 (68 vectors: one storage unit of a zero-decimal currency at Stripe, Adyen, Razorpay, Airwallex, PayPal HUF/JPY/TWD, Mollie ISK/JPY) is a refusal vector by package policy: `encodeWire` refuses it with `wire_refused` (`... rounds to 0 at <Tag> ...`).
   Medusa today puts 0 on the wire at initiate for Stripe and Adyen, and for Razorpay, PayPal and Airwallex everywhere; it refuses at refund and capture for Stripe and Adyen, and in Mollie, iyzico and Authorize.Net.
 - `PSP_FRACTIONAL_GOLDEN_VECTORS`: the same codecs fed fractional storage amounts (0.4, 0.5, ties, 107.8175, a fraction of a dong); `policy` and `medusa` mark where `encodeWire` departs from them on purpose (the sub-unit refusal, exact half-up at ties float `toFixed` rounds down, the real amount in a refusal message).
+- `PSP_LEGACY_FLOAT_GOLDEN_VECTORS`: for the PSPs Medusa encoded in floating point before 0.2.0, what those codecs sent at whole, fractional and tie amounts, and their ISO-digit spelling; `sameWireAmount`'s `acceptLegacyFloatRounding` accepts every one.
 - `DESTINATION_GOLDEN_VECTORS`: what `destinationAmount`, `feedPrice` and `googleMicros` must give per destination.
 - `checkWireDigits(psp, documented)`: the capability-consistency probe; returns mismatch messages.
 - `normalizeIntlSpaces(s)`, `sampleMoney(currency, major)`.
@@ -339,6 +349,7 @@ The full list, with the decision behind each, is in [`docs/money/API-SPEC.md`](.
   `formatMoney`, `moneyView` (`/ai`), `destinationAmount` and `feedPrice` (`/wire`) use the display digits; capability-kit, the plugins and Medusa's `formatMoney` use the storage digits today.
   This is deliberate: it is what the PSPs charge and what people read.
   - `formatMoney` (default `digits: 'display'`) rounds half-up: HUF 435050 was `HUF 4,350.50` and is `HUF 4,351`; IQD 1500 was `IQD 1.500` and is `IQD 2`.
+    A cap ("refund at most") passes `rounding: 'down'`, so HUF 435050 shows `HUF 4,350` and typing the amount shown stays within it.
   - Catalog feeds and destinations drop the sub-unit the same way: `feedPrice(money(435050, 'HUF'))` is `'4351 HUF'`, IQD 1500 is `'2 IQD'`.
   - Model views keep the value but show fewer zeros: `moneyView` returns the exact `amount` and widens `display` only for a sub-unit value (`'HUF 4,350.5'`), so HUF 435000 is `'HUF 4,350'` where capability-kit shows `'HUF 4,350.00'`, and IQD 1500 is `'IQD 1.5'` where it shows `'IQD 1.500'`.
   - Machine files that need storage precision use `toMajorDecimal(m)` or `formatAmountInput(m)`.

package/dist/ai.cjs

@@ -1,9 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_money = require("./money-B3wH_Z4S.cjs");
-const require_format = require("./format-DLhno7eX.cjs");
-const require_number_text = require("./number-text-BWu67jUq.cjs");
-const require_amount = require("./amount-BV0O-aN8.cjs");
-//#region src/ai/mentions.ts
+const require_money = require("./money-DWBjuuEK.cjs");
+const require_format = require("./format-92fzvTXY.cjs");
+const require_number_text = require("./number-text-CWuVwrlg.cjs");
+const require_amount = require("./amount-Bzxw9aD4.cjs");
+// src/ai/mentions.ts
 const ACTIVE = require_money.CURRENCIES.filter((c) => c.status === "active");
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const LETTER_START = /^\p{L}/u;
@@ -84,8 +84,7 @@ function moneyMentions(text, options = {}) {
 	}
 	return mentions;
 }
-//#endregion
-//#region src/ai/wording.ts
+// src/ai/wording.ts
 /** The one unit sentence every money field carries, for the model and for people. Verbatim. */
 const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
 /** JSON Schema keyword marking a money field. Verbatim. */
@@ -99,8 +98,7 @@ function moneyFieldDescription(describe) {
 	const lead = typeof describe === "string" ? describe.trim() : "";
 	return lead ? `${lead} ${MONEY_UNIT_SENTENCE}` : MONEY_UNIT_SENTENCE;
 }
-//#endregion
-//#region src/ai/model-money.ts
+// src/ai/model-money.ts
 /**
 * `{ amount: 19.99, currency: 'USD', display: '$19.99' }`. `amount` is exact; `display` shows the
 * display digits, widened to keep a stored value finer than them (JPY 550 is `'¥5.5'`, HUF 435050
@@ -126,7 +124,7 @@ function failure(reason, input, code, digits) {
 		error: `${{
 			empty: `Not an amount: ${shown}.`,
 			unparseable: `Not an amount: ${shown}.`,
-			too_many_decimals: `${shown} has more decimal places than ${code} uses (at most ${digits}).`,
+			too_many_decimals: digits === 0 ? `${shown} has more decimal places than ${code} uses (at most 0). Write thousands with ',' or without a separator (1,500 or 1500).` : `${shown} has more decimal places than ${code} uses (at most ${digits}).`,
 			negative: "The amount must not be negative.",
 			zero: "The amount must be more than zero.",
 			below_min: `${shown} is out of range for ${code}.`,
@@ -148,8 +146,10 @@ function fromNumber(input, currency, options) {
 * An amount from a model tool call (major units, as the merchant says it) as Money, or an
 * error to send back to the model ending with `MONEY_UNIT_SENTENCE`. Numbers go through
 * `fromMajor` (float noise such as 0.1 + 0.2 allowed); strings through `/input`'s entry rule
-* in English (`'1,299.00'`, `'$1,299'`, `'99.000'` VND, `'1.500'` JPY). More fraction digits
-* than the currency stores and negative amounts are refused, never rounded or flipped. An
+* in English (`'1,299.00'`, `'$1,299'`, `'99,000'` VND). More fraction digits than the
+* currency stores and negative amounts are refused, never rounded or flipped; so is a `.` before
+* three digits in a currency without decimals (`'99.000'` VND, `'1.500'` JPY: a thousands group
+* or a fraction?), and the error asks the model for `1,500` or `1500`. An
 * unknown currency throws `currency_invalid` (it is the tool's, not the model's).
 */
 function parseModelMoney(input, currency, options = {}) {
@@ -172,7 +172,6 @@ function parseModelMoney(input, currency, options = {}) {
 		money: result.money
 	} : failure(result.reason, input, info.code, info.storageDigits);
 }
-//#endregion
 exports.MONEY_META_KEY = MONEY_META_KEY;
 exports.MONEY_UNIT_SENTENCE = MONEY_UNIT_SENTENCE;
 exports.RATE_UNIT_SENTENCE = RATE_UNIT_SENTENCE;

package/dist/ai.d.cts

@@ -1,5 +1,4 @@
-import { R as DecimalText, g as CurrencyCode, i as Money } from "./money-B-3aFjNJ.cjs";
-//#region src/ai/mentions.d.ts
+import { R as DecimalText, g as CurrencyCode, i as Money } from "./money-BkMeYDEW.cjs";
 /** One price found in text. `code` is set when the mark names one currency; `amount` when the number reads (see the separator engine's 'auto' rule). */
 interface MoneyMention {
   /** The matched text, mark and number. */
@@ -43,8 +42,6 @@ export declare function moneyLiteralPattern(options?: {
 export declare function moneyMentions(text: string, options?: {
   currency?: string;
 }): MoneyMention[];
-//#endregion
-//#region src/ai/model-money.d.ts
 /** A stored amount as the model sees it: the major amount, the code and a display string. */
 interface MoneyView {
   readonly amount: number;
@@ -76,13 +73,13 @@ interface ParseModelMoneyOptions {
  * An amount from a model tool call (major units, as the merchant says it) as Money, or an
  * error to send back to the model ending with `MONEY_UNIT_SENTENCE`. Numbers go through
  * `fromMajor` (float noise such as 0.1 + 0.2 allowed); strings through `/input`'s entry rule
- * in English (`'1,299.00'`, `'$1,299'`, `'99.000'` VND, `'1.500'` JPY). More fraction digits
- * than the currency stores and negative amounts are refused, never rounded or flipped. An
+ * in English (`'1,299.00'`, `'$1,299'`, `'99,000'` VND). More fraction digits than the
+ * currency stores and negative amounts are refused, never rounded or flipped; so is a `.` before
+ * three digits in a currency without decimals (`'99.000'` VND, `'1.500'` JPY: a thousands group
+ * or a fraction?), and the error asks the model for `1,500` or `1500`. An
  * unknown currency throws `currency_invalid` (it is the tool's, not the model's).
  */
 export declare function parseModelMoney(input: unknown, currency: string, options?: ParseModelMoneyOptions): ParseModelMoneyResult;
-//#endregion
-//#region src/ai/wording.d.ts
 /** The one unit sentence every money field carries, for the model and for people. Verbatim. */
 export declare const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
 /** JSON Schema keyword marking a money field. Verbatim. */
@@ -93,5 +90,4 @@ export declare const STORAGE_UNIT_SENTENCE = "Store API amounts are storage unit
 export declare const RATE_UNIT_SENTENCE = "1 unit of the store currency equals this many units of the other currency.";
 /** A money field's description: `describe` (trimmed) followed by the unit sentence, or the sentence alone. */
 export declare function moneyFieldDescription(describe?: string): string;
-//#endregion
 export type { MoneyMention, MoneyView, ParseModelMoneyOptions, ParseModelMoneyResult };

package/dist/ai.d.ts

@@ -1,5 +1,4 @@
-import { R as DecimalText, g as CurrencyCode, i as Money } from "./money-B-3aFjNJ.js";
-//#region src/ai/mentions.d.ts
+import { R as DecimalText, g as CurrencyCode, i as Money } from "./money-BkMeYDEW.js";
 /** One price found in text. `code` is set when the mark names one currency; `amount` when the number reads (see the separator engine's 'auto' rule). */
 interface MoneyMention {
   /** The matched text, mark and number. */
@@ -43,8 +42,6 @@ export declare function moneyLiteralPattern(options?: {
 export declare function moneyMentions(text: string, options?: {
   currency?: string;
 }): MoneyMention[];
-//#endregion
-//#region src/ai/model-money.d.ts
 /** A stored amount as the model sees it: the major amount, the code and a display string. */
 interface MoneyView {
   readonly amount: number;
@@ -76,13 +73,13 @@ interface ParseModelMoneyOptions {
  * An amount from a model tool call (major units, as the merchant says it) as Money, or an
  * error to send back to the model ending with `MONEY_UNIT_SENTENCE`. Numbers go through
  * `fromMajor` (float noise such as 0.1 + 0.2 allowed); strings through `/input`'s entry rule
- * in English (`'1,299.00'`, `'$1,299'`, `'99.000'` VND, `'1.500'` JPY). More fraction digits
- * than the currency stores and negative amounts are refused, never rounded or flipped. An
+ * in English (`'1,299.00'`, `'$1,299'`, `'99,000'` VND). More fraction digits than the
+ * currency stores and negative amounts are refused, never rounded or flipped; so is a `.` before
+ * three digits in a currency without decimals (`'99.000'` VND, `'1.500'` JPY: a thousands group
+ * or a fraction?), and the error asks the model for `1,500` or `1500`. An
  * unknown currency throws `currency_invalid` (it is the tool's, not the model's).
  */
 export declare function parseModelMoney(input: unknown, currency: string, options?: ParseModelMoneyOptions): ParseModelMoneyResult;
-//#endregion
-//#region src/ai/wording.d.ts
 /** The one unit sentence every money field carries, for the model and for people. Verbatim. */
 export declare const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
 /** JSON Schema keyword marking a money field. Verbatim. */
@@ -93,5 +90,4 @@ export declare const STORAGE_UNIT_SENTENCE = "Store API amounts are storage unit
 export declare const RATE_UNIT_SENTENCE = "1 unit of the store currency equals this many units of the other currency.";
 /** A money field's description: `describe` (trimmed) followed by the unit sentence, or the sentence alone. */
 export declare function moneyFieldDescription(describe?: string): string;
-//#endregion
 export type { MoneyMention, MoneyView, ParseModelMoneyOptions, ParseModelMoneyResult };

package/dist/ai.js

@@ -1,8 +1,8 @@
-import { $ as describeValue, E as resolveCurrency, Q as MoneyError, l as toMajorNumber, m as currencyMarks, n as fromMajor, pt as toDecimalText, s as storedDecimal, u as CURRENCIES } from "./money-WhnGiI00.js";
-import { t as formatMoney } from "./format-BdPnijvn.js";
-import { n as readNumberText, t as digitGroupingSource } from "./number-text-DE-q4jO5.js";
-import { s as parseAmountInput } from "./amount-BoYBMgK9.js";
-//#region src/ai/mentions.ts
+import { $ as describeValue, E as resolveCurrency, Q as MoneyError, l as toMajorNumber, m as currencyMarks, n as fromMajor, pt as toDecimalText, s as storedDecimal, u as CURRENCIES } from "./money-BxbAw7BP.js";
+import { t as formatMoney } from "./format-BJC513u4.js";
+import { n as readNumberText, t as digitGroupingSource } from "./number-text-Bj-gZXiF.js";
+import { s as parseAmountInput } from "./amount-off8IMBJ.js";
+// src/ai/mentions.ts
 const ACTIVE = CURRENCIES.filter((c) => c.status === "active");
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 const LETTER_START = /^\p{L}/u;
@@ -83,8 +83,7 @@ function moneyMentions(text, options = {}) {
 	}
 	return mentions;
 }
-//#endregion
-//#region src/ai/wording.ts
+// src/ai/wording.ts
 /** The one unit sentence every money field carries, for the model and for people. Verbatim. */
 const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
 /** JSON Schema keyword marking a money field. Verbatim. */
@@ -98,8 +97,7 @@ function moneyFieldDescription(describe) {
 	const lead = typeof describe === "string" ? describe.trim() : "";
 	return lead ? `${lead} ${MONEY_UNIT_SENTENCE}` : MONEY_UNIT_SENTENCE;
 }
-//#endregion
-//#region src/ai/model-money.ts
+// src/ai/model-money.ts
 /**
 * `{ amount: 19.99, currency: 'USD', display: '$19.99' }`. `amount` is exact; `display` shows the
 * display digits, widened to keep a stored value finer than them (JPY 550 is `'¥5.5'`, HUF 435050
@@ -125,7 +123,7 @@ function failure(reason, input, code, digits) {
 		error: `${{
 			empty: `Not an amount: ${shown}.`,
 			unparseable: `Not an amount: ${shown}.`,
-			too_many_decimals: `${shown} has more decimal places than ${code} uses (at most ${digits}).`,
+			too_many_decimals: digits === 0 ? `${shown} has more decimal places than ${code} uses (at most 0). Write thousands with ',' or without a separator (1,500 or 1500).` : `${shown} has more decimal places than ${code} uses (at most ${digits}).`,
 			negative: "The amount must not be negative.",
 			zero: "The amount must be more than zero.",
 			below_min: `${shown} is out of range for ${code}.`,
@@ -147,8 +145,10 @@ function fromNumber(input, currency, options) {
 * An amount from a model tool call (major units, as the merchant says it) as Money, or an
 * error to send back to the model ending with `MONEY_UNIT_SENTENCE`. Numbers go through
 * `fromMajor` (float noise such as 0.1 + 0.2 allowed); strings through `/input`'s entry rule
-* in English (`'1,299.00'`, `'$1,299'`, `'99.000'` VND, `'1.500'` JPY). More fraction digits
-* than the currency stores and negative amounts are refused, never rounded or flipped. An
+* in English (`'1,299.00'`, `'$1,299'`, `'99,000'` VND). More fraction digits than the
+* currency stores and negative amounts are refused, never rounded or flipped; so is a `.` before
+* three digits in a currency without decimals (`'99.000'` VND, `'1.500'` JPY: a thousands group
+* or a fraction?), and the error asks the model for `1,500` or `1500`. An
 * unknown currency throws `currency_invalid` (it is the tool's, not the model's).
 */
 function parseModelMoney(input, currency, options = {}) {
@@ -171,5 +171,4 @@ function parseModelMoney(input, currency, options = {}) {
 		money: result.money
 	} : failure(result.reason, input, info.code, info.storageDigits);
 }
-//#endregion
 export { MONEY_META_KEY, MONEY_UNIT_SENTENCE, RATE_UNIT_SENTENCE, STORAGE_UNIT_SENTENCE, currencySymbolAliases, moneyFieldDescription, moneyLiteralPattern, moneyMentions, moneyView, parseModelMoney };

package/dist/{allocate-CZRg4TOP.cjs → allocate-AusholrC.cjs}

@@ -1,6 +1,6 @@
-const require_money = require("./money-B3wH_Z4S.cjs");
-const require_rounding = require("./rounding-DHBtNCHG.cjs");
-//#region src/allocate.ts
+const require_money = require("./money-DWBjuuEK.cjs");
+const require_rounding = require("./rounding-4QKTRbMQ.cjs");
+// src/allocate.ts
 const invalid = (message) => new require_money.MoneyError("amount_invalid", message);
 const sumOf = (values) => values.reduce((a, b) => a + b, 0n);
 const floorShares = (units, weights, total) => weights.map((w) => require_money.divRound(units * w, total, "floor"));
@@ -195,7 +195,6 @@ function splitUnitPrice(net, quantity, options = {}) {
 	});
 	return parts;
 }
-//#endregion
 Object.defineProperty(exports, "allocate", {
 	enumerable: true,
 	get: function() {

package/dist/{allocate-X7_jAtOj.js → allocate-BBRfdaSC.js}

@@ -1,6 +1,6 @@
-import { $ as describeValue, B as decimalOf, Q as MoneyError, X as mulDiv, at as fractionDigitsOf, dt as roundToScale, pt as toDecimalText, rt as divRound, s as storedDecimal, t as boundedMoney } from "./money-WhnGiI00.js";
-import { a as unitSize } from "./rounding-g9rvye0k.js";
-//#region src/allocate.ts
+import { $ as describeValue, B as decimalOf, Q as MoneyError, X as mulDiv, at as fractionDigitsOf, dt as roundToScale, pt as toDecimalText, rt as divRound, s as storedDecimal, t as boundedMoney } from "./money-BxbAw7BP.js";
+import { a as unitSize } from "./rounding-CA1PVP3b.js";
+// src/allocate.ts
 const invalid = (message) => new MoneyError("amount_invalid", message);
 const sumOf = (values) => values.reduce((a, b) => a + b, 0n);
 const floorShares = (units, weights, total) => weights.map((w) => divRound(units * w, total, "floor"));
@@ -195,5 +195,4 @@ function splitUnitPrice(net, quantity, options = {}) {
 	});
 	return parts;
 }
-//#endregion
 export { splitUnitPrice as i, allocateUnits as n, allocateWaterfall as r, allocate as t };

package/dist/{amount-BV0O-aN8.cjs → amount-Bzxw9aD4.cjs}

@@ -1,7 +1,7 @@
-const require_money = require("./money-B3wH_Z4S.cjs");
-const require_arithmetic = require("./arithmetic-DjT4Kzgt.cjs");
-const require_number_text = require("./number-text-BWu67jUq.cjs");
-//#region src/input/amount.ts
+const require_money = require("./money-DWBjuuEK.cjs");
+const require_arithmetic = require("./arithmetic-D8A6IeZ0.cjs");
+const require_number_text = require("./number-text-CWuVwrlg.cjs");
+// src/input/amount.ts
 /** Internal: the exact signed decimal a successful separator-engine read holds. */
 function decimalOfText(read) {
 	return {
@@ -69,6 +69,15 @@ function echoesOriginal(shown, options) {
 		grouped: true
 	});
 }
+/**
+* In a currency storing 0 digits, the locale's decimal separator before exactly three digits
+* after a whole part of at most three (en-US `'1.234'`, `'19.999'`, `'1.000'` JPY) reads as a
+* thousands group to some people and as a fraction to others; trailing zeros would even let
+* `'1.000'` through as 1 yen. Neither reading is safe, so a locale field refuses it.
+*/
+function readsAsGroupOrFraction(read, info) {
+	return info.storageDigits === 0 && read.decimalMark !== null && read.scale === 3 && read.units < 1000000n;
+}
 /** Which reading a field's options ask for; `decimalSeparator` and `locale` together, or a `decimalSeparator` other than `'.'`, throw. */
 function entryMode(options) {
 	if (options.decimalSeparator === void 0) return options.locale === void 0 ? "auto" : "locale";
@@ -92,17 +101,19 @@ const ENTRY_SEPARATORS = {
 *   against `,` (see `parseImportAmount`): `'29,99'` EUR is 29.99, `'1.299,00'` and `'1,299'`
 *   are 1299, KWD `'1,5'` is 1.5; a currency storing 0 digits rounds a fraction half-up to a
 *   whole unit (`'1200.5'` JPY is 1201).
-* - With `locale`: its decimal separator is the decimal and its group separator is valid only in
-*   3-digit (or Indian lakh) groups; in a currency that stores no fraction (JPY, VND) a separator
-*   before exactly three digits in grouping position is grouping (`'1.500'` JPY is 1500).
-*   en-US `'29,99'` USD is `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY
-*   is `'too_many_decimals'`.
+* - With `locale`: its decimal separator is always the decimal and its group separator is valid
+*   only in 3-digit (or Indian lakh) groups. In a currency that stores no fraction (JPY, VND) the
+*   decimal separator before exactly three digits is ambiguous (en-US `'1.234'` JPY could be
+*   1,234 or 1.234) and is `'too_many_decimals'`, never read as grouping; grouping takes the
+*   locale's group separator (`'1,234'` en-US, `'1.234'` de-DE). en-US `'29,99'` USD is
+*   `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY is `'too_many_decimals'`.
 * - With `decimalSeparator: '.'` (every `<input type="number">`): `.` is the decimal, nothing
 *   groups (`'1,299'` is `'unparseable'`), TND and IQD `'1.500'` are 1.5, and a currency storing
-*   0 digits rounds a fraction half-up to a whole unit (`'1.5'` JPY is 2).
+*   0 digits refuses any fraction as `'too_many_decimals'` (`'1.5'` JPY), never rounded;
+*   trailing zeros read as whole (`'1.0'` JPY is 1).
 * Otherwise more fraction digits than the currency stores is `'too_many_decimals'`, never rounded
 * (`'1,2345'` USD). Text equal to `original` returns it unchanged (JPY 120050 shown as
-* `'1200.50'`). An unknown currency, or an `original` in another currency, throws.
+* `'1200.50'`), except the ambiguous zero-digit text above. An unknown currency, or an `original` in another currency, throws.
 */
 function parseAmountInput(text, currency, options = {}) {
 	const info = require_money.resolveCurrency(currency, { allowHistoric: true });
@@ -112,7 +123,10 @@ function parseAmountInput(text, currency, options = {}) {
 	let value;
 	if (echoesOriginal(shown, options)) value = require_money.storedDecimal(options.original).value;
 	else {
-		const separators = mode === "locale" ? localeSeparators(options.locale) : ENTRY_SEPARATORS[mode];
+		const separators = mode === "locale" ? {
+			...localeSeparators(options.locale),
+			wholeCurrencyGrouping: false
+		} : ENTRY_SEPARATORS[mode];
 		const read = require_number_text.readNumberText(text, {
 			...separators,
 			currency: info.code
@@ -122,11 +136,16 @@ function parseAmountInput(text, currency, options = {}) {
 			reason: read.reason,
 			text: shown
 		};
+		if (mode === "locale" && readsAsGroupOrFraction(read, info)) return {
+			ok: false,
+			reason: "too_many_decimals",
+			text: shown
+		};
 		value = decimalOfText(read);
 	}
 	const result = entryMoney(value, info, {
 		...options,
-		roundExtraDigits: mode !== "locale" && info.storageDigits === 0
+		roundExtraDigits: mode === "auto" && info.storageDigits === 0
 	});
 	if (!result.ok) return {
 		ok: false,
@@ -196,7 +215,6 @@ function inputStep(currency) {
 function inputPlaceholder(currency) {
 	return PLACEHOLDERS[require_money.resolveCurrency(currency, { allowHistoric: true }).storageDigits];
 }
-//#endregion
 Object.defineProperty(exports, "decimalOfText", {
 	enumerable: true,
 	get: function() {

package/dist/{amount-BoYBMgK9.js → amount-off8IMBJ.js}

@@ -1,7 +1,7 @@
-import { E as resolveCurrency, M as resolveLocale, N as separatorsOf, Q as MoneyError, at as fractionDigitsOf, c as toMajorDecimal, it as formatDecimal, n as fromMajor, q as trimDecimalZeros, s as storedDecimal, tt as compareDecimal } from "./money-WhnGiI00.js";
-import { r as compare } from "./arithmetic-BhNwisjb.js";
-import { n as readNumberText } from "./number-text-DE-q4jO5.js";
-//#region src/input/amount.ts
+import { E as resolveCurrency, M as resolveLocale, N as separatorsOf, Q as MoneyError, at as fractionDigitsOf, c as toMajorDecimal, it as formatDecimal, n as fromMajor, q as trimDecimalZeros, s as storedDecimal, tt as compareDecimal } from "./money-BxbAw7BP.js";
+import { r as compare } from "./arithmetic-C97-YafD.js";
+import { n as readNumberText } from "./number-text-Bj-gZXiF.js";
+// src/input/amount.ts
 /** Internal: the exact signed decimal a successful separator-engine read holds. */
 function decimalOfText(read) {
 	return {
@@ -69,6 +69,15 @@ function echoesOriginal(shown, options) {
 		grouped: true
 	});
 }
+/**
+* In a currency storing 0 digits, the locale's decimal separator before exactly three digits
+* after a whole part of at most three (en-US `'1.234'`, `'19.999'`, `'1.000'` JPY) reads as a
+* thousands group to some people and as a fraction to others; trailing zeros would even let
+* `'1.000'` through as 1 yen. Neither reading is safe, so a locale field refuses it.
+*/
+function readsAsGroupOrFraction(read, info) {
+	return info.storageDigits === 0 && read.decimalMark !== null && read.scale === 3 && read.units < 1000000n;
+}
 /** Which reading a field's options ask for; `decimalSeparator` and `locale` together, or a `decimalSeparator` other than `'.'`, throw. */
 function entryMode(options) {
 	if (options.decimalSeparator === void 0) return options.locale === void 0 ? "auto" : "locale";
@@ -92,17 +101,19 @@ const ENTRY_SEPARATORS = {
 *   against `,` (see `parseImportAmount`): `'29,99'` EUR is 29.99, `'1.299,00'` and `'1,299'`
 *   are 1299, KWD `'1,5'` is 1.5; a currency storing 0 digits rounds a fraction half-up to a
 *   whole unit (`'1200.5'` JPY is 1201).
-* - With `locale`: its decimal separator is the decimal and its group separator is valid only in
-*   3-digit (or Indian lakh) groups; in a currency that stores no fraction (JPY, VND) a separator
-*   before exactly three digits in grouping position is grouping (`'1.500'` JPY is 1500).
-*   en-US `'29,99'` USD is `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY
-*   is `'too_many_decimals'`.
+* - With `locale`: its decimal separator is always the decimal and its group separator is valid
+*   only in 3-digit (or Indian lakh) groups. In a currency that stores no fraction (JPY, VND) the
+*   decimal separator before exactly three digits is ambiguous (en-US `'1.234'` JPY could be
+*   1,234 or 1.234) and is `'too_many_decimals'`, never read as grouping; grouping takes the
+*   locale's group separator (`'1,234'` en-US, `'1.234'` de-DE). en-US `'29,99'` USD is
+*   `'unparseable'`; de-DE `'29,99'` EUR is 29.99; en-US `'1200.5'` JPY is `'too_many_decimals'`.
 * - With `decimalSeparator: '.'` (every `<input type="number">`): `.` is the decimal, nothing
 *   groups (`'1,299'` is `'unparseable'`), TND and IQD `'1.500'` are 1.5, and a currency storing
-*   0 digits rounds a fraction half-up to a whole unit (`'1.5'` JPY is 2).
+*   0 digits refuses any fraction as `'too_many_decimals'` (`'1.5'` JPY), never rounded;
+*   trailing zeros read as whole (`'1.0'` JPY is 1).
 * Otherwise more fraction digits than the currency stores is `'too_many_decimals'`, never rounded
 * (`'1,2345'` USD). Text equal to `original` returns it unchanged (JPY 120050 shown as
-* `'1200.50'`). An unknown currency, or an `original` in another currency, throws.
+* `'1200.50'`), except the ambiguous zero-digit text above. An unknown currency, or an `original` in another currency, throws.
 */
 function parseAmountInput(text, currency, options = {}) {
 	const info = resolveCurrency(currency, { allowHistoric: true });
@@ -112,7 +123,10 @@ function parseAmountInput(text, currency, options = {}) {
 	let value;
 	if (echoesOriginal(shown, options)) value = storedDecimal(options.original).value;
 	else {
-		const separators = mode === "locale" ? localeSeparators(options.locale) : ENTRY_SEPARATORS[mode];
+		const separators = mode === "locale" ? {
+			...localeSeparators(options.locale),
+			wholeCurrencyGrouping: false
+		} : ENTRY_SEPARATORS[mode];
 		const read = readNumberText(text, {
 			...separators,
 			currency: info.code
@@ -122,11 +136,16 @@ function parseAmountInput(text, currency, options = {}) {
 			reason: read.reason,
 			text: shown
 		};
+		if (mode === "locale" && readsAsGroupOrFraction(read, info)) return {
+			ok: false,
+			reason: "too_many_decimals",
+			text: shown
+		};
 		value = decimalOfText(read);
 	}
 	const result = entryMoney(value, info, {
 		...options,
-		roundExtraDigits: mode !== "locale" && info.storageDigits === 0
+		roundExtraDigits: mode === "auto" && info.storageDigits === 0
 	});
 	if (!result.ok) return {
 		ok: false,
@@ -196,5 +215,4 @@ function inputStep(currency) {
 function inputPlaceholder(currency) {
 	return PLACEHOLDERS[resolveCurrency(currency, { allowHistoric: true }).storageDigits];
 }
-//#endregion
 export { inputStep as a, inputPlaceholder as i, formatAmountInput as n, localeSeparators as o, groupDigits as r, parseAmountInput as s, decimalOfText as t };

package/dist/{arithmetic-BhNwisjb.js → arithmetic-C97-YafD.js}

@@ -1,7 +1,7 @@
-import { $ as describeValue, B as decimalOf, E as resolveCurrency, Q as MoneyError, ot as isPositiveDecimal, s as storedDecimal, t as boundedMoney, ut as pow10 } from "./money-WhnGiI00.js";
-import { t as mulDivToUnit } from "./rounding-g9rvye0k.js";
-import { n as hundredPercent } from "./percent-D1VB9xXG.js";
-//#region src/arithmetic.ts
+import { $ as describeValue, B as decimalOf, E as resolveCurrency, Q as MoneyError, ot as isPositiveDecimal, s as storedDecimal, t as boundedMoney, ut as pow10 } from "./money-BxbAw7BP.js";
+import { t as mulDivToUnit } from "./rounding-CA1PVP3b.js";
+import { n as hundredPercent } from "./percent-CB3Ixjc_.js";
+// src/arithmetic.ts
 /** Internal: the shared currency of `a` and `b` and their stored integers. Throws `currency_mismatch`. */
 function pair(a, b, verb) {
 	const left = storedDecimal(a).info;
@@ -128,5 +128,4 @@ function excessOver(a, b, tolerance) {
 	const delta = x - y;
 	return boundedMoney(delta < limit ? 0n : delta, info);
 }
-//#endregion
 export { within as _, equals as a, isPositive as c, min as d, multiply as f, sum as g, subtract as h, divide as i, isZero as l, remaining as m, clamp as n, excessOver as o, percentOf as p, compare as r, isNegative as s, add as t, max as u };

package/dist/{arithmetic-DjT4Kzgt.cjs → arithmetic-D8A6IeZ0.cjs}

@@ -1,7 +1,7 @@
-const require_money = require("./money-B3wH_Z4S.cjs");
-const require_rounding = require("./rounding-DHBtNCHG.cjs");
-const require_percent = require("./percent-C0InC2t2.cjs");
-//#region src/arithmetic.ts
+const require_money = require("./money-DWBjuuEK.cjs");
+const require_rounding = require("./rounding-4QKTRbMQ.cjs");
+const require_percent = require("./percent-DABHiSBs.cjs");
+// src/arithmetic.ts
 /** Internal: the shared currency of `a` and `b` and their stored integers. Throws `currency_mismatch`. */
 function pair(a, b, verb) {
 	const left = require_money.storedDecimal(a).info;
@@ -128,7 +128,6 @@ function excessOver(a, b, tolerance) {
 	const delta = x - y;
 	return require_money.boundedMoney(delta < limit ? 0n : delta, info);
 }
-//#endregion
 Object.defineProperty(exports, "add", {
 	enumerable: true,
 	get: function() {

package/dist/billing.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_money = require("./money-B3wH_Z4S.cjs");
-const require_percent = require("./percent-C0InC2t2.cjs");
-//#region src/billing/credits.ts
+const require_money = require("./money-DWBjuuEK.cjs");
+const require_percent = require("./percent-DABHiSBs.cjs");
+// src/billing/credits.ts
 function wholeNumber(value, name, min) {
 	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min) throw new require_money.MoneyError("amount_invalid", `${name} must be an integer >= ${min}, got ${require_money.describeValue(value)}`);
 	return BigInt(value);
@@ -64,8 +64,7 @@ function bucketCredits(credits, step = 50) {
 	const s = wholeNumber(step, "step", 1);
 	return Number(require_money.divRound(c, s, "ceil") * s);
 }
-//#endregion
-//#region src/billing/plans.ts
+// src/billing/plans.ts
 function checkSame(m, other, verb) {
 	const info = require_money.storedDecimal(m).info;
 	const own = require_money.storedDecimal(other).info;
@@ -144,8 +143,7 @@ function grossUpForPercentOffs(m, percents) {
 	if (!(kept > 0)) return m;
 	return require_money.boundedMoney(BigInt(Math.round(m.amount / kept)), info);
 }
-//#endregion
-//#region src/billing/usage.ts
+// src/billing/usage.ts
 const USD_DIGITS = 6;
 /**
 * The exact sum of `quantity x rate x multiplier` over `lines`, rounded half-up once to 6
@@ -172,7 +170,6 @@ function usdCost(lines) {
 	}
 	return require_money.toDecimalText(require_money.roundToScale(total, USD_DIGITS, "half-up"));
 }
-//#endregion
 exports.annualPrice = annualPrice;
 exports.applyCoupons = applyCoupons;
 exports.bucketCredits = bucketCredits;