retail.coupon-validate

export function validateCoupon(coupon: Coupon, lines: readonly CouponLine[], customerUses: number, onDate: string): CouponCheck

/** The rules attached to one coupon code. A null limit is no limit. */
export interface Coupon {
  readonly code: string;
  /** first day it can be used */
  readonly validFrom: string | null;
  /** last day it can be used, inclusive */
  readonly validTo: string | null;
  readonly minimumSpend: Money | null;
  /** basket: the whole basket counts; eligible: only eligible lines count */
  readonly minimumSpendOn: SpendScope;
  /** redemptions allowed across all customers */
  readonly maxUses: number | null;
  /** redemptions so far across all customers */
  readonly timesUsed: number;
  readonly maxUsesPerCustomer: number | null;
  /** eligible SKUs; with categories empty too, every line is eligible */
  readonly skus: readonly string[];
  /** eligible categories */
  readonly categories: readonly string[];
  /** never eligible, even when listed above */
  readonly excludedSkus: readonly string[];
  /** never eligible, even when listed above */
  readonly excludedCategories: readonly string[];
}

export type SpendScope = "basket" | "eligible";

/** One basket line as the coupon sees it. */
export interface CouponLine {
  readonly sku: string;
  readonly category: string;
  /** the line's price after any line promotions */
  readonly total: Money;
}

/** Whether the coupon applies, every reason it does not, and which lines it can discount. */
export interface CouponCheck {
  readonly valid: boolean;
  /** in a fixed order: not-yet-valid, expired, usage-limit-reached, customer-limit-reached, no-eligible-items, minimum-spend-not-met */
  readonly reasons: readonly string[];
  /** 0-based indices into lines, in basket order */
  readonly eligibleLines: readonly number[];
}

import { validateCoupon } from "#fune/retail.coupon-validate@^1";

import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { compareMoney } from "./money_compare.ts";  ← from money.compare ^1.0.0 · built alongside by fune
import { sumMoney } from "./money_sum.ts";  ← from money.sum ^1.0.0 · built alongside by fune
import { type Coupon, type CouponLine, type CouponCheck } from "./retail_coupon_validate_types.ts";

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

function isEligible(coupon: Coupon, line: CouponLine): boolean {
  const open = coupon.skus.length === 0 && coupon.categories.length === 0;
  const listed = open || coupon.skus.includes(line.sku) || coupon.categories.includes(line.category);
  const excluded = coupon.excludedSkus.includes(line.sku) || coupon.excludedCategories.includes(line.category);
  return listed && !excluded;
}

/**
 * Whether a coupon can be used on a basket, with every reason it cannot.
 * ISO dates compare correctly as strings.
 */
export function validateCoupon(
  coupon: Coupon,
  lines: readonly CouponLine[],
  customerUses: number,
  onDate: string,
): CouponCheck {
  if (!ISO_DATE.test(onDate)) throw new RangeError(`onDate must be an ISO date (YYYY-MM-DD), received "${onDate}"`);
  if (!Number.isInteger(customerUses) || customerUses < 0) {
    throw new RangeError(`customerUses must not be negative, received ${customerUses}`);
  }

  const eligibleLines: number[] = [];
  lines.forEach((line, index) => {
    if (isEligible(coupon, line)) eligibleLines.push(index);
  });

  const reasons: string[] = [];
  if (coupon.validFrom !== null && onDate < coupon.validFrom) reasons.push("not-yet-valid");
  if (coupon.validTo !== null && onDate > coupon.validTo) reasons.push("expired");
  if (coupon.maxUses !== null && coupon.timesUsed >= coupon.maxUses) reasons.push("usage-limit-reached");
  if (coupon.maxUsesPerCustomer !== null && customerUses >= coupon.maxUsesPerCustomer) {
    reasons.push("customer-limit-reached");
  }
  if (eligibleLines.length === 0) reasons.push("no-eligible-items");
  if (coupon.minimumSpend !== null) {
    const counted: Money[] =
      coupon.minimumSpendOn === "eligible" ? eligibleLines.map((i) => lines[i].total) : lines.map((l) => l.total);
    const spend = sumMoney(counted, coupon.minimumSpend.currency);
    if (compareMoney(spend, coupon.minimumSpend) < 0) reasons.push("minimum-spend-not-met");
  }

  return { valid: reasons.length === 0, reasons, eligibleLines };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add retail.coupon-validate

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./retail.coupon-validate-1.0.0-typescript.fune, or fetch it from a terminal with fune pull retail.coupon-validate@1.0.0:typescript.

The whole function, every language, is one file too: retail.coupon-validate-1.0.0.fune, 31,771 bytes, sha256 2f3b1751f83b86484da40c127ba5c07ab7e3d3451f7d11c8dee60ec1e953c6a6. It installs into a project of any language.

// fune: before retail.coupon-validate

// fune: after retail.coupon-validate

// fune: replace money.amount in retail.coupon-validate
// fune: replace money.compare in retail.coupon-validate
// fune: replace money.sum in retail.coupon-validate

// fune: step retail.coupon-validate after <n|label>

More from the author

| reason | fails when | |---|---| | `not-yet-valid` | `onDate` is before `validFrom` | | `expired` | `onDate` is after `validTo` (the last day is inclusive) | | `usage-limit-reached` | `timesUsed` is `maxUses` or more | | `customer-limit-reached` | `customerUses` is `maxUsesPerCustomer` or more | | `no-eligible-items` | no line passes the product rules | | `minimum-spend-not-met` | the spend is below `minimumSpend` |

Every failing reason is returned, not just the first, so a checkout can say "this code expired, and it needs a £20 spend" in one go. `valid` is true exactly when `reasons` is empty. A null limit is no limit.

## Which lines are eligible

A line is eligible when its SKU is in `skus` or its category is in `categories` (either list; both empty means every line), and neither its SKU is in `excludedSkus` nor its category in `excludedCategories`. Exclusions always win: that is how "20% off homeware, excluding sale items" is written.

## Minimum spend

`minimumSpendOn` says what counts towards it: `basket` sums every line, `eligible` only the eligible ones. Retailers do both, and the difference is a common source of complaints, so the coupon has to say. Line totals should be after line promotions and before this coupon's own discount. The minimum spend and the lines must share a currency.

This function only decides eligibility. Working out the discount and spreading it across the eligible lines is `money.apply-rate` and `money.allocate`, and recording the use (incrementing `timesUsed`) is the caller's job, once the order is placed, not when the code is checked.

Files