# discount-designer

Discount, promotion and pricing-strategy metrics pack for ecommerce, retail and marketing teams designing offers without eroding margin: apply a percentage-off discount (percentOff) or a...


Promotion, pricing & discount-strategy intelligence pack. Deterministic promo/margin math for
ecommerce, retail and marketing teams, with an optional AI coupon-copy layer on `couponPlan` that
activates only when a model is reachable (and silently falls back to the heuristic core otherwise).

**Every discount tool folds in a MARGIN GUARD** — post-discount margin, markup and (optionally) an
above-floor check — so a promotion can never quietly go underwater.

**Pricing math only** — not tax, accounting or legal advice.

## Tools

| Tool | Args | Does |
|---|---|---|
| `percentOff` | `{price, percent, cost?, marginFloor?}` | % off → discounted price, saved, guard. |
| `fixedOff` | `{price, amount, cost?}` | $ off (clamped ≥0) + effective %. |
| `bogo` | `{price, qty, buy?, get?, getDiscount?}` | Buy X Get Y at Z% off; blended unit price + effective %. |
| `tiered` | `{tiers:[{min,price\|discount}], qty, options?}` | Volume/quantity-break pricing, flat best-tier or `mode:'incremental'`. |
| `bundlePrice` | `{items:[{price,cost?,qty?}], bundleDiscount\|bundlePrice}` | Bundle/kit price + savings + blended margin. |
| `marginSafeCheck` | `{cost, price, discount, marginFloor?}` | `{ ok }` guardrail + max safe discount / min safe price. |
| `couponPlan` | `{type, value, avgOrderValue, cost?, usageCap?, validDays?, options?}` | Full coupon spec + per-order economics. `options.advise` adds AI copy. |
| `loyaltyPoints` | `{spend?, points?, pointsPerCurrency?, redeemRate?, tier?}` | Earn points from spend / value a balance, with tier multipliers. |

Only `couponPlan` has an AI path; its result is tagged `{ mode: 'heuristic' | 'llm' }`. Any tool given a
`cost` returns a `guard` block (`unitProfit`, `marginPct`, `markupPct`, `breakEven`, `aboveFloor`).

## Example

```js
import pack from './index.js';
await pack.adapters.percentOff({ price: 100, percent: 20, cost: 60, marginFloor: 30 });
// { discountedPrice:80, amountSaved:20, guard:{ marginPct:25, aboveFloor:false, … } }

await pack.adapters.marginSafeCheck({ cost: 60, price: 100, discount: 20, marginFloor: 30 });
// { ok:false, resultingMarginPct:25, maxSafeDiscountPct≈14.29, minSafePrice≈85.71, verdict:'Unsafe: …' }

await pack.adapters.bogo({ price: 40, qty: 4 });
// buy 1 get 1 free over 4 units → blendedUnitPrice:20, effectivePct:50, …
```

## DRY boundaries

- **`numbers`** owns generic scalar math; **`finance`** owns time-value-of-money; **`tax`** owns tax
  lines; **`invoice`** owns billing documents; **`saas-metrics`** owns recurring-revenue metrics. This
  pack owns *promotion/pricing composition* — percent/fixed off, BOGO, tiered/volume pricing, bundle
  pricing, margin guardrails, coupon plans and loyalty points — which none of those own.
- Self-contained: the only cross-pack import is `../_shared/llm.js` for the optional AI layer.

## Hybrid intelligence

Every deterministic core runs offline with no model. `couponPlan` accepts `options.advise:true` to
request LLM promo copy; with no model configured/reachable it returns the exact same campaign spec
tagged `mode:'heuristic'`. A down model never throws.


---
Source: shared/engines/adapters/domain/discount-designer/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/discount-designer