@suluk/stripe 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/stripe",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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

@@ -11,10 +11,19 @@ export {
   type UsageBillingConfig, type CostBillingConfig,
 } from "./stripe";
 export {
-  subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, verifyAmount,
-  cartFingerprint, idempotencyKey,
-  type CartLine, type Discount, type DiscountResult, type DiscountRejection, type OrderTotal, type AmountVerdict,
+  subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, composeTotal, verifyAmount,
+  cartFingerprint, idempotencyKey, requiresStripe, STRIPE_MIN_CHARGE_CENTS,
+  type CartLine, type Discount, type DiscountResult, type DiscountRejection, type OrderTotal, type OrderTotalFull, type AmountVerdict,
 } from "./pricing";
+// pluggable shipping + tax adapters — swap flat-rate for Shippo/EasyPost/TaxJar/Stripe-Tax without touching checkout.
+export {
+  cartNeedsShipping, flatRateShipping, combineShipping, resolveShipping,
+  type ShippingInput, type ShippingOption, type ShippingProvider,
+} from "./shipping";
+export {
+  flatRateTax, noTax, resolveTax,
+  type TaxInput, type TaxResult, type TaxProvider,
+} from "./tax";
 // the checkout money-path (Phase 1): the pure anti-double-charge / anti-tampering core + the Stripe binding.
 export {
   planPaymentIntent, cardInfoFrom, ownsPaymentMethod, stripeCheckout,

package/src/pricing.ts

@@ -112,6 +112,23 @@ export function orderTotal(lines: CartLine[], discount?: Discount | null): Order
   return { subtotalCents, discountCents, totalCents: subtotalCents - discountCents };
 }
 
+/** The full order total once shipping + tax (from the ./shipping + ./tax adapters) are known. */
+export interface OrderTotalFull { subtotalCents: number; discountCents: number; shippingCents: number; taxCents: number; totalCents: number }
+
+/**
+ * Fold every component into ONE authoritative total: subtotal − discount + shipping + tax, each a non-negative whole
+ * cent and the discount never exceeding the subtotal. The single place the order total is composed once shipping (a
+ * ShippingOption) and tax (a TaxResult) are resolved — so the cart drawer, checkout summary, order record, and the
+ * Stripe charge can never disagree.
+ */
+export function composeTotal(parts: { subtotalCents: number; discountCents?: number; shippingCents?: number; taxCents?: number }): OrderTotalFull {
+  const subtotalCents = Math.max(0, Math.round(fin(parts.subtotalCents)));
+  const discountCents = Math.min(subtotalCents, Math.max(0, Math.round(fin(parts.discountCents ?? 0))));
+  const shippingCents = Math.max(0, Math.round(fin(parts.shippingCents ?? 0)));
+  const taxCents = Math.max(0, Math.round(fin(parts.taxCents ?? 0)));
+  return { subtotalCents, discountCents, shippingCents, taxCents, totalCents: subtotalCents - discountCents + shippingCents + taxCents };
+}
+
 /**
  * ANTI-TAMPERING: recompute the total from authoritative line prices + the discount and compare it to the amount
  * the client claims (e.g. a PaymentIntent amount the browser posted). Reject any mismatch beyond `toleranceCents`

package/src/shipping.ts

@@ -0,0 +1,65 @@
+/**
+ * SHIPPING — a pluggable rate-quoting adapter, so a store can swap or stack shipping providers (flat-rate now;
+ * Shippo / EasyPost / Stripe-Shipping / carrier-specific later) WITHOUT touching checkout. Like {@link ./pricing},
+ * this is pure MATH + structure; "which provider, what rates" is config the app supplies. All money is integer cents.
+ *
+ * The contract: a {@link ShippingProvider} turns a {@link ShippingInput} (the priced cart + an optional destination)
+ * into zero-or-more {@link ShippingOption}s the buyer can pick. A DIGITAL-only cart quotes nothing (free, no method).
+ */
+
+/** What a provider sees: the priced cart, which lines physically ship, and an optional destination. */
+export interface ShippingInput {
+  subtotalCents: number;
+  /** one entry per cart line; `requiresShipping` marks a physical good (absent/false ⇒ digital, never shipped). */
+  lines: { id?: string | number; qty: number; requiresShipping?: boolean }[];
+  address?: { country?: string; state?: string; postalCode?: string };
+}
+
+/** A quoted shipping method the buyer can choose. `amountCents` is integer minor units. */
+export interface ShippingOption { id: string; label: string; amountCents: number; estimate?: string }
+
+/** A swappable shipping-rate source. Implement `quote` over any carrier API; the default is {@link flatRateShipping}. */
+export interface ShippingProvider { id: string; quote(input: ShippingInput): ShippingOption[] | Promise<ShippingOption[]> }
+
+const cents = (n: number) => Math.max(0, Math.round(Number.isFinite(n) ? n : 0));
+
+/** Does the cart contain anything that physically ships? (A digital-only cart needs no shipping at all.) */
+export function cartNeedsShipping(input: ShippingInput): boolean {
+  return (input.lines ?? []).some((l) => l && l.requiresShipping);
+}
+
+/**
+ * The default provider: a single FLAT fee, optionally FREE over a subtotal threshold ("free shipping over $50").
+ * Quotes nothing for a digital-only cart, so digital orders stay free + method-less.
+ */
+export function flatRateShipping(opts: { flatCents: number; freeOverCents?: number; label?: string; id?: string }): ShippingProvider {
+  const id = opts.id ?? "flat";
+  return {
+    id,
+    quote(input) {
+      if (!cartNeedsShipping(input)) return [];
+      const free = opts.freeOverCents != null && cents(input.subtotalCents) >= cents(opts.freeOverCents);
+      return [{ id, label: opts.label ?? "Standard shipping", amountCents: free ? 0 : cents(opts.flatCents), estimate: "3–7 business days" }];
+    },
+  };
+}
+
+/** Compose several providers — the union of every provider's options (e.g. flat + an express carrier). */
+export function combineShipping(...providers: ShippingProvider[]): ShippingProvider {
+  return {
+    id: "combined",
+    async quote(input) { return (await Promise.all(providers.map((p) => p.quote(input)))).flat(); },
+  };
+}
+
+/**
+ * Resolve the buyer's CHOSEN option from a provider's quote — by id when given, else the cheapest. Returns null when
+ * the cart needs no shipping (digital-only) so the caller adds a $0 / no-method line. The server must re-resolve
+ * (never trust a client-sent amount) — pass only the chosen id.
+ */
+export async function resolveShipping(provider: ShippingProvider | null | undefined, input: ShippingInput, chosenId?: string): Promise<ShippingOption | null> {
+  if (!provider) return null;
+  const options = await provider.quote(input);
+  if (!options.length) return null;
+  return (chosenId ? options.find((o) => o.id === chosenId) : undefined) ?? options.slice().sort((a, b) => a.amountCents - b.amountCents)[0];
+}

package/src/tax.ts

@@ -0,0 +1,52 @@
+/**
+ * TAX — a pluggable tax-rule adapter, so a store can swap or layer tax logic (a flat rate now; TaxJar / Stripe Tax /
+ * jurisdiction tables / per-product rules later) WITHOUT touching checkout. Pure MATH + structure; the RULES (which
+ * rate, where, what's taxable) are config the app supplies. All money is integer cents.
+ *
+ * The contract: a {@link TaxProvider} turns a {@link TaxInput} (the taxable base + destination + lines) into a
+ * {@link TaxResult} (cents of tax, the effective rate, a label). Real tax is jurisdiction-specific — the default
+ * {@link flatRateTax} is a clearly-labeled starter placeholder; production swaps in a real provider via the same shape.
+ */
+
+/** What a tax provider sees. `subtotalCents` is the TAXABLE base (typically post-discount). */
+export interface TaxInput {
+  subtotalCents: number;
+  shippingCents?: number;
+  address?: { country?: string; state?: string; postalCode?: string };
+  /** per-line, when a provider needs item-level taxability (e.g. digital vs physical, exempt categories). */
+  lines?: { id?: string | number; qty: number; taxable?: boolean }[];
+}
+
+/** The computed tax. `rate` is the effective fraction (0.08 = 8%); `label` shows on the order summary. */
+export interface TaxResult { taxCents: number; rate?: number; label?: string }
+
+/** A swappable tax-rule source. Implement `calculate` over any rules engine; the default is {@link flatRateTax}. */
+export interface TaxProvider { id: string; calculate(input: TaxInput): TaxResult | Promise<TaxResult> }
+
+const cents = (n: number) => Math.max(0, Math.round(Number.isFinite(n) ? n : 0));
+
+/**
+ * The default provider: a single FLAT rate on the taxable base (optionally including shipping). A starter placeholder
+ * — swap for a jurisdiction-aware provider in production. `rate` is a fraction (0.08 = 8%); a non-positive rate ⇒ $0.
+ */
+export function flatRateTax(opts: { rate: number; label?: string; taxableShipping?: boolean; id?: string }): TaxProvider {
+  return {
+    id: opts.id ?? "flat",
+    calculate(input) {
+      const rate = Number.isFinite(opts.rate) && opts.rate > 0 ? opts.rate : 0;
+      const base = cents(input.subtotalCents) + (opts.taxableShipping ? cents(input.shippingCents ?? 0) : 0);
+      return { taxCents: Math.round(base * rate), rate, label: opts.label ?? "Tax" };
+    },
+  };
+}
+
+/** A no-op provider — tax-exempt, or handled externally (e.g. Stripe Tax computes it on the PaymentIntent). */
+export function noTax(): TaxProvider {
+  return { id: "none", calculate: () => ({ taxCents: 0 }) };
+}
+
+/** Resolve tax via the provider (or $0 when none configured). The server must compute this — never trust the client. */
+export async function resolveTax(provider: TaxProvider | null | undefined, input: TaxInput): Promise<TaxResult> {
+  if (!provider) return { taxCents: 0 };
+  return provider.calculate(input);
+}

package/test/shipping-tax.test.ts

@@ -0,0 +1,54 @@
+import { test, expect } from "bun:test";
+import {
+  cartNeedsShipping, flatRateShipping, combineShipping, resolveShipping,
+  flatRateTax, noTax, resolveTax, composeTotal,
+} from "../src/index";
+
+const physical = (subtotalCents: number) => ({ subtotalCents, lines: [{ qty: 1, requiresShipping: true }] });
+const digital = (subtotalCents: number) => ({ subtotalCents, lines: [{ qty: 1, requiresShipping: false }] });
+
+test("flat shipping: flat fee for a physical cart under the free threshold", async () => {
+  const p = flatRateShipping({ flatCents: 500, freeOverCents: 5000 });
+  const o = await resolveShipping(p, physical(2900));
+  expect(o?.amountCents).toBe(500);
+});
+
+test("flat shipping: FREE over the threshold", async () => {
+  const p = flatRateShipping({ flatCents: 500, freeOverCents: 5000 });
+  expect((await resolveShipping(p, physical(5000)))?.amountCents).toBe(0);
+  expect((await resolveShipping(p, physical(9900)))?.amountCents).toBe(0);
+});
+
+test("flat shipping: digital-only cart quotes nothing", async () => {
+  const p = flatRateShipping({ flatCents: 500 });
+  expect(cartNeedsShipping(digital(9900))).toBe(false);
+  expect(await resolveShipping(p, digital(9900))).toBeNull();
+});
+
+test("resolveShipping picks the chosen id, else the cheapest", async () => {
+  const p = combineShipping(
+    flatRateShipping({ flatCents: 500, id: "std", label: "Standard" }),
+    flatRateShipping({ flatCents: 1500, id: "exp", label: "Express" }),
+  );
+  expect((await resolveShipping(p, physical(2900)))?.id).toBe("std"); // cheapest by default
+  expect((await resolveShipping(p, physical(2900), "exp"))?.amountCents).toBe(1500); // honor the choice
+});
+
+test("flat tax: rate on the taxable base; shipping taxable only when opted in", async () => {
+  expect((await resolveTax(flatRateTax({ rate: 0.08 }), { subtotalCents: 2900 })).taxCents).toBe(232);
+  // taxableShipping folds shipping into the base
+  expect((await resolveTax(flatRateTax({ rate: 0.1, taxableShipping: true }), { subtotalCents: 1000, shippingCents: 500 })).taxCents).toBe(150);
+  expect((await resolveTax(flatRateTax({ rate: 0.1 }), { subtotalCents: 1000, shippingCents: 500 })).taxCents).toBe(100);
+});
+
+test("noTax + a non-positive rate yield zero", async () => {
+  expect((await resolveTax(noTax(), { subtotalCents: 9999 })).taxCents).toBe(0);
+  expect((await resolveTax(flatRateTax({ rate: 0 }), { subtotalCents: 9999 })).taxCents).toBe(0);
+});
+
+test("composeTotal folds subtotal − discount + shipping + tax, clamped", () => {
+  expect(composeTotal({ subtotalCents: 2900, discountCents: 400, shippingCents: 500, taxCents: 200 }).totalCents).toBe(3200);
+  // discount never exceeds subtotal; negatives clamp to 0
+  expect(composeTotal({ subtotalCents: 1000, discountCents: 5000 }).totalCents).toBe(0);
+  expect(composeTotal({ subtotalCents: 1000, shippingCents: -50, taxCents: NaN }).totalCents).toBe(1000);
+});