@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

pnpm add @munchi_oy/cart-engine @munchi_oy/core

Peer dependency:

• @munchi_oy/core

Bundled runtime dependencies:

• dayjs
• lodash
• @paralleldrive/cuid2

Package Layout

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:

pnpm install

Useful commands:

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:

pnpm version:sync

Build always runs version sync first.

Release

Release script:

pnpm release -- 0.1.1

Optional GitHub release modes:

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