@pithy-sh/payments 0.1.0

package/src/rails/stripe/discounts.ts

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { CreatedDiscount, DiscountTerms } from "../../data/discount";
+import { PaymentsDiscountInvalidError, PaymentsProviderUnavailableError } from "../../error/errors";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import type { ListedDiscount } from "../contract";
+import { type StripeFormObject, type StripeHttpFetch, stripeHttpFetch, stripeJson } from "./api";
+
+/**
+ * Minting a discount at Stripe, from the normalized terms.
+ *
+ * Stripe models a discount as **two objects**: a Coupon, which carries the money and the duration, and a
+ * Promotion Code, which is the string a customer types and carries the redemption limit and the redeem-by
+ * date. Both are created here, in that order, because the second references the first.
+ *
+ * ## The two translations that decide whether a customer is charged correctly
+ *
+ * **Duration.** `DiscountDuration` counts **billing periods**, because that is what a customer experiences.
+ * Stripe's `duration_in_months` counts **months**. On a monthly plan they coincide, which is exactly why the
+ * mistranslation survives review: on an annual plan `12` means one year to the customer and twelve years to
+ * Stripe. So the conversion multiplies by the plan's interval, and `billingInterval` is required on the
+ * terms rather than assumed — `discounts.test.ts` pins an annual plan in both directions.
+ *
+ * **Expiry.** `redeemableUntil` means the code can no longer be *claimed*, and anyone already holding it
+ * keeps their rate. Stripe's `redeem_by` on a Promotion Code is exactly that, and deliberately not the
+ * Coupon's own `redeem_by`, which would be the same word applied one level up. A test asserts an existing
+ * redemption survives the date.
+ *
+ * ## What Stripe decides and Pithy does not
+ *
+ * Whether a code is still usable, what a discounted invoice comes to, and whether a fixed amount can apply
+ * to a given subscription. Pithy refuses a currency mismatch it can see before creation, because that
+ * failure would otherwise arrive at the customer at redemption rather than at the adopter at creation — but
+ * it computes no prices and re-checks no redemptions.
+ */
+
+/** What creating a discount needs: the key, and the transport to reach Stripe through. */
+export interface StripeDiscountOptions {
+  /** Stripe's credential block. Only `secretKey` is used here. */
+  credentials: PaymentsStripeCredentials;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+}
+
+/** A created Coupon, narrowed to its id. */
+const StripeCoupon = z.object({ id: z.string().min(1) }).loose();
+
+/** A created Promotion Code, narrowed to what an adopter needs back. */
+const StripePromotionCode = z.object({ id: z.string().min(1), code: z.string().min(1) }).loose();
+
+/**
+ * How many months Stripe should be told, for a duration this package counts in billing periods.
+ *
+ * The whole of the annual-plan defect lives in this function, which is why it is one named thing with a test
+ * against it rather than an expression inline.
+ */
+export function durationInMonths(billingPeriods: number, interval: "month" | "year"): number {
+  return interval === "year" ? billingPeriods * 12 : billingPeriods;
+}
+
+/** Create a Coupon and a Promotion Code for it, and return the code a customer will type. */
+export async function createStripeDiscount(
+  terms: DiscountTerms,
+  options: StripeDiscountOptions,
+): Promise<CreatedDiscount> {
+  const transport = options.transport ?? stripeHttpFetch;
+
+  const coupon: StripeFormObject =
+    terms.amount.kind === "percent"
+      ? { percent_off: terms.amount.percent }
+      : { amount_off: terms.amount.amountMinor, currency: terms.amount.currency };
+
+  // `once` and `forever` are Stripe's own words for the same ideas; only `repeating` needs converting.
+  coupon.duration = terms.duration.kind;
+  if (terms.duration.kind === "repeating") {
+    if (terms.billingInterval === undefined) {
+      // `DiscountTerms` refuses this combination, so reaching it means somebody built the object without
+      // parsing. Refusing here too rather than defaulting to "month": the default would be right for a
+      // monthly plan and would turn an annual one into a twelve-year discount — exactly the failure the
+      // required field exists to prevent, committed silently.
+      throw new PaymentsDiscountInvalidError({
+        detail:
+          "A repeating discount reached the Stripe rail with no `billingInterval`. Stripe counts a duration in months, so billing periods cannot be converted without it. Build terms through `DiscountTerms.parse`.",
+      });
+    }
+    coupon.duration_in_months = durationInMonths(terms.duration.billingPeriods, terms.billingInterval);
+  }
+
+  const created = await stripeJson(transport, "/coupons", {
+    what: "a discount",
+    secretKey: options.credentials.secretKey,
+    form: coupon,
+  });
+  const parsedCoupon = StripeCoupon.safeParse(created);
+  if (!parsedCoupon.success) {
+    throw new PaymentsProviderUnavailableError({ detail: "Stripe created a coupon and returned no id." });
+  }
+
+  const promotion: StripeFormObject = { coupon: parsedCoupon.data.id };
+  if (terms.code !== undefined) promotion.code = terms.code;
+  if (terms.maxRedemptions !== undefined) promotion.max_redemptions = terms.maxRedemptions;
+  // Seconds since the epoch, and on the Promotion Code rather than the Coupon: this date stops the code
+  // being *claimed*, and a customer who already redeemed it keeps their rate for its full duration.
+  if (terms.redeemableUntil !== undefined) {
+    promotion.redeem_by = Math.floor(terms.redeemableUntil.getTime() / 1000);
+  }
+
+  const madeCode = await stripeJson(transport, "/promotion_codes", {
+    what: "a discount code",
+    secretKey: options.credentials.secretKey,
+    form: promotion,
+  });
+  const parsedCode = StripePromotionCode.safeParse(madeCode);
+  if (!parsedCode.success) {
+    throw new PaymentsDiscountInvalidError({
+      detail: `Stripe created coupon ${parsedCoupon.data.id} but would not attach a promotion code to it.`,
+    });
+  }
+
+  return { code: parsedCode.data.code, providerDiscountId: parsedCode.data.id, terms };
+}
+
+/** Stripe's promotion-code list, narrowed to what a management pane shows. */
+const StripePromotionList = z
+  .object({
+    data: z.array(
+      z
+        .object({
+          id: z.string().min(1),
+          code: z.string().min(1),
+          times_redeemed: z.number().nullish(),
+          coupon: z
+            .object({
+              percent_off: z.number().nullish(),
+              amount_off: z.number().nullish(),
+              currency: z.string().nullish(),
+            })
+            .loose()
+            .nullish(),
+        })
+        .loose(),
+    ),
+  })
+  .loose();
+
+/** The promotion codes this account holds, newest first. */
+export async function listStripeDiscounts(options: StripeDiscountOptions): Promise<readonly ListedDiscount[]> {
+  const found = await stripeJson(options.transport ?? stripeHttpFetch, "/promotion_codes", {
+    what: "the discount codes",
+    secretKey: options.credentials.secretKey,
+    query: { limit: DISCOUNT_PAGE },
+  });
+  const parsed = StripePromotionList.safeParse(found);
+  if (!parsed.success) return [];
+  return parsed.data.data.map((promotion) => ({
+    code: promotion.code,
+    providerDiscountId: promotion.id,
+    amount:
+      promotion.coupon?.percent_off != null
+        ? `${promotion.coupon.percent_off}%`
+        : `${promotion.coupon?.amount_off ?? 0} ${promotion.coupon?.currency ?? ""}`.trim(),
+    redemptions: promotion.times_redeemed ?? null,
+  }));
+}
+
+/** One page of codes. A discount list is small by nature; this bounds it without inventing pagination. */
+const DISCOUNT_PAGE = 100;

package/src/rails/stripe/fixtures/event-charge-refunded.json

@@ -0,0 +1,23 @@
+{
+  "id": "evt_stripeChargeRefunded",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1768003200,
+  "livemode": true,
+  "type": "charge.refunded",
+  "data": {
+    "object": {
+      "id": "ch_1PithyCoins",
+      "object": "charge",
+      "amount": 499,
+      "amount_refunded": 499,
+      "currency": "usd",
+      "customer": "cus_PithyAda",
+      "payment_intent": "pi_1PithyCoins",
+      "refunded": true,
+      "created": 1767225600,
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada", "pithy_price_id": "price_1Coins" }
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-invoice-paid.json

@@ -0,0 +1,19 @@
+{
+  "id": "evt_stripeInvoicePaid",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1769904000,
+  "livemode": true,
+  "type": "invoice.paid",
+  "data": {
+    "object": {
+      "id": "in_1PithyAdaFeb",
+      "object": "invoice",
+      "customer": "cus_PithyAda",
+      "subscription": "sub_1PithyAdaPro",
+      "amount_paid": 999,
+      "currency": "usd",
+      "livemode": true
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-session-completed-payment.json

@@ -0,0 +1,27 @@
+{
+  "id": "evt_stripeSessionPayment",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1767225600,
+  "livemode": true,
+  "type": "checkout.session.completed",
+  "data": {
+    "object": {
+      "id": "cs_test_pithyCoins",
+      "object": "checkout.session",
+      "mode": "payment",
+      "status": "complete",
+      "payment_status": "paid",
+      "amount_total": 499,
+      "currency": "usd",
+      "customer": "cus_PithyAda",
+      "client_reference_id": "ada",
+      "payment_intent": "pi_1PithyCoins",
+      "subscription": null,
+      "created": 1767225600,
+      "expires_at": 1767312000,
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada", "pithy_price_id": "price_1Coins" }
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-session-completed-subscription.json

@@ -0,0 +1,27 @@
+{
+  "id": "evt_stripeSessionSubscription",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1767225600,
+  "livemode": true,
+  "type": "checkout.session.completed",
+  "data": {
+    "object": {
+      "id": "cs_test_pithyPro",
+      "object": "checkout.session",
+      "mode": "subscription",
+      "status": "complete",
+      "payment_status": "paid",
+      "amount_total": 999,
+      "currency": "usd",
+      "customer": "cus_PithyAda",
+      "client_reference_id": "ada",
+      "payment_intent": null,
+      "subscription": "sub_1PithyAdaPro",
+      "created": 1767225600,
+      "expires_at": 1767312000,
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada", "pithy_price_id": "price_1Abc" }
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-subscription-canceled.json

@@ -0,0 +1,43 @@
+{
+  "id": "evt_stripeSubscriptionCanceled",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1768003200,
+  "livemode": true,
+  "type": "customer.subscription.updated",
+  "data": {
+    "object": {
+      "id": "sub_1PithyAdaPro",
+      "object": "subscription",
+      "customer": "cus_PithyAda",
+      "status": "active",
+      "cancel_at_period_end": true,
+      "canceled_at": 1768003200,
+      "created": 1767225600,
+      "start_date": 1767225600,
+      "currency": "usd",
+      "latest_invoice": "in_1PithyAdaJan",
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada" },
+      "items": {
+        "object": "list",
+        "data": [
+          {
+            "id": "si_1PithyAdaPro",
+            "object": "subscription_item",
+            "quantity": 1,
+            "current_period_start": 1767225600,
+            "current_period_end": 1769904000,
+            "price": {
+              "id": "price_1Abc",
+              "object": "price",
+              "currency": "usd",
+              "unit_amount": 999,
+              "recurring": { "interval": "month", "interval_count": 1 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-subscription-created.json

@@ -0,0 +1,42 @@
+{
+  "id": "evt_stripeSubscriptionCreated",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1767225600,
+  "livemode": true,
+  "type": "customer.subscription.created",
+  "data": {
+    "object": {
+      "id": "sub_1PithyAdaPro",
+      "object": "subscription",
+      "customer": "cus_PithyAda",
+      "status": "active",
+      "cancel_at_period_end": false,
+      "created": 1767225600,
+      "start_date": 1767225600,
+      "currency": "usd",
+      "latest_invoice": "in_1PithyAdaJan",
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada" },
+      "items": {
+        "object": "list",
+        "data": [
+          {
+            "id": "si_1PithyAdaPro",
+            "object": "subscription_item",
+            "quantity": 1,
+            "current_period_start": 1767225600,
+            "current_period_end": 1769904000,
+            "price": {
+              "id": "price_1Abc",
+              "object": "price",
+              "currency": "usd",
+              "unit_amount": 999,
+              "recurring": { "interval": "month", "interval_count": 1 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/src/rails/stripe/fixtures/event-subscription-deleted.json

@@ -0,0 +1,44 @@
+{
+  "id": "evt_stripeSubscriptionDeleted",
+  "object": "event",
+  "api_version": "2025-04-30.basil",
+  "created": 1769904000,
+  "livemode": true,
+  "type": "customer.subscription.deleted",
+  "data": {
+    "object": {
+      "id": "sub_1PithyAdaPro",
+      "object": "subscription",
+      "customer": "cus_PithyAda",
+      "status": "canceled",
+      "cancel_at_period_end": true,
+      "canceled_at": 1768003200,
+      "ended_at": 1769904000,
+      "created": 1767225600,
+      "start_date": 1767225600,
+      "currency": "usd",
+      "latest_invoice": "in_1PithyAdaJan",
+      "livemode": true,
+      "metadata": { "pithy_account_reference": "ada" },
+      "items": {
+        "object": "list",
+        "data": [
+          {
+            "id": "si_1PithyAdaPro",
+            "object": "subscription_item",
+            "quantity": 1,
+            "current_period_start": 1767225600,
+            "current_period_end": 1769904000,
+            "price": {
+              "id": "price_1Abc",
+              "object": "price",
+              "currency": "usd",
+              "unit_amount": 999,
+              "recurring": { "interval": "month", "interval_count": 1 }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/src/rails/stripe/fixtures/events.ts

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { StripeHttpFetch, StripeHttpRequest } from "../api";
+
+/**
+ * Test material for Stripe's rail: a known signing secret, a real HMAC over real bytes, and a transport that
+ * answers the way Stripe's API does.
+ *
+ * Stripe's authenticity proof is symmetric — the same secret signs and verifies — so a test can produce a
+ * genuinely valid `Stripe-Signature` header rather than stubbing the verifier. That is the whole point: the
+ * negative cases below are real failures of real cryptography. A tampered body produces a signature that does
+ * not match because the bytes changed, not because a mock was told to say no.
+ *
+ * The recorded event payloads live beside this module as JSON, unsigned, because a signature is over the exact
+ * bytes a test sends — so it must be computed at send time and cannot be recorded.
+ *
+ * This module signs; the shipped code only verifies. That is why it lives under `fixtures/`.
+ */
+
+/**
+ * The signing secret every Stripe suite uses. Shaped like Stripe's own (`whsec_` + base64-ish) so a test that
+ * accidentally logged it would be recognizable, and obviously fake so nobody mistakes it for a real one.
+ */
+export const STRIPE_TEST_WEBHOOK_SECRET = "whsec_pithyTestSigningSecretNotARealOne00";
+
+/** The secret key the API fixtures pretend to call Stripe with. Test-mode shaped, and not a real key. */
+export const STRIPE_TEST_SECRET_KEY = "sk_test_pithyTestKeyNotARealOne00";
+
+/** What a test varies about the signature header. */
+export interface StripeSignatureOptions {
+  /** The signing secret. The suite's own unless a case is proving a wrong one is refused. */
+  secret?: string;
+  /** The timestamp the header claims and the signature covers. Defaults to the clock the case passes in. */
+  timestamp?: Date;
+  /** The scheme label. `v1` unless a case is proving an unknown scheme is not accepted. */
+  scheme?: string;
+  /** Extra signature values to list before the real one — how Stripe presents a secret mid-rotation. */
+  extra?: readonly string[];
+}
+
+/** Hex, lower case — the encoding Stripe puts a `v1` signature in. */
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Sign a body the way Stripe signs a webhook delivery: HMAC-SHA256 over `<timestamp>.<body>`, keyed with the
+ * endpoint's signing secret, presented as `t=<timestamp>,v1=<hex>`.
+ *
+ * The timestamp is inside the signed payload as well as beside it, which is what makes the replay window real:
+ * a delivery cannot be re-dated without invalidating its own signature.
+ */
+export async function stripeSignatureHeader(
+  body: string,
+  now: Date,
+  options: StripeSignatureOptions = {},
+): Promise<string> {
+  const timestamp = Math.floor((options.timestamp ?? now).getTime() / 1000);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(options.secret ?? STRIPE_TEST_WEBHOOK_SECRET) as unknown as ArrayBuffer,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = new Uint8Array(
+    await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${body}`) as unknown as ArrayBuffer),
+  );
+  const values = [...(options.extra ?? []), hex(signature)];
+  return [`t=${timestamp}`, ...values.map((value) => `${options.scheme ?? "v1"}=${value}`)].join(",");
+}
+
+/** One recorded outbound call, so a suite can assert what left the Worker and not only what came back. */
+export interface StripeRecordedCall {
+  /** The full URL, query string included. */
+  url: string;
+  /** The request as the transport received it. */
+  init?: StripeHttpRequest;
+}
+
+/** What the stub answers with. A status alone is a failure; a body alone is a 200. */
+export interface StripeStubAnswer {
+  /** The status to answer with. 200 unless a case is proving a failure path. */
+  status?: number;
+  /** The JSON body. Absent answers `{}`. */
+  body?: unknown;
+}
+
+/**
+ * A transport that answers Stripe's endpoints from a table keyed on a path fragment, recording every call.
+ *
+ * A fragment rather than a full URL because a retrieve carries an id and a query string, and a test that had to
+ * spell those out would be asserting its own string building. An unmatched call is a 404, which is the honest
+ * answer for an endpoint the case did not stub.
+ */
+export function stripeStubTransport(
+  answers: Record<string, StripeStubAnswer>,
+  calls: StripeRecordedCall[] = [],
+): StripeHttpFetch {
+  return async (url, init) => {
+    calls.push({ url, init });
+    const matched = Object.entries(answers).find(([fragment]) => url.includes(fragment))?.[1];
+    const status = matched?.status ?? (matched === undefined ? 404 : 200);
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      text: async () => JSON.stringify(matched?.body ?? {}),
+    };
+  };
+}