@lacspace/coupon 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,86 @@
+# @lacspace/coupon
+
+A small, dependable **discount / coupon engine** — percent, fixed and free-shipping codes with validity windows, minimum-subtotal thresholds, discount caps and usage limits. All money is in **integer minor units** (e.g. cents), so there is no floating-point drift.
+
+- **Zero runtime dependencies**
+- **Isomorphic** — Node, edge runtimes and browsers
+- **TypeScript-first**, strict types
+
+```bash
+npm install @lacspace/coupon
+```
+
+## Quick start
+
+```ts
+import { applyCoupon, validateCoupon, type Coupon } from "@lacspace/coupon";
+
+const coupon: Coupon = {
+  code: "SAVE20",
+  type: "percent",
+  value: 20,          // 20%
+  maxDiscount: 500,   // never more than $5.00
+  minSubtotal: 1000,  // order must be at least $10.00
+};
+
+applyCoupon(coupon, { subtotal: 3000, shipping: 400 });
+// { valid: true, discount: 500, shippingDiscount: 0, total: 2900 }
+```
+
+## API
+
+### `validateCoupon(coupon, { subtotal, now? }): { valid, reason? }`
+
+Checks the validity window (`not-yet-started` / `expired`), `minSubtotal` (`below-min-subtotal`) and `usageLimit` vs `used` (`usage-limit-reached`). Does not compute a discount.
+
+### `applyCoupon(coupon, { subtotal, shipping?, now? }): CouponResult`
+
+Validates, then computes the discount:
+
+| type            | discount                                             |
+| --------------- | ---------------------------------------------------- |
+| `percent`       | `round(subtotal * value / 100)`, capped by `maxDiscount` and the subtotal |
+| `fixed`         | `min(value, subtotal)`, capped by `maxDiscount`      |
+| `free-shipping` | `shippingDiscount = shipping`                        |
+
+```
+total = max(0, subtotal - discount + shipping - shippingDiscount)
+```
+
+When the coupon is invalid, discounts are `0` and the total is the untouched `subtotal + shipping`.
+
+```ts
+applyCoupon({ code: "FREESHIP", type: "free-shipping" }, { subtotal: 1000, shipping: 300 });
+// { valid: true, discount: 0, shippingDiscount: 300, total: 1000 }
+```
+
+## Types
+
+```ts
+interface Coupon {
+  code: string;
+  type: "percent" | "fixed" | "free-shipping";
+  value?: number;        // percent 0..100, or minor units for fixed
+  minSubtotal?: number;
+  maxDiscount?: number;
+  startsAt?: string;     // ISO-8601
+  endsAt?: string;       // ISO-8601
+  usageLimit?: number;
+  used?: number;
+  currency?: string;
+}
+```
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/coupon` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+// src/index.ts
+function validateCoupon(coupon, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  const t = now.getTime();
+  if (coupon.startsAt) {
+    const starts = new Date(coupon.startsAt).getTime();
+    if (!Number.isNaN(starts) && t < starts) {
+      return { valid: false, reason: "not-yet-started" };
+    }
+  }
+  if (coupon.endsAt) {
+    const ends = new Date(coupon.endsAt).getTime();
+    if (!Number.isNaN(ends) && t > ends) {
+      return { valid: false, reason: "expired" };
+    }
+  }
+  if (typeof coupon.minSubtotal === "number" && ctx.subtotal < coupon.minSubtotal) {
+    return { valid: false, reason: "below-min-subtotal" };
+  }
+  if (typeof coupon.usageLimit === "number" && (coupon.used ?? 0) >= coupon.usageLimit) {
+    return { valid: false, reason: "usage-limit-reached" };
+  }
+  return { valid: true };
+}
+function applyCoupon(coupon, ctx) {
+  const subtotal = ctx.subtotal;
+  const shipping = ctx.shipping ?? 0;
+  const validation = validateCoupon(coupon, { subtotal, now: ctx.now });
+  if (!validation.valid) {
+    return {
+      ...validation,
+      discount: 0,
+      shippingDiscount: 0,
+      total: Math.max(0, subtotal + shipping)
+    };
+  }
+  let discount = 0;
+  let shippingDiscount = 0;
+  switch (coupon.type) {
+    case "percent": {
+      const pct = coupon.value ?? 0;
+      discount = Math.round(subtotal * pct / 100);
+      break;
+    }
+    case "fixed": {
+      const amount = coupon.value ?? 0;
+      discount = Math.min(amount, subtotal);
+      break;
+    }
+    case "free-shipping": {
+      shippingDiscount = shipping;
+      break;
+    }
+  }
+  if (typeof coupon.maxDiscount === "number") {
+    discount = Math.min(discount, coupon.maxDiscount);
+  }
+  discount = Math.min(discount, subtotal);
+  discount = Math.max(0, discount);
+  const total = Math.max(0, subtotal - discount + shipping - shippingDiscount);
+  return { valid: true, discount, shippingDiscount, total };
+}
+
+exports.applyCoupon = applyCoupon;
+exports.validateCoupon = validateCoupon;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/coupon\n *\n * Discount / coupon engine — percent, fixed and free-shipping codes with\n * validity windows, minimum-subtotal thresholds, discount caps and usage\n * limits. All money is expressed in integer minor units (e.g. cents) so there\n * is no floating-point drift.\n *\n * Zero runtime dependencies. Isomorphic (Node, edge, browser).\n */\n\n/** A discount coupon definition. */\nexport interface Coupon {\n  /** The code a customer enters. */\n  code: string;\n  /** Kind of discount. */\n  type: \"percent\" | \"fixed\" | \"free-shipping\";\n  /**\n   * For `percent`, a whole percentage 0..100. For `fixed`, an amount in minor\n   * units. Ignored for `free-shipping`.\n   */\n  value?: number;\n  /** Minimum order subtotal (minor units) required for the coupon to apply. */\n  minSubtotal?: number;\n  /** Maximum discount (minor units) the coupon may grant. */\n  maxDiscount?: number;\n  /** ISO-8601 timestamp before which the coupon is not yet valid. */\n  startsAt?: string;\n  /** ISO-8601 timestamp after which the coupon has expired. */\n  endsAt?: string;\n  /** How many times the coupon may be redeemed in total. */\n  usageLimit?: number;\n  /** How many times it has already been redeemed. */\n  used?: number;\n  /** Optional currency tag for downstream formatting. */\n  currency?: string;\n}\n\n/** Result of validating a coupon against a context. */\nexport interface CouponValidation {\n  valid: boolean;\n  reason?: string;\n}\n\n/** Result of applying a coupon to an order. */\nexport interface CouponResult extends CouponValidation {\n  /** Discount applied to the subtotal (minor units). */\n  discount: number;\n  /** Discount applied to shipping (minor units). */\n  shippingDiscount: number;\n  /** Final payable total (minor units). */\n  total: number;\n}\n\n/**\n * Validate a coupon against an order context: checks the validity window,\n * minimum-subtotal threshold and usage limit. Does not compute any discount.\n */\nexport function validateCoupon(\n  coupon: Coupon,\n  ctx: { subtotal: number; now?: Date },\n): CouponValidation {\n  const now = ctx.now ?? new Date();\n  const t = now.getTime();\n\n  if (coupon.startsAt) {\n    const starts = new Date(coupon.startsAt).getTime();\n    if (!Number.isNaN(starts) && t < starts) {\n      return { valid: false, reason: \"not-yet-started\" };\n    }\n  }\n\n  if (coupon.endsAt) {\n    const ends = new Date(coupon.endsAt).getTime();\n    if (!Number.isNaN(ends) && t > ends) {\n      return { valid: false, reason: \"expired\" };\n    }\n  }\n\n  if (typeof coupon.minSubtotal === \"number\" && ctx.subtotal < coupon.minSubtotal) {\n    return { valid: false, reason: \"below-min-subtotal\" };\n  }\n\n  if (\n    typeof coupon.usageLimit === \"number\" &&\n    (coupon.used ?? 0) >= coupon.usageLimit\n  ) {\n    return { valid: false, reason: \"usage-limit-reached\" };\n  }\n\n  return { valid: true };\n}\n\n/**\n * Apply a coupon to an order. Validates first; when invalid, returns zero\n * discounts and the untouched total. When valid, computes the discount:\n *\n * - `percent`  → `round(subtotal * value / 100)`, capped by `maxDiscount` and\n *   never more than the subtotal.\n * - `fixed`    → `min(value, subtotal)`, capped by `maxDiscount`.\n * - `free-shipping` → `shippingDiscount = shipping`.\n *\n * `total = max(0, subtotal - discount + shipping - shippingDiscount)`.\n */\nexport function applyCoupon(\n  coupon: Coupon,\n  ctx: { subtotal: number; shipping?: number; now?: Date },\n): CouponResult {\n  const subtotal = ctx.subtotal;\n  const shipping = ctx.shipping ?? 0;\n\n  const validation = validateCoupon(coupon, { subtotal, now: ctx.now });\n  if (!validation.valid) {\n    return {\n      ...validation,\n      discount: 0,\n      shippingDiscount: 0,\n      total: Math.max(0, subtotal + shipping),\n    };\n  }\n\n  let discount = 0;\n  let shippingDiscount = 0;\n\n  switch (coupon.type) {\n    case \"percent\": {\n      const pct = coupon.value ?? 0;\n      discount = Math.round((subtotal * pct) / 100);\n      break;\n    }\n    case \"fixed\": {\n      const amount = coupon.value ?? 0;\n      discount = Math.min(amount, subtotal);\n      break;\n    }\n    case \"free-shipping\": {\n      shippingDiscount = shipping;\n      break;\n    }\n  }\n\n  if (typeof coupon.maxDiscount === \"number\") {\n    discount = Math.min(discount, coupon.maxDiscount);\n  }\n  discount = Math.min(discount, subtotal);\n  discount = Math.max(0, discount);\n\n  const total = Math.max(0, subtotal - discount + shipping - shippingDiscount);\n\n  return { valid: true, discount, shippingDiscount, total };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+/**
+ * @lacspace/coupon
+ *
+ * Discount / coupon engine — percent, fixed and free-shipping codes with
+ * validity windows, minimum-subtotal thresholds, discount caps and usage
+ * limits. All money is expressed in integer minor units (e.g. cents) so there
+ * is no floating-point drift.
+ *
+ * Zero runtime dependencies. Isomorphic (Node, edge, browser).
+ */
+/** A discount coupon definition. */
+interface Coupon {
+    /** The code a customer enters. */
+    code: string;
+    /** Kind of discount. */
+    type: "percent" | "fixed" | "free-shipping";
+    /**
+     * For `percent`, a whole percentage 0..100. For `fixed`, an amount in minor
+     * units. Ignored for `free-shipping`.
+     */
+    value?: number;
+    /** Minimum order subtotal (minor units) required for the coupon to apply. */
+    minSubtotal?: number;
+    /** Maximum discount (minor units) the coupon may grant. */
+    maxDiscount?: number;
+    /** ISO-8601 timestamp before which the coupon is not yet valid. */
+    startsAt?: string;
+    /** ISO-8601 timestamp after which the coupon has expired. */
+    endsAt?: string;
+    /** How many times the coupon may be redeemed in total. */
+    usageLimit?: number;
+    /** How many times it has already been redeemed. */
+    used?: number;
+    /** Optional currency tag for downstream formatting. */
+    currency?: string;
+}
+/** Result of validating a coupon against a context. */
+interface CouponValidation {
+    valid: boolean;
+    reason?: string;
+}
+/** Result of applying a coupon to an order. */
+interface CouponResult extends CouponValidation {
+    /** Discount applied to the subtotal (minor units). */
+    discount: number;
+    /** Discount applied to shipping (minor units). */
+    shippingDiscount: number;
+    /** Final payable total (minor units). */
+    total: number;
+}
+/**
+ * Validate a coupon against an order context: checks the validity window,
+ * minimum-subtotal threshold and usage limit. Does not compute any discount.
+ */
+declare function validateCoupon(coupon: Coupon, ctx: {
+    subtotal: number;
+    now?: Date;
+}): CouponValidation;
+/**
+ * Apply a coupon to an order. Validates first; when invalid, returns zero
+ * discounts and the untouched total. When valid, computes the discount:
+ *
+ * - `percent`  → `round(subtotal * value / 100)`, capped by `maxDiscount` and
+ *   never more than the subtotal.
+ * - `fixed`    → `min(value, subtotal)`, capped by `maxDiscount`.
+ * - `free-shipping` → `shippingDiscount = shipping`.
+ *
+ * `total = max(0, subtotal - discount + shipping - shippingDiscount)`.
+ */
+declare function applyCoupon(coupon: Coupon, ctx: {
+    subtotal: number;
+    shipping?: number;
+    now?: Date;
+}): CouponResult;
+
+export { type Coupon, type CouponResult, type CouponValidation, applyCoupon, validateCoupon };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @lacspace/coupon
+ *
+ * Discount / coupon engine — percent, fixed and free-shipping codes with
+ * validity windows, minimum-subtotal thresholds, discount caps and usage
+ * limits. All money is expressed in integer minor units (e.g. cents) so there
+ * is no floating-point drift.
+ *
+ * Zero runtime dependencies. Isomorphic (Node, edge, browser).
+ */
+/** A discount coupon definition. */
+interface Coupon {
+    /** The code a customer enters. */
+    code: string;
+    /** Kind of discount. */
+    type: "percent" | "fixed" | "free-shipping";
+    /**
+     * For `percent`, a whole percentage 0..100. For `fixed`, an amount in minor
+     * units. Ignored for `free-shipping`.
+     */
+    value?: number;
+    /** Minimum order subtotal (minor units) required for the coupon to apply. */
+    minSubtotal?: number;
+    /** Maximum discount (minor units) the coupon may grant. */
+    maxDiscount?: number;
+    /** ISO-8601 timestamp before which the coupon is not yet valid. */
+    startsAt?: string;
+    /** ISO-8601 timestamp after which the coupon has expired. */
+    endsAt?: string;
+    /** How many times the coupon may be redeemed in total. */
+    usageLimit?: number;
+    /** How many times it has already been redeemed. */
+    used?: number;
+    /** Optional currency tag for downstream formatting. */
+    currency?: string;
+}
+/** Result of validating a coupon against a context. */
+interface CouponValidation {
+    valid: boolean;
+    reason?: string;
+}
+/** Result of applying a coupon to an order. */
+interface CouponResult extends CouponValidation {
+    /** Discount applied to the subtotal (minor units). */
+    discount: number;
+    /** Discount applied to shipping (minor units). */
+    shippingDiscount: number;
+    /** Final payable total (minor units). */
+    total: number;
+}
+/**
+ * Validate a coupon against an order context: checks the validity window,
+ * minimum-subtotal threshold and usage limit. Does not compute any discount.
+ */
+declare function validateCoupon(coupon: Coupon, ctx: {
+    subtotal: number;
+    now?: Date;
+}): CouponValidation;
+/**
+ * Apply a coupon to an order. Validates first; when invalid, returns zero
+ * discounts and the untouched total. When valid, computes the discount:
+ *
+ * - `percent`  → `round(subtotal * value / 100)`, capped by `maxDiscount` and
+ *   never more than the subtotal.
+ * - `fixed`    → `min(value, subtotal)`, capped by `maxDiscount`.
+ * - `free-shipping` → `shippingDiscount = shipping`.
+ *
+ * `total = max(0, subtotal - discount + shipping - shippingDiscount)`.
+ */
+declare function applyCoupon(coupon: Coupon, ctx: {
+    subtotal: number;
+    shipping?: number;
+    now?: Date;
+}): CouponResult;
+
+export { type Coupon, type CouponResult, type CouponValidation, applyCoupon, validateCoupon };

package/dist/index.js

@@ -0,0 +1,66 @@
+// src/index.ts
+function validateCoupon(coupon, ctx) {
+  const now = ctx.now ?? /* @__PURE__ */ new Date();
+  const t = now.getTime();
+  if (coupon.startsAt) {
+    const starts = new Date(coupon.startsAt).getTime();
+    if (!Number.isNaN(starts) && t < starts) {
+      return { valid: false, reason: "not-yet-started" };
+    }
+  }
+  if (coupon.endsAt) {
+    const ends = new Date(coupon.endsAt).getTime();
+    if (!Number.isNaN(ends) && t > ends) {
+      return { valid: false, reason: "expired" };
+    }
+  }
+  if (typeof coupon.minSubtotal === "number" && ctx.subtotal < coupon.minSubtotal) {
+    return { valid: false, reason: "below-min-subtotal" };
+  }
+  if (typeof coupon.usageLimit === "number" && (coupon.used ?? 0) >= coupon.usageLimit) {
+    return { valid: false, reason: "usage-limit-reached" };
+  }
+  return { valid: true };
+}
+function applyCoupon(coupon, ctx) {
+  const subtotal = ctx.subtotal;
+  const shipping = ctx.shipping ?? 0;
+  const validation = validateCoupon(coupon, { subtotal, now: ctx.now });
+  if (!validation.valid) {
+    return {
+      ...validation,
+      discount: 0,
+      shippingDiscount: 0,
+      total: Math.max(0, subtotal + shipping)
+    };
+  }
+  let discount = 0;
+  let shippingDiscount = 0;
+  switch (coupon.type) {
+    case "percent": {
+      const pct = coupon.value ?? 0;
+      discount = Math.round(subtotal * pct / 100);
+      break;
+    }
+    case "fixed": {
+      const amount = coupon.value ?? 0;
+      discount = Math.min(amount, subtotal);
+      break;
+    }
+    case "free-shipping": {
+      shippingDiscount = shipping;
+      break;
+    }
+  }
+  if (typeof coupon.maxDiscount === "number") {
+    discount = Math.min(discount, coupon.maxDiscount);
+  }
+  discount = Math.min(discount, subtotal);
+  discount = Math.max(0, discount);
+  const total = Math.max(0, subtotal - discount + shipping - shippingDiscount);
+  return { valid: true, discount, shippingDiscount, total };
+}
+
+export { applyCoupon, validateCoupon };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/coupon\n *\n * Discount / coupon engine — percent, fixed and free-shipping codes with\n * validity windows, minimum-subtotal thresholds, discount caps and usage\n * limits. All money is expressed in integer minor units (e.g. cents) so there\n * is no floating-point drift.\n *\n * Zero runtime dependencies. Isomorphic (Node, edge, browser).\n */\n\n/** A discount coupon definition. */\nexport interface Coupon {\n  /** The code a customer enters. */\n  code: string;\n  /** Kind of discount. */\n  type: \"percent\" | \"fixed\" | \"free-shipping\";\n  /**\n   * For `percent`, a whole percentage 0..100. For `fixed`, an amount in minor\n   * units. Ignored for `free-shipping`.\n   */\n  value?: number;\n  /** Minimum order subtotal (minor units) required for the coupon to apply. */\n  minSubtotal?: number;\n  /** Maximum discount (minor units) the coupon may grant. */\n  maxDiscount?: number;\n  /** ISO-8601 timestamp before which the coupon is not yet valid. */\n  startsAt?: string;\n  /** ISO-8601 timestamp after which the coupon has expired. */\n  endsAt?: string;\n  /** How many times the coupon may be redeemed in total. */\n  usageLimit?: number;\n  /** How many times it has already been redeemed. */\n  used?: number;\n  /** Optional currency tag for downstream formatting. */\n  currency?: string;\n}\n\n/** Result of validating a coupon against a context. */\nexport interface CouponValidation {\n  valid: boolean;\n  reason?: string;\n}\n\n/** Result of applying a coupon to an order. */\nexport interface CouponResult extends CouponValidation {\n  /** Discount applied to the subtotal (minor units). */\n  discount: number;\n  /** Discount applied to shipping (minor units). */\n  shippingDiscount: number;\n  /** Final payable total (minor units). */\n  total: number;\n}\n\n/**\n * Validate a coupon against an order context: checks the validity window,\n * minimum-subtotal threshold and usage limit. Does not compute any discount.\n */\nexport function validateCoupon(\n  coupon: Coupon,\n  ctx: { subtotal: number; now?: Date },\n): CouponValidation {\n  const now = ctx.now ?? new Date();\n  const t = now.getTime();\n\n  if (coupon.startsAt) {\n    const starts = new Date(coupon.startsAt).getTime();\n    if (!Number.isNaN(starts) && t < starts) {\n      return { valid: false, reason: \"not-yet-started\" };\n    }\n  }\n\n  if (coupon.endsAt) {\n    const ends = new Date(coupon.endsAt).getTime();\n    if (!Number.isNaN(ends) && t > ends) {\n      return { valid: false, reason: \"expired\" };\n    }\n  }\n\n  if (typeof coupon.minSubtotal === \"number\" && ctx.subtotal < coupon.minSubtotal) {\n    return { valid: false, reason: \"below-min-subtotal\" };\n  }\n\n  if (\n    typeof coupon.usageLimit === \"number\" &&\n    (coupon.used ?? 0) >= coupon.usageLimit\n  ) {\n    return { valid: false, reason: \"usage-limit-reached\" };\n  }\n\n  return { valid: true };\n}\n\n/**\n * Apply a coupon to an order. Validates first; when invalid, returns zero\n * discounts and the untouched total. When valid, computes the discount:\n *\n * - `percent`  → `round(subtotal * value / 100)`, capped by `maxDiscount` and\n *   never more than the subtotal.\n * - `fixed`    → `min(value, subtotal)`, capped by `maxDiscount`.\n * - `free-shipping` → `shippingDiscount = shipping`.\n *\n * `total = max(0, subtotal - discount + shipping - shippingDiscount)`.\n */\nexport function applyCoupon(\n  coupon: Coupon,\n  ctx: { subtotal: number; shipping?: number; now?: Date },\n): CouponResult {\n  const subtotal = ctx.subtotal;\n  const shipping = ctx.shipping ?? 0;\n\n  const validation = validateCoupon(coupon, { subtotal, now: ctx.now });\n  if (!validation.valid) {\n    return {\n      ...validation,\n      discount: 0,\n      shippingDiscount: 0,\n      total: Math.max(0, subtotal + shipping),\n    };\n  }\n\n  let discount = 0;\n  let shippingDiscount = 0;\n\n  switch (coupon.type) {\n    case \"percent\": {\n      const pct = coupon.value ?? 0;\n      discount = Math.round((subtotal * pct) / 100);\n      break;\n    }\n    case \"fixed\": {\n      const amount = coupon.value ?? 0;\n      discount = Math.min(amount, subtotal);\n      break;\n    }\n    case \"free-shipping\": {\n      shippingDiscount = shipping;\n      break;\n    }\n  }\n\n  if (typeof coupon.maxDiscount === \"number\") {\n    discount = Math.min(discount, coupon.maxDiscount);\n  }\n  discount = Math.min(discount, subtotal);\n  discount = Math.max(0, discount);\n\n  const total = Math.max(0, subtotal - discount + shipping - shippingDiscount);\n\n  return { valid: true, discount, shippingDiscount, total };\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/coupon",
+  "version": "1.0.0",
+  "description": "Discount & coupon engine — percent, fixed and free-shipping codes with validity windows, minimum-subtotal, discount caps and usage limits. Integer minor units, no float drift. Zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "coupon",
+    "discount",
+    "promo-code",
+    "voucher",
+    "percent-off",
+    "free-shipping",
+    "checkout",
+    "ecommerce",
+    "minor-units",
+    "isomorphic",
+    "zero-dependency",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/coupon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "coupon"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}