@suluk/stripe 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/stripe",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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,
+  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 AmountVerdict,
+  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,
@@ -22,3 +31,7 @@ export {
   type StripeCheckoutLike, type PaymentMethodLike, type PaymentIntentLike,
 } from "./checkout";
 export { webhookRouter, STRIPE_EVENTS, type WebhookRouter, type WebhookHandler, type HandleResult } from "./webhook";
+// SDK-free edge webhook verification (Web Crypto) — one verifier for dev + Workers prod, no `stripe` SDK.
+export { verifyStripeSignature, timingSafeHexEqual, type VerifyOptions } from "./webhook-verify";
+// the StripeLike fetch impl (Workers-safe) + read surface for webhook PI→order resolution + refund checks.
+export { restStripe, toForm, stripeGet, retrievePaymentIntent, type RestStripeOptions } from "./rest";

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/rest.ts

@@ -0,0 +1,76 @@
+/**
+ * A {@link StripeLike} client over the Stripe REST API (fetch only — no SDK), so the @suluk/stripe helpers
+ * (setupUsageBilling / stripeProvider / reportCostUsage / subscriptions) run on a Cloudflare Worker or any fetch
+ * runtime. Stripe's API is form-encoded with bracket notation for nested params; {@link toForm} flattens the param
+ * objects the helpers build. Plus the read surface ({@link stripeGet} / {@link retrievePaymentIntent}) the edge needs
+ * for webhook PaymentIntent→order resolution and refund-state checks. `fetch` is injectable for testing.
+ */
+import type { StripeLike } from "./types";
+
+type FetchLike = typeof fetch;
+export interface RestStripeOptions { fetch?: FetchLike }
+
+/** Flatten a params object into Stripe's bracket form-encoding (recurse objects + arrays). */
+export function toForm(obj: Record<string, unknown>, prefix = "", form = new URLSearchParams()): URLSearchParams {
+  for (const [k, v] of Object.entries(obj)) {
+    if (v == null) continue;
+    const key = prefix ? `${prefix}[${k}]` : k;
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => {
+        if (item && typeof item === "object") toForm(item as Record<string, unknown>, `${key}[${i}]`, form);
+        else form.append(`${key}[${i}]`, String(item));
+      });
+    } else if (typeof v === "object") {
+      toForm(v as Record<string, unknown>, key, form);
+    } else {
+      form.append(key, String(v));
+    }
+  }
+  return form;
+}
+
+/** A duck-typed Stripe client backed by the REST API. `key` is the secret key. */
+export function restStripe(key: string, opts: RestStripeOptions = {}): StripeLike {
+  const f = opts.fetch ?? fetch;
+  const post = async (path: string, params: Record<string, unknown>): Promise<any> => { // eslint-disable-line @typescript-eslint/no-explicit-any
+    const res = await f(`https://api.stripe.com/v1/${path}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${key}`, "content-type": "application/x-www-form-urlencoded" },
+      body: toForm(params).toString(),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error((json as { error?: { message?: string } })?.error?.message ?? `Stripe ${path} failed (${res.status})`);
+    return json;
+  };
+  return {
+    customers: { create: (p) => post("customers", p) },
+    products: { create: (p) => post("products", p) },
+    prices: { create: (p) => post("prices", p) },
+    subscriptions: { create: (p) => post("subscriptions", p) },
+    billing: {
+      meters: { create: (p) => post("billing/meters", p) },
+      meterEvents: { create: (p) => post("billing/meter_events", p) },
+    },
+    billingPortal: { sessions: { create: (p) => post("billing_portal/sessions", p) } },
+    // verifyWebhook isn't used by the REST adapter (the edge uses verifyStripeSignature) — stub to satisfy the type.
+    webhooks: { constructEvent: () => { throw new Error("constructEvent not supported by the REST adapter; use verifyStripeSignature"); } },
+  } as StripeLike;
+}
+
+/** Low-level authenticated GET → parsed JSON (null on non-OK / parse error). */
+export async function stripeGet<T = unknown>(key: string, path: string, opts: RestStripeOptions = {}): Promise<T | null> {
+  if (!key) return null;
+  const f = opts.fetch ?? fetch;
+  try {
+    const r = await f(`https://api.stripe.com/v1/${path}`, { headers: { authorization: `Bearer ${key}` } });
+    if (!r.ok) return null;
+    return (await r.json().catch(() => null)) as T | null;
+  } catch { return null; }
+}
+
+/** Retrieve a PaymentIntent, optionally expanding fields (e.g. `latest_charge`). Returns null if unresolvable. */
+export async function retrievePaymentIntent<T = Record<string, unknown>>(key: string, id: string, opts: RestStripeOptions & { expand?: string[] } = {}): Promise<T | null> {
+  if (!id) return null;
+  const q = (opts.expand ?? []).map((e) => `expand[]=${encodeURIComponent(e)}`).join("&");
+  return stripeGet<T>(key, `payment_intents/${encodeURIComponent(id)}${q ? "?" + q : ""}`, opts);
+}

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/src/webhook-verify.ts

@@ -0,0 +1,40 @@
+/**
+ * SDK-free Stripe webhook signature verification (Web Crypto HMAC-SHA256) — runs on Workers / Bun / Node 18+ with
+ * NO `stripe` SDK. The edge leaf: prove a webhook payload is authentic AND fresh before dispatching it (e.g. via
+ * {@link webhookRouter}). `stripeProvider.verifyWebhook` (the SDK's constructEvent) stays for SDK callers; this is
+ * the binding-free path, so a dev server and a Workers prod runtime can share ONE verifier instead of diverging.
+ */
+
+/** Constant-time hex-string compare (no early-out) — guards the signature check against timing oracles. */
+export function timingSafeHexEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+export interface VerifyOptions {
+  /** current unix seconds (default `Date.now()/1000`) — injectable for tests + replay-window tuning. */
+  now?: () => number;
+  /** reject events whose timestamp is older than this many seconds (default 300 — Stripe's window). */
+  toleranceSec?: number;
+}
+
+/**
+ * Verify a Stripe `stripe-signature` header against the raw request body + the endpoint signing secret.
+ * Returns true iff a v1 signature matches the HMAC of `${t}.${rawBody}` AND the timestamp is within tolerance.
+ * Pass the RAW (unparsed) body — re-serializing JSON changes the bytes and breaks the HMAC.
+ */
+export async function verifyStripeSignature(rawBody: string, sigHeader: string, secret: string, opts: VerifyOptions = {}): Promise<boolean> {
+  if (!rawBody || !sigHeader || !secret) return false;
+  const parts: Record<string, string> = {};
+  for (const p of sigHeader.split(",")) { const i = p.indexOf("="); if (i > 0 && !(p.slice(0, i) in parts)) parts[p.slice(0, i)] = p.slice(i + 1); } // split on the FIRST '=' only
+  const ts = Number(parts.t);
+  if (!parts.t || !parts.v1 || !Number.isFinite(ts)) return false;
+  const now = (opts.now ?? (() => Date.now() / 1000))();
+  if (Math.abs(now - ts) > (opts.toleranceSec ?? 300)) return false; // reject stale/replayed events (Stripe's 5-min window)
+  const keyData = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", keyData, new TextEncoder().encode(`${ts}.${rawBody}`));
+  const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return timingSafeHexEqual(expected, parts.v1);
+}

package/test/rest.test.ts

@@ -0,0 +1,47 @@
+/**
+ * rest.ts — the Workers-safe StripeLike fetch impl. Pins toForm's bracket encoding (the load-bearing form-encoder
+ * the helpers rely on) + the read surface (retrievePaymentIntent) over an injected fetch.
+ */
+import { test, expect, describe } from "bun:test";
+import { toForm, restStripe, retrievePaymentIntent, stripeGet } from "../src/index";
+
+describe("toForm", () => {
+  test("flattens scalars, nested objects, and arrays into Stripe bracket notation", () => {
+    const f = toForm({ email: "a@b.com", metadata: { orderId: 7 }, items: [{ price: "p_1", qty: 2 }] });
+    expect(f.get("email")).toBe("a@b.com");
+    expect(f.get("metadata[orderId]")).toBe("7");
+    expect(f.get("items[0][price]")).toBe("p_1");
+    expect(f.get("items[0][qty]")).toBe("2");
+  });
+  test("drops null/undefined", () => {
+    const f = toForm({ a: 1, b: null, c: undefined });
+    expect(f.has("b")).toBe(false);
+    expect(f.has("c")).toBe(false);
+    expect(f.get("a")).toBe("1");
+  });
+});
+
+describe("rest read surface (injected fetch)", () => {
+  const mockFetch = (status: number, body: unknown) => (async () => new Response(JSON.stringify(body), { status })) as unknown as typeof fetch;
+
+  test("retrievePaymentIntent returns the parsed PI + builds the expand query", async () => {
+    let seenUrl = "";
+    const fetch = (async (url: string) => { seenUrl = url; return new Response(JSON.stringify({ id: "pi_1", metadata: { orderId: "42" } }), { status: 200 }); }) as unknown as typeof fetch;
+    const pi = await retrievePaymentIntent<{ metadata?: { orderId?: string } }>("sk_test", "pi_1", { expand: ["latest_charge"], fetch });
+    expect(pi?.metadata?.orderId).toBe("42");
+    expect(seenUrl).toContain("/payment_intents/pi_1");
+    expect(seenUrl).toContain("expand[]=latest_charge");
+  });
+
+  test("stripeGet returns null on non-OK", async () => {
+    expect(await stripeGet("sk_test", "payment_intents/x", { fetch: mockFetch(404, { error: {} }) })).toBeNull();
+  });
+
+  test("restStripe.customers.create posts form-encoded + parses the result", async () => {
+    let body = "";
+    const fetch = (async (_url: string, init: RequestInit) => { body = String(init.body); return new Response(JSON.stringify({ id: "cus_1" }), { status: 200 }); }) as unknown as typeof fetch;
+    const r = await restStripe("sk_test", { fetch }).customers.create({ email: "a@b.com" });
+    expect((r as { id: string }).id).toBe("cus_1");
+    expect(body).toContain("email=a%40b.com");
+  });
+});

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);
+});

package/test/webhook-verify.test.ts

@@ -0,0 +1,58 @@
+/**
+ * verifyStripeSignature — the SDK-free Web-Crypto webhook verifier. Pins a known-good signature (computed with the
+ * same HMAC the verifier checks), a stale-timestamp rejection, and a tampered-body rejection. The constant-time
+ * compare must have no early-out. These pin the behavior BEFORE dev + prod adopt this one verifier.
+ */
+import { test, expect, describe } from "bun:test";
+import { verifyStripeSignature, timingSafeHexEqual } from "../src/index";
+
+const SECRET = "whsec_test_secret";
+const BODY = JSON.stringify({ id: "evt_1", type: "checkout.session.completed", data: { object: { id: "cs_1" } } });
+
+/** Build a valid `stripe-signature` header (t=<ts>,v1=<HMAC-SHA256(`${ts}.${body}`)>) the way Stripe does. */
+async function sign(body: string, secret: string, ts: number): Promise<string> {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${ts}.${body}`));
+  const v1 = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `t=${ts},v1=${v1}`;
+}
+
+describe("verifyStripeSignature", () => {
+  const now = () => 1_700_000_000; // fixed clock
+
+  test("accepts a fresh, correctly-signed payload", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now })).toBe(true);
+  });
+
+  test("rejects a stale timestamp beyond tolerance (replay)", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000 - 600); // 10 min old, tolerance 300
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now })).toBe(false);
+  });
+
+  test("rejects a tampered body (HMAC mismatch)", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY + " ", sig, SECRET, { now })).toBe(false);
+  });
+
+  test("rejects a wrong secret, a missing v1, and empty inputs", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000);
+    expect(await verifyStripeSignature(BODY, sig, "whsec_wrong", { now })).toBe(false);
+    expect(await verifyStripeSignature(BODY, "t=1700000000", SECRET, { now })).toBe(false);
+    expect(await verifyStripeSignature("", sig, SECRET, { now })).toBe(false);
+  });
+
+  test("honors an injected tolerance window", async () => {
+    const sig = await sign(BODY, SECRET, 1_700_000_000 - 60);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now, toleranceSec: 30 })).toBe(false);
+    expect(await verifyStripeSignature(BODY, sig, SECRET, { now, toleranceSec: 120 })).toBe(true);
+  });
+});
+
+describe("timingSafeHexEqual", () => {
+  test("true on equal, false on differing same-length and differing-length", () => {
+    expect(timingSafeHexEqual("deadbeef", "deadbeef")).toBe(true);
+    expect(timingSafeHexEqual("deadbeef", "deadbef0")).toBe(false);
+    expect(timingSafeHexEqual("dead", "deadbeef")).toBe(false);
+  });
+});