@suluk/stripe 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/stripe",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "First-class Stripe via a swappable PaymentProvider: usage-based billing (Billing Meters + meter events), customers, metered prices, subscriptions, webhooks — and a bridge from @suluk/cost to Stripe usage. Other processors follow Stripe. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"

package/src/index.ts

@@ -12,7 +12,7 @@ export {
 } from "./stripe";
 export {
   subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, verifyAmount,
-  cartFingerprint, idempotencyKey,
+  cartFingerprint, idempotencyKey, requiresStripe, STRIPE_MIN_CHARGE_CENTS,
   type CartLine, type Discount, type DiscountResult, type DiscountRejection, type OrderTotal, type AmountVerdict,
 } from "./pricing";
 // the checkout money-path (Phase 1): the pure anti-double-charge / anti-tampering core + the Stripe binding.

package/src/pricing.ts

@@ -26,6 +26,17 @@ export interface Discount {
   value: number;
   /** the discount only applies at/above this subtotal (cents). */
   minSubtotalCents?: number;
+  /** cap the amount removed (cents) — e.g. "30% off, up to $50". Applied before the [0, subtotal] clamp. */
+  maxDiscountCents?: number;
+}
+
+/** Stripe's minimum chargeable amount (USD). Below it, a charge is impossible — the order must go the free path. */
+export const STRIPE_MIN_CHARGE_CENTS = 50;
+
+/** Does this total require a real Stripe charge, or can it complete as a free order? Centralizes the $0.50 floor
+ *  decision so the free-checkout branch and the Stripe branch can never disagree about where $0–$0.49 goes. */
+export function requiresStripe(totalCents: number): boolean {
+  return Math.max(0, Math.round(fin(totalCents))) >= STRIPE_MIN_CHARGE_CENTS;
 }
 
 export interface DiscountResult { valid: boolean; amountCents: number; reason?: DiscountRejection }
@@ -53,7 +64,9 @@ export function computeDiscountAmount(subtotalCents: number, d: Discount): numbe
   const base = Math.max(0, Math.round(fin(subtotalCents)));
   if (base === 0 || !Number.isFinite(d.value) || d.value <= 0) return 0; // a non-finite/non-positive value buys nothing
   const raw = d.type === "percent" ? (base * d.value) / 100 : d.value;
-  return Math.min(base, Math.max(0, Math.round(raw)));
+  // cap a percentage (or fixed) discount at maxDiscountCents if set ("30% off, up to $50"), then clamp to [0, subtotal].
+  const capped = d.maxDiscountCents != null && Number.isFinite(d.maxDiscountCents) ? Math.min(raw, Math.max(0, d.maxDiscountCents)) : raw;
+  return Math.min(base, Math.max(0, Math.round(capped)));
 }
 
 /**

package/test/pricing.test.ts

@@ -1,7 +1,7 @@
 import { test, expect, describe } from "bun:test";
 import {
   subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, verifyAmount,
-  cartFingerprint, idempotencyKey, type CartLine, type Discount,
+  cartFingerprint, idempotencyKey, requiresStripe, STRIPE_MIN_CHARGE_CENTS, type CartLine, type Discount,
 } from "../src/index";
 
 const lines = (xs: [number, number][]): CartLine[] => xs.map(([unitCents, qty], i) => ({ unitCents, qty, id: i + 1 }));
@@ -117,4 +117,34 @@ describe("@suluk/stripe money — pure pricing primitives (the trust layer)", ()
       expect(idempotencyKey("user-1", a)).not.toBe(idempotencyKey("user-2", a));
     });
   });
+
+  describe("maxDiscountCents — capping a percentage discount", () => {
+    test("a percent discount is capped at maxDiscountCents", () => {
+      expect(computeDiscountAmount(30000, { type: "percent", value: 30, maxDiscountCents: 5000 })).toBe(5000); // 9000 → capped 5000
+    });
+    test("under the cap, the full percent applies", () => {
+      expect(computeDiscountAmount(10000, { type: "percent", value: 30, maxDiscountCents: 5000 })).toBe(3000);
+    });
+    test("no cap → uncapped (back-compat)", () => {
+      expect(computeDiscountAmount(30000, { type: "percent", value: 30 })).toBe(9000);
+    });
+    test("the cap still respects the [0, subtotal] clamp", () => {
+      expect(computeDiscountAmount(2000, { type: "fixed", value: 9999, maxDiscountCents: 5000 })).toBe(2000);
+    });
+  });
+
+  describe("requiresStripe — the $0.50 floor / free-order decision", () => {
+    test("a chargeable total requires Stripe", () => {
+      expect(requiresStripe(2900)).toBe(true);
+      expect(requiresStripe(STRIPE_MIN_CHARGE_CENTS)).toBe(true);
+    });
+    test("$0 and sub-floor totals go the free path", () => {
+      expect(requiresStripe(0)).toBe(false);
+      expect(requiresStripe(49)).toBe(false);
+    });
+    test("poison totals never require a charge", () => {
+      expect(requiresStripe(NaN)).toBe(false);
+      expect(requiresStripe(-100)).toBe(false);
+    });
+  });
 });