@stacksjs/commerce 0.75.38 → 0.75.40

package/dist/money.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Decimal places of a currency's minor unit (USD 2, JPY 0, KWD 3).
+ *
+ * Read from `Intl`, which carries the ISO 4217 table, so there is no list here
+ * to fall out of date. Unknown or missing codes are treated as 2 decimals, the
+ * overwhelmingly common case.
+ */
+export declare function currencyExponent(currency: string | null | undefined): number;
+/**
+ * A decimal price string as integer minor units.
+ *
+ * Accepts plain decimals only: `"19.99"`, `"0.10"`, `"1999"`, `"19.9"`, `".5"`.
+ * Rejects thousands separators (`"1,000.00"`), signs, exponents and anything
+ * else, because each is ambiguous in some locale (`"1,000"` is one in German).
+ * Digits past the currency's precision round half up, which only arises when a
+ * store is configured with more decimals than its currency has.
+ *
+ * @returns The amount in minor units, or null for an empty value (unpriced).
+ */
+export declare function decimalToMinor(value: string | number | null | undefined, exponent?: number): number | null;
+/** Integer minor units back to a decimal string, e.g. `1999, 2 -> "19.99"`. */
+export declare function minorToDecimal(minor: number | bigint | string, exponent?: number): string;
+/**
+ * Minor units at one precision as minor units at another.
+ *
+ * WooCommerce reports `prices.price` at the store's configured decimals
+ * (`currency_minor_unit`). A USD store set to 0 decimals sends `"20"` for
+ * $20.00, which must become 2000 cents, not 20.
+ */
+export declare function rescaleMinor(amount: string | number | null | undefined, fromExponent: number, toExponent: number): number | null;
+/** `1999, 'USD' -> "19.99 USD"`, for reports and exports. Never used for storage. */
+export declare function formatMinor(minor: number, currency: string | null): string;
+/**
+ * A stored minor-unit amount as major units, for `Intl.NumberFormat` and
+ * charts. `1999, 'USD' -> 19.99`, `1999, 'JPY' -> 1999`, `1999, 'KWD' -> 1.999`.
+ *
+ * Display only: the result is a float, so never store it or add it up.
+ * A non-integer input is rounded to the nearest minor unit first, which is
+ * what a legacy row holding a fraction of a cent would have meant.
+ */
+export declare function minorToMajor(minor: number | string | null | undefined, currency: string | null | undefined): number;
+/**
+ * A stored minor-unit amount, formatted for people.
+ *
+ * `formatCurrency(1999, 'USD', 'en-US')` is `"$19.99"`; `(1999, 'JPY', 'en-US')`
+ * is `"¥1,999"`. The locale defaults to the runtime's (the viewer's browser in
+ * the dashboard). A currency code `Intl` does not know falls back to the
+ * report form, `"19.99 XYZ"`, rather than throwing out of a table render.
+ */
+export declare function formatCurrency(minor: number | string | null | undefined, currency: string | null | undefined, locale?: string): string;
+/**
+ * A stored minor-unit amount as the decimal string an input field shows,
+ * e.g. `1999, 'USD' -> "19.99"`. The inverse of `parseMoneyInput`.
+ */
+export declare function minorToInput(minor: number | string | null | undefined, currency: string | null | undefined): string;
+/** The `step` attribute for a money input: `"0.01"` for USD, `"1"` for JPY. */
+export declare function moneyInputStep(currency: string | null | undefined): string;
+/**
+ * Why `input` is not an acceptable amount of `currency`, or `''` when it is.
+ *
+ * For forms: the dashboard disables Save and shows this next to the field.
+ * Stricter than `decimalToMinor` on purpose: a person typing `19.999` for a
+ * USD price has made a mistake, and rounding it silently would hide that.
+ */
+export declare function moneyInputError(input: string | number | null | undefined, currency: string | null | undefined, options?: MoneyInputOptions): string;
+/**
+ * A money field's value as integer minor units: `"19.99"` in USD is `1999`.
+ *
+ * Throws `PriceFormatError` with the same message `moneyInputError` gives, so
+ * a caller that skipped validation still cannot store a float. Returns null
+ * only for an empty, optional field.
+ */
+export declare function parseMoneyInput(input: string | number | null | undefined, currency: string | null | undefined, options?: MoneyInputOptions & { required?: true }): number;
+export declare function parseMoneyInput(input: string | number | null | undefined, currency: string | null | undefined, options: MoneyInputOptions & { required: false }): number | null;
+export declare interface MoneyInputOptions {
+  min?: number
+  max?: number
+  required?: boolean
+}
+/**
+ * Money, at every boundary it crosses.
+ *
+ * Every amount Stacks commerce stores is an integer in the currency's MINOR
+ * unit: cents for USD, whole yen for JPY, fils for KWD. `products.price`,
+ * `order_items.price`, `orders.total_amount`, `payments.amount` and the rest
+ * hold that integer, and arithmetic (order totals, refunds) happens on it.
+ *
+ * Conversion happens only where a human or a foreign system is on the other
+ * side, and only through this module:
+ *
+ * - display: `formatCurrency(1999, 'USD')` is `"$19.99"`
+ * - input: `parseMoneyInput('19.99', 'USD')` is `1999`
+ * - reports: `formatMinor(1999, 'USD')` is `"19.99 USD"`
+ * - import: `decimalToMinor('19.99')` and `rescaleMinor(...)`
+ *
+ * Decimal strings are converted with string and BigInt arithmetic, never
+ * through a float: `Math.round(19.99 * 100)` happens to be right,
+ * `Math.round(1.005 * 100)` is 100 rather than 101.
+ *
+ * The module has no imports, so it is safe to bundle into the browser. The
+ * dashboard reaches it as `@stacksjs/commerce/money`; server code can use the
+ * `@stacksjs/commerce` barrel.
+ */
+export declare class PriceFormatError extends Error {
+  public readonly value: unknown;
+  constructor(value: unknown, reason: string);
+}

package/dist/money.js

@@ -0,0 +1,2 @@
+// @bun
+var p=Object.defineProperty;var b=(n)=>n;function h(n,e){this[n]=b.bind(null,e)}var x=(n,e)=>{for(var t in e)p(n,t,{get:e[t],enumerable:!0,configurable:!0,set:h.bind(e,t)})};var O=(n,e,t)=>()=>{if(n)try{e=n(n=0)}catch(r){t=[r]}if(t)throw t[0];return e};var S={};x(S,{PriceFormatError:()=>l,currencyExponent:()=>s,decimalToMinor:()=>m,formatCurrency:()=>y,formatMinor:()=>c,minorToDecimal:()=>a,minorToInput:()=>M,minorToMajor:()=>f,moneyInputError:()=>g,moneyInputStep:()=>I,parseMoneyInput:()=>N,rescaleMinor:()=>w});class l extends Error{value;constructor(n,e){super(`Unreadable price ${JSON.stringify(n)}: ${e}`);this.value=n;this.name="PriceFormatError"}}function s(n){if(!n)return 2;try{let e=new Intl.NumberFormat("en",{style:"currency",currency:n}).resolvedOptions().maximumFractionDigits;return typeof e==="number"?e:2}catch{return 2}}function m(n,e=2){if(n===null||n===void 0)return null;let t=String(n).trim();if(t==="")return null;let r=/^(\d*)(?:\.(\d*))?$/.exec(t);if(!r||!/\d/.test(t))throw new l(n,"expected a plain decimal such as 19.99");let u=r[1]||"0",i=r[2]??"",o;if(i.length<=e)o=BigInt(u+i.padEnd(e,"0"));else if(o=BigInt(u+i.slice(0,e)),i.charCodeAt(e)>=53)o+=1n;if(o>BigInt(Number.MAX_SAFE_INTEGER))throw new l(n,"too large to store exactly");return Number(o)}function a(n,e=2){let t=String(n).trim();if(!/^\d+$/.test(t))throw new l(n,"expected a non-negative integer amount in minor units");if(e===0)return t.replace(/^0+(?=\d)/,"");let r=t.padStart(e+1,"0");return`${r.slice(0,-e).replace(/^0+(?=\d)/,"")}.${r.slice(-e)}`}function w(n,e,t){if(n===null||n===void 0||String(n).trim()==="")return null;if(!Number.isInteger(e)||e<0)throw new l(n,`invalid source precision ${e}`);return m(a(String(n),e),t)}function c(n,e){let t=s(e),r=Math.round(Number(n)),u=Number.isSafeInteger(r)?`${r<0?"-":""}${a(Math.abs(r),t)}`:String(n);return e?`${u} ${e}`:u}function f(n,e){let t=Math.round(Number(n??0));if(!Number.isFinite(t))return 0;let r=a(Math.abs(t),s(e));return t<0?-Number(r):Number(r)}function y(n,e,t){let r=(e||"USD").toUpperCase(),u=f(n,r);try{return new Intl.NumberFormat(t,{style:"currency",currency:r}).format(u)}catch{return c(Math.round(Number(n??0))||0,r)}}function M(n,e){if(n===null||n===void 0||n==="")return"";let t=Math.round(Number(n));if(!Number.isFinite(t))return"";let r=a(Math.abs(t),s(e));return t<0?`-${r}`:r}function I(n){let e=s(n);return e===0?"1":`0.${"1".padStart(e,"0")}`}function g(n,e,t={}){let r=n===null||n===void 0?"":String(n).trim(),u=s(e),i=(e||"USD").toUpperCase();if(r==="")return t.required===!1?"":"Enter an amount.";let o=/^(\d*)(?:\.(\d*))?$/.exec(r);if(!o||!/\d/.test(r))return u===0?"Enter a whole number, for example 1999.":`Enter a plain amount, for example ${a(1999,u)}.`;if((o[2]??"").length>u)return u===0?`${i} amounts have no decimal places.`:`${i} amounts have at most ${u} decimal ${u===1?"place":"places"}.`;let d;try{d=m(r,u)}catch{return"That amount is too large."}if(d===null)return"Enter an amount.";if(t.min!==void 0&&d<t.min)return`Enter at least ${c(t.min,i)}.`;if(t.max!==void 0&&d>t.max)return`Enter at most ${c(t.max,i)}.`;return""}function N(n,e,t={}){let r=g(n,e,t);if(r)throw new l(n,r);return m(n,s(e))}export{l as PriceFormatError,s as currencyExponent,m as decimalToMinor,y as formatCurrency,c as formatMinor,a as minorToDecimal,M as minorToInput,f as minorToMajor,g as moneyInputError,I as moneyInputStep,N as parseMoneyInput,w as rescaleMinor};

package/dist/orders/export.d.ts

@@ -1,3 +1,4 @@
+import type { OrderWithTotals } from '../types';
 import type { SpreadsheetWrapper } from 'ts-spreadsheets';
 /**
  * Export orders to a spreadsheet
@@ -5,6 +6,29 @@ import type { SpreadsheetWrapper } from 'ts-spreadsheets';
  * @returns Spreadsheet object ready for download or storage
  */
 export declare function exportOrders(format?: 'csv' | 'excel'): Promise<SpreadsheetWrapper>;
+/**
+ * Every order with its customer and its line items (each with its product),
+ * ready for `prepareOrdersForExport`.
+ *
+ * Four flat queries, whatever the number of orders: the orders, then the
+ * customers, line items and products they reference, each read with `IN` and
+ * stitched together in memory. Nothing is fetched per order.
+ *
+ * The orders are read on their own rather than joined to customers: a
+ * `SELECT *` across that join returns two `id` columns, and the customer's
+ * silently replaces the order's in the row object.
+ */
+export declare function fetchOrdersForExport(): Promise<OrderWithTotals[]>;
+/**
+ * Prepare orders data for spreadsheet export
+ *
+ * Amounts are stored as integer minor units, so `total_amount: 1999` in USD is
+ * written as `19.99 USD`, never as `1999` or `$1999` (stacksjs/stacks#2851).
+ *
+ * @param orders Array of order objects
+ * @returns Spreadsheet data structure
+ */
+export declare function prepareOrdersForExport(orders: OrderWithTotals[]): { headings: (keyof ExportedOrder)[], data: (string | number)[][] };
 /**
  * Export orders and automatically download
  * @param format The format of the spreadsheet (default is CSV)
@@ -26,7 +50,7 @@ export declare interface ExportedOrder {
   'Order ID': number
   'Customer': string
   'Date': string
-  'Total': number
+  'Total': string
   'Status': string
   'Items': string
 }

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@stacksjs/commerce",
   "type": "module",
-  "sideEffects": false,
-  "version": "0.75.38",
+  "version": "0.75.40",
   "description": "Stacks commerce utilities.",
   "author": "Chris Breuer",
   "contributors": [
@@ -58,17 +57,17 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/cache": "0.75.38",
-    "@stacksjs/config": "0.75.38",
-    "@stacksjs/database": "0.75.38",
-    "@stacksjs/env": "0.75.38",
-    "@stacksjs/error-handling": "0.75.38",
-    "@stacksjs/events": "0.75.38",
-    "@stacksjs/logging": "0.75.38",
-    "@stacksjs/orm": "0.75.38",
-    "@stacksjs/payments": "0.75.38",
-    "@stacksjs/realtime": "0.75.38",
-    "@stacksjs/strings": "0.75.38",
+    "@stacksjs/cache": "0.75.40",
+    "@stacksjs/config": "0.75.40",
+    "@stacksjs/database": "0.75.40",
+    "@stacksjs/env": "0.75.40",
+    "@stacksjs/error-handling": "0.75.40",
+    "@stacksjs/events": "0.75.40",
+    "@stacksjs/logging": "0.75.40",
+    "@stacksjs/orm": "0.75.40",
+    "@stacksjs/payments": "0.75.40",
+    "@stacksjs/realtime": "0.75.40",
+    "@stacksjs/strings": "0.75.40",
     "ts-spreadsheets": "^0.2.0"
   },
   "devDependencies": {