@stacksjs/commerce 0.75.89 → 0.75.91

package/dist/register.d.ts

@@ -0,0 +1,63 @@
+/** Units still on the shelf once the basket is taken off it; null when stock is not counted. */
+export declare function shelfLeft(product: Product, basket: BasketLine[], fields?: RegisterFields): number | null;
+/** Whether one more can be rung up. */
+export declare function canAdd(product: Product, basket: BasketLine[], fields?: RegisterFields): boolean;
+/** One more of a product, when there is one to sell; the basket unchanged otherwise. */
+export declare function addToBasket(basket: BasketLine[], product: Product, fields?: RegisterFields): BasketLine[];
+/** A line's quantity, held to the stock on hand; zero (or less) takes the line off. */
+export declare function setQuantity(basket: BasketLine[], product: Product, quantity: number, fields?: RegisterFields): BasketLine[];
+/** The basket's lines with their products, leaving out any no longer in the catalog. */
+export declare function basketLines<T extends Product>(basket: BasketLine[], products: T[], fields?: RegisterFields): Array<BasketLine & { product: T }>;
+/** The basket's total, in minor units. */
+export declare function basketTotal(basket: BasketLine[], products: Product[], fields?: RegisterFields): number;
+/**
+ * The part of the basket's total that sales tax applies to: every line whose
+ * product is not marked `taxable: false` (a food product, an admission).
+ * Feed it to `breakdownFor` from `@stacksjs/commerce/sales-tax`.
+ */
+export declare function basketTaxable(basket: BasketLine[], products: Product[], fields?: RegisterFields): number;
+/** How many units are in the basket. */
+export declare function basketCount(basket: BasketLine[]): number;
+/**
+ * How a product's stock reads on the register: sold out, running low (at or
+ * under its own reorder level, `defaultLow` when it has none), or how many
+ * are left. Null when stock is not counted.
+ */
+export declare function stockLabel(product: Product, basket?: BasketLine[], fields?: RegisterFields, defaultLow?: number): StockLabel | null;
+/** The distinct values of a grouping (a shelf, a category), in the order the products come. */
+export declare function groupsOf<T>(products: T[], groupOf: (product: T) => string): string[];
+export declare const DEFAULT_FIELDS: RegisterFields;
+/** Field names for a catalog stored with `price_cents` and `inventory_quantity`. */
+export declare const CENTS_FIELDS: RegisterFields;
+/**
+ * A point-of-sale register's basket: what is being rung up, held against what
+ * is on the shelf, before anything is written. Pure and dependency-free, so
+ * the browser bundles it (`@stacksjs/commerce/register`) and a server can
+ * check the same rules.
+ *
+ * A product is anything with an `id`, a `price` in minor units and, when its
+ * stock is counted, an `inventory` (null or absent: not counted, never runs
+ * out). Field names follow the caller: pass `fields` when a catalog stores
+ * them as, say, `price_cents` and `inventory_quantity`.
+ *
+ * ```ts
+ * import { addToBasket, basketTotal } from '@stacksjs/commerce/register'
+ *
+ * let basket = addToBasket([], gatorade)
+ * basket = addToBasket(basket, gatorade)
+ * basketTotal(basket, catalog) // 700
+ * ```
+ */
+export declare interface BasketLine {
+  productId: number
+  quantity: number
+}
+export declare interface RegisterFields {
+  id: string
+  price: string
+  inventory: string
+  lowStock: string
+  taxable: string
+}
+export declare interface StockLabel { text: string, tone: 'out' | 'low' | 'ok' }
+declare type Product = Record<string, any>;

package/dist/register.js

@@ -0,0 +1,2 @@
+// @bun
+var k=Object.defineProperty;var x=(t)=>t;function m(t,n){this[t]=x.bind(null,n)}var b=(t,n)=>{for(var e in n)k(t,e,{get:n[e],enumerable:!0,configurable:!0,set:m.bind(n,e)})};var h=(t,n,e)=>()=>{if(t)try{n=t(t=0)}catch(r){e=[r]}if(e)throw e[0];return n};var S={};b(S,{CENTS_FIELDS:()=>g,DEFAULT_FIELDS:()=>u,addToBasket:()=>L,basketCount:()=>B,basketLines:()=>l,basketTaxable:()=>I,basketTotal:()=>F,canAdd:()=>f,groupsOf:()=>T,setQuantity:()=>y,shelfLeft:()=>a,stockLabel:()=>R});var u={id:"id",price:"price",inventory:"inventory",lowStock:"low_stock_threshold",taxable:"taxable"},g={id:"id",price:"price_cents",inventory:"inventory_quantity",lowStock:"low_stock_threshold",taxable:"taxable"};function s(t,n){return Number(t[n.id])}function p(t,n){let e=t[n.inventory];return e===null||e===void 0||e===""?null:Number(e)}function a(t,n,e=u){let r=p(t,e);if(r===null)return null;let o=n.find((c)=>c.productId===s(t,e))?.quantity||0;return Math.max(0,r-o)}function f(t,n,e=u){let r=a(t,n,e);return r===null||r>0}function L(t,n,e=u){if(!f(n,t,e))return t;let r=s(n,e);return t.some((o)=>o.productId===r)?t.map((o)=>o.productId===r?{...o,quantity:o.quantity+1}:o):[...t,{productId:r,quantity:1}]}function y(t,n,e,r=u){let o=s(n,r),c=p(n,r),d=Math.min(Math.max(0,Math.floor(Number(e)||0)),c===null?Number.POSITIVE_INFINITY:c);if(d===0)return t.filter((i)=>i.productId!==o);return t.some((i)=>i.productId===o)?t.map((i)=>i.productId===o?{...i,quantity:d}:i):[...t,{productId:o,quantity:d}]}function l(t,n,e=u){return t.map((r)=>({...r,product:n.find((o)=>s(o,e)===r.productId)})).filter((r)=>!!r.product)}function F(t,n,e=u){return l(t,n,e).reduce((r,o)=>r+Number(o.product[e.price]||0)*o.quantity,0)}function I(t,n,e=u){return l(t,n,e).filter((r)=>r.product[e.taxable]!==!1).reduce((r,o)=>r+Number(o.product[e.price]||0)*o.quantity,0)}function B(t){return t.reduce((n,e)=>n+e.quantity,0)}function R(t,n=[],e=u,r=5){let o=a(t,n,e);if(o===null)return null;if(o===0)return{text:"Sold out",tone:"out"};let c=t[e.lowStock]===null||t[e.lowStock]===void 0?r:Number(t[e.lowStock]);return{text:`${o} left`,tone:o<=c?"low":"ok"}}function T(t,n){let e=[];for(let r of t){let o=n(r);if(!e.includes(o))e.push(o)}return e}export{g as CENTS_FIELDS,u as DEFAULT_FIELDS,L as addToBasket,B as basketCount,l as basketLines,I as basketTaxable,F as basketTotal,f as canAdd,T as groupsOf,y as setQuantity,a as shelfLeft,R as stockLabel};

package/dist/releases.d.ts

@@ -0,0 +1,48 @@
+export declare function isReleaseMode(value: unknown): value is ReleaseMode;
+/** The product row's columns as a config, with the defaults filled in. */
+export declare function rolloutFromProduct(product: { release_mode?: unknown, release_interval_days?: unknown, release_initial_count?: unknown, release_starts_at?: unknown }): RolloutConfig;
+/** When unit `index` unlocks for a buyer whose clock starts at `purchasedAt`. */
+export declare function unlockAt(config: RolloutConfig, index: number, purchasedAt: Date, override?: UnitOverride): Date;
+/** The release of every unit, in order, and whether it is open at `now`. */
+export declare function releaseSchedule(config: RolloutConfig, count: number, purchasedAt: Date, now: Date, overrides?: UnitOverride[]): UnitRelease[];
+/**
+ * How many leading units are open. A plan's weeks are written to the calendar
+ * in order, so an early week never waits behind a later one that opened first
+ * (possible with per-video overrides, which plans do not have).
+ */
+export declare function unlockedPrefix(schedule: UnitRelease[]): number;
+/** A sentence for the product page: what a buyer gets, and when. */
+export declare function describeRollout(config: RolloutConfig, count: number, unit: 'video' | 'week', now?: Date): string;
+/**
+ * When each part of a digital product opens for a buyer: the videos of a
+ * series, the weeks of a training plan or a course. Pure and dependency-free,
+ * so the browser bundles it (`@stacksjs/commerce/releases`) and a server
+ * decides the same way.
+ *
+ * - `all_at_once`: every unit at the anchor.
+ * - `drip`: the first `initialCount` units at the anchor, then one more every
+ *   `intervalDays`. A video's own `offsetDays` overrides its slot.
+ * - `scheduled`: the same dates for every buyer, from `startsAt`, stepping the
+ *   same way. A video's own `releaseAt` overrides its slot. Someone buying
+ *   late gets everything already released.
+ *
+ * The anchor is the purchase, but never before launch: a product whose
+ * `startsAt` is still ahead is a pre-sale, and nothing opens until then.
+ */
+export declare const RELEASE_MODES: readonly ['all_at_once', 'drip', 'scheduled'];
+export declare interface RolloutConfig {
+  mode: ReleaseMode
+  intervalDays: number
+  initialCount: number
+  startsAt: string | null
+}
+export declare interface UnitOverride {
+  offsetDays?: number | null
+  releaseAt?: string | null
+}
+export declare interface UnitRelease {
+  index: number
+  unlock_at: string
+  unlocked: boolean
+}
+export type ReleaseMode = typeof RELEASE_MODES[number];

package/dist/releases.js

@@ -0,0 +1,2 @@
+// @bun
+var _=Object.defineProperty;var b=(e)=>e;function h(e,t){this[e]=b.bind(null,t)}var v=(e,t)=>{for(var n in t)_(e,n,{get:t[n],enumerable:!0,configurable:!0,set:h.bind(t,n)})};var A=(e,t,n)=>()=>{if(e)try{t=e(e=0)}catch(o){n=[o]}if(n)throw n[0];return t};var p={};v(p,{RELEASE_MODES:()=>D,describeRollout:()=>S,isReleaseMode:()=>f,releaseSchedule:()=>k,rolloutFromProduct:()=>w,unlockAt:()=>y,unlockedPrefix:()=>R});var D=["all_at_once","drip","scheduled"];function f(e){return typeof e==="string"&&D.includes(e)}function w(e){let t=Number(e.release_interval_days),n=Number(e.release_initial_count),o=s(e.release_starts_at);return{mode:f(e.release_mode)?e.release_mode:"all_at_once",intervalDays:Number.isInteger(t)&&t>0?t:7,initialCount:Number.isInteger(n)&&n>0?n:1,startsAt:o===null?null:new Date(o).toISOString()}}function s(e){if(e==null||e==="")return null;let t=new Date(String(e)).getTime();return Number.isFinite(t)?t:null}function d(e,t){return Math.max(0,t-(e.initialCount-1))}function y(e,t,n,o={}){let i=s(e.startsAt),a=Math.max(n.getTime(),i??0);if(e.mode==="scheduled"){let r=s(o.releaseAt);if(r!==null)return new Date(r);let l=i??n.getTime();return new Date(l+d(e,t)*e.intervalDays*86400000)}if(e.mode==="drip"){let r=o.offsetDays;if(r!=null&&Number.isFinite(Number(r))&&Number(r)>=0)return new Date(a+Number(r)*86400000);return new Date(a+d(e,t)*e.intervalDays*86400000)}return new Date(a)}function k(e,t,n,o,i=[]){let a=[];for(let r=0;r<t;r++){let l=y(e,r,n,i[r]||{});a.push({index:r,unlock_at:l.toISOString(),unlocked:l.getTime()<=o.getTime()})}return a}function R(e){let t=0;for(let n of e){if(!n.unlocked)break;t++}return t}function S(e,t,n,o=new Date){let i=(c)=>`${c} ${n}${c===1?"":"s"}`,a=s(e.startsAt),r=a!==null&&a>o.getTime()?` from ${new Date(a).toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric",timeZone:"UTC"})}`:"";if(t<=0)return"";if(t===1)return`Available${r||" immediately"}.`;if(e.mode==="all_at_once"||t<=e.initialCount)return`All ${i(t)} available${r||" immediately"}.`;let l=e.intervalDays===1?"every day":e.intervalDays===7?"every week":`every ${e.intervalDays} days`,u=e.initialCount===1,m=u?`The first ${n}`:`The first ${i(e.initialCount)}`;if(e.mode==="drip")return`${m} ${u?"unlocks":"unlock"}${r||" on purchase"}, then one more ${l}.`;if(r)return`${m} ${u?"releases":"release"} on ${r.slice(6)}, then one more ${l}, on the same dates for everyone.`;return`Releasing on a shared schedule${a===null?"":` since ${new Date(a).toLocaleDateString("en-US",{month:"short",day:"numeric",year:"numeric",timeZone:"UTC"})}`}, one more ${n} ${l}. Join now and everything already out is yours.`}export{D as RELEASE_MODES,S as describeRollout,f as isReleaseMode,k as releaseSchedule,w as rolloutFromProduct,y as unlockAt,R as unlockedPrefix};

package/dist/sales-tax.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A stored rate as a decimal multiplier.
+ *
+ * Rates are entered as percentages, because that is how tax is written down
+ * and how the dashboard asks for it. Multiplying by a percentage would charge
+ * a hundred times too much, which is the kind of error that reaches a
+ * customer's card before anyone notices.
+ */
+export declare function multiplierOf(rate: unknown): number;
+export declare function breakdownFor(taxable: number, rates: readonly TaxRateRow[], options?: BreakdownOptions): TaxBreakdown;
+/**
+ * What tax is owed on an amount, component by component.
+ *
+ * The tax rates a dashboard manages did not price anything. `recomputeOrderTotals`
+ * takes a single `taxRateId`, multiplies once, and returns one number — so a
+ * business whose tax is a sum of parts had to blend them into one rate before
+ * storing it, and a blended rate cannot answer the question that matters when
+ * a customer is exempt: exempt from *which part*?
+ *
+ * Most jurisdictions tax in parts and lift some of them for some buyers.
+ * Groceries escape VAT but not a deposit levy. A Californian medical cannabis
+ * patient is exempt from sales tax and still pays excise and the city's
+ * business tax. Blending those into one number leaves an application choosing
+ * between over-charging the exempt customer and under-collecting tax it owes.
+ *
+ * So: rates are rows, an exemption lifts the ones marked `exemptible`, and the
+ * result itemises what was charged and what was not.
+ *
+ * The calculation is pure and imports nothing, so a register in the browser
+ * shows the tax before it charges (`@stacksjs/commerce/sales-tax`); the rates
+ * a dashboard manages are read by `taxFor` in the tax module.
+ */
+/** One component, as it applied to this sale. */
+export declare interface TaxComponent {
+  id: number
+  code: string
+  name: string
+  rate: number
+  amount: number
+  exempted: boolean
+}
+export declare interface TaxBreakdown {
+  taxable: number
+  components: TaxComponent[]
+  tax: number
+  exempted: number
+}
+export declare interface BreakdownOptions {
+  exempt?: boolean
+  codes?: string[]
+  country?: string
+}
+/**
+ * Tax on `taxable` cents, itemised.
+ *
+ * Each component is rounded on its own rather than the total being rounded
+ * once. That is what a receipt has to show — the parts have to add up to the
+ * figure charged, and a single rounding at the end leaves a line that is a
+ * cent out from the sum above it.
+ *
+ * Every component is applied to `taxable` directly. Jurisdictions that compound
+ * — where one tax forms part of the base for another — need an explicit order,
+ * and that is a bigger claim than this should make quietly; an app that needs
+ * it should compose two calls.
+ */
+/** One tax rate row, in the terms the breakdown reads it. */
+export declare interface TaxRateRow {
+  id?: number | string
+  name?: string
+  code?: string
+  rate?: number | string
+  exemptible?: boolean
+}

package/dist/sales-tax.js

@@ -0,0 +1,2 @@
+// @bun
+function s(t){let n=Number(t);return Number.isFinite(n)?n/100:0}function b(t,n,p={}){let a=Math.max(0,Math.round(t)),m=[],i=0,u=0;for(let e of n){let x=s(e.rate),o=Math.round(a*x),r=Boolean(p.exempt&&e.exemptible);if(r)u+=o;else i+=o;m.push({id:Number(e.id),code:String(e.code??""),name:String(e.name??""),rate:x,amount:r?0:o,exempted:r})}return{taxable:a,components:m,tax:i,exempted:u}}export{b as breakdownFor,s as multiplierOf};

package/dist/tax/breakdown.d.ts

@@ -1,6 +1,8 @@
+import { breakdownFor } from '../sales-tax';
+import type { BreakdownOptions, TaxBreakdown } from '../sales-tax';
+export type { BreakdownOptions, TaxBreakdown, TaxComponent, TaxRateRow } from '../sales-tax';
 /** Every active rate, in the order they should be listed. */
 export declare function activeTaxRates(options?: BreakdownOptions): Promise<any[]>;
-export declare function breakdownFor(taxable: number, rates: readonly TaxRateRow[], options?: BreakdownOptions): TaxBreakdown;
 /**
  * Read the active rates and apply them.
  *
@@ -9,44 +11,4 @@ export declare function breakdownFor(taxable: number, rates: readonly TaxRateRow
  * per bag rather than querying each time.
  */
 export declare function taxFor(taxable: number, options?: BreakdownOptions): Promise<TaxBreakdown>;
-/** One component, as it applied to this sale. */
-export declare interface TaxComponent {
-  id: number
-  code: string
-  name: string
-  rate: number
-  amount: number
-  exempted: boolean
-}
-export declare interface TaxBreakdown {
-  taxable: number
-  components: TaxComponent[]
-  tax: number
-  exempted: number
-}
-export declare interface BreakdownOptions {
-  exempt?: boolean
-  codes?: string[]
-  country?: string
-}
-/**
- * Tax on `taxable` cents, itemised.
- *
- * Each component is rounded on its own rather than the total being rounded
- * once. That is what a receipt has to show — the parts have to add up to the
- * figure charged, and a single rounding at the end leaves a line that is a
- * cent out from the sum above it.
- *
- * Every component is applied to `taxable` directly. Jurisdictions that compound
- * — where one tax forms part of the base for another — need an explicit order,
- * and that is a bigger claim than this should make quietly; an app that needs
- * it should compose two calls.
- */
-/** One tax rate row, in the terms the breakdown reads it. */
-export declare interface TaxRateRow {
-  id?: number | string
-  name?: string
-  code?: string
-  rate?: number | string
-  exemptible?: boolean
-}
+export { breakdownFor } from '../sales-tax';

package/package.json

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