@munchi_oy/cart-engine 0.1.0

package/README.md

@@ -0,0 +1,204 @@
+# @munchi_oy/cart-engine
+
+Headless cart engine for Munchi POS flows.
+
+This package owns cart state, pricing, discount application, and tax summary calculation. It is designed for offline-first consumers and shared across app surfaces without depending on React, Zustand, Firebase, or UI code.
+
+## Scope
+
+This package includes:
+
+- `Cart` aggregate for cart state mutations
+- Pure pricing helpers
+- Pure discount helpers
+- Pure tax helpers
+- Shared cart-oriented types
+
+This package does not include:
+
+- Product mapping from app DTOs into cart items
+- UI formatting
+- Persistence
+- Network calls
+- Activity logs or staff audit logging
+- Payment settlement logic
+
+## Core Rules
+
+- All money is in minor units as integers
+- Use `Math.floor()` for percentage-derived money calculations
+- Tax rate may be decimal, such as `13.5`
+- `Cart` owns state
+- Pricing, discount, and tax modules stay pure and stateless
+- The package relies on shared DTO contracts from `@munchi_oy/core`
+
+## Install
+
+```bash
+pnpm add @munchi_oy/cart-engine @munchi_oy/core
+```
+
+Peer dependency:
+
+- `@munchi_oy/core`
+
+Bundled runtime dependencies:
+
+- `dayjs`
+- `lodash`
+- `@paralleldrive/cuid2`
+
+## Package Layout
+
+```text
+src/
+  cart/
+    Cart.ts
+  discount/
+    calculator.ts
+    modulo.ts
+  pricing/
+    calculator.ts
+  tax/
+    index.ts
+  types/
+    index.ts
+  utils/
+    index.ts
+  version.ts
+  index.ts
+```
+
+## Public API
+
+Main exports:
+
+- `Cart`
+- `calculateItemPrice`
+- `calculateCartPriceSnapshot`
+- `calculateDiscountAmount`
+- `calculateSequentialDiscountTotal`
+- `allocateProportionalMinorUnits`
+- `splitTaxInclusiveAmount`
+- `calculateOrderTaxSummary`
+- `ApplyTo`
+- `VERSION`
+
+## Cart Responsibilities
+
+`Cart` is the aggregate root for cart state. It currently handles:
+
+- item add, update, remove, and status changes
+- item and cart discounts
+- customer, invoice company, loyalty, and order metadata
+- serialization through `toJSON()`
+- rehydration through `fromData()`
+- cloning through `clone()`
+
+`Cart` delegates all math to the pure modules under `discount`, `pricing`, and `tax`.
+
+## Pricing, Discount, and Tax Boundaries
+
+### Pricing
+
+Pricing helpers work on normalized cart data and produce DTO-safe totals. They do not parse raw user input.
+
+### Discount
+
+`calculateDiscountAmount` expects normalized values:
+
+- percentage discount values are percentages
+- fixed discount values are already in minor units
+
+If the app needs to parse user-entered strings such as `"10.50"`, that parsing should happen outside this package before calling the engine.
+
+### Tax
+
+Tax calculations:
+
+- use integer money math
+- support decimal tax rates
+- group tax summaries by rate
+- allocate cart-level discounts proportionally before tax splitting
+
+## Development
+
+Install dependencies:
+
+```bash
+pnpm install
+```
+
+Useful commands:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm yalc:publish
+pnpm yalc:push
+```
+
+## Testing
+
+Tests live under `test/` and are organized by concern:
+
+- cart item behavior
+- cart pricing behavior
+- cart tax behavior
+- cart metadata behavior
+- cart serialization behavior
+- pure discount helpers
+- pure pricing helpers
+- pure tax helpers
+
+Current expectations:
+
+- cart totals must be correct for no discount, item discount, cart discount, and combined discount cases
+- tax summaries must group by dynamic tax rate
+- runtime fallbacks must behave safely
+
+## Versioning
+
+Package version is sourced from `package.json` and synced into `src/version.ts`.
+
+Sync version constant:
+
+```bash
+pnpm version:sync
+```
+
+Build always runs version sync first.
+
+## Release
+
+Release script:
+
+```bash
+pnpm release -- 0.1.1
+```
+
+Optional GitHub release modes:
+
+```bash
+pnpm release -- 0.1.1 --publish
+pnpm release -- 0.1.1 --publish=custom
+pnpm release -- 0.1.1 --publish=file
+```
+
+The release script:
+
+- updates `package.json`
+- syncs `src/version.ts`
+- runs typecheck, tests, and build
+- creates a commit
+- creates a `v<version>` tag
+- pushes branch and tag
+- optionally creates a GitHub release
+
+## Consumer Notes
+
+- Rebuild before publishing or pushing with `yalc`
+- If a consumer app still sees stale types, rebuild and refresh the installed package
+- One cart should use one `CurrencyCode`
+