@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/server/take-back.ts

@@ -0,0 +1,190 @@
+// Taking back what one grant added, shared by a provider refund (`refundPayment`) and an admin's
+// revoke (`revokeManualGrant`): a period loses its unused days (a partial refund only its share of
+// them) and every period stored after it moves back by as many days, in both tables (provider
+// payments and manual grants), so their stored dates keep saying where their access lies; a
+// lifetime ends unless something else still pays for it (a partial refund never ends it). Lock order: the caller takes the account (key share), then the entitlement
+// (`lockEntitlementRow`), then flips its own row; the shift then updates other rows under the
+// entitlement lock, so two take-backs of one account never wait on each other's rows. A refund that
+// fails later gives days back (`giveBackDays`) the same way in reverse.
+import type { Queryable } from "@softure-ai/db";
+import { and, eq, gte, ne, type SQL } from "drizzle-orm";
+import type { Entitlement, EntitlementEvent, EntitlementRecord, PaymentGrant } from "../contract.js";
+import { resolveEntitlement } from "../entitlement.js";
+import { getGrantStart, getRefundEvent, getTakenBackDays, isFullShare, moveBackByDays, moveForwardByDays, type RefundShare } from "../refund.js";
+import { entitlements, manualGrants, payments } from "../schema.js";
+import { changeEntitlement, findEntitlementRecord, type BillingContext } from "./entitlements.js";
+import { getEntitlementPolicy } from "./options.js";
+
+/**
+ * Locks the account's entitlement row until the transaction ends (nothing when it has none yet:
+ * a check that must hold before the first change pins the row first, `pinEntitlementRow`).
+ * Taken before a refund's or a revoke's own row, so every take-back of the account queues here.
+ */
+export async function lockEntitlementRow(tx: Queryable, userId: string): Promise<void> {
+  await tx.select({ userId: entitlements.userId }).from(entitlements).where(eq(entitlements.userId, userId)).for("update");
+}
+
+/** Whether a paid payment of the account (other than `exceptId`) bought lifetime access. */
+export async function hasPaidLifetimePayment(tx: Queryable, userId: string, exceptId?: string): Promise<boolean> {
+  const conditions: SQL[] = [eq(payments.userId, userId), eq(payments.grantKind, "lifetime"), eq(payments.status, "paid")];
+  if (exceptId !== undefined) conditions.push(ne(payments.id, exceptId));
+  const [other] = await tx.select({ id: payments.id }).from(payments).where(and(...conditions)).limit(1);
+  return other !== undefined;
+}
+
+/** Whether an active manual grant of the account (other than `exceptId`) gave lifetime access. */
+export async function hasActiveManualLifetime(tx: Queryable, userId: string, exceptId?: string): Promise<boolean> {
+  const conditions: SQL[] = [eq(manualGrants.userId, userId), eq(manualGrants.grantKind, "lifetime"), eq(manualGrants.status, "active")];
+  if (exceptId !== undefined) conditions.push(ne(manualGrants.id, exceptId));
+  const [other] = await tx.select({ id: manualGrants.id }).from(manualGrants).where(and(...conditions)).limit(1);
+  return other !== undefined;
+}
+
+export interface ShiftLaterPeriodsInput {
+  readonly userId: string;
+  /** Stored periods starting at or after this instant move (the end of the period taken back or given back). */
+  readonly after: Date;
+  readonly days: number;
+  /** `back` when days are taken back, `forward` when a failed refund gives them back. */
+  readonly direction: "back" | "forward";
+  readonly timezone: string;
+}
+
+interface StoredPeriod {
+  readonly id: string;
+  readonly grantedFrom: Date | null;
+  readonly grantedUntil: Date | null;
+}
+
+/** The stored period moved by `days` local days in the input's direction. */
+function getShiftedPeriod(row: StoredPeriod, input: ShiftLaterPeriodsInput): { grantedFrom: Date; grantedUntil: Date } | null {
+  if (row.grantedFrom === null || row.grantedUntil === null) return null;
+  const days = input.direction === "back" ? input.days : -input.days;
+  return { grantedFrom: moveBackByDays(row.grantedFrom, days, input.timezone), grantedUntil: moveBackByDays(row.grantedUntil, days, input.timezone) };
+}
+
+/**
+ * Moves the stored periods that follow the one taken back or given back (paid provider payments and
+ * active manual grants starting at or after `after`) by the days, so a later refund or revoke of one
+ * of them takes back the right days. The caller holds the entitlement lock.
+ */
+export async function shiftLaterPeriods(tx: Queryable, input: ShiftLaterPeriodsInput): Promise<void> {
+  const laterPayments = await tx
+    .select({ id: payments.id, grantedFrom: payments.grantedFrom, grantedUntil: payments.grantedUntil })
+    .from(payments)
+    .where(and(eq(payments.userId, input.userId), eq(payments.grantKind, "period"), eq(payments.status, "paid"), gte(payments.grantedFrom, input.after)));
+  for (const row of laterPayments) {
+    const shifted = getShiftedPeriod(row, input);
+    if (shifted !== null) await tx.update(payments).set(shifted).where(eq(payments.id, row.id));
+  }
+  const laterGrants = await tx
+    .select({ id: manualGrants.id, grantedFrom: manualGrants.grantedFrom, grantedUntil: manualGrants.grantedUntil })
+    .from(manualGrants)
+    .where(and(eq(manualGrants.userId, input.userId), eq(manualGrants.grantKind, "period"), eq(manualGrants.status, "active"), gte(manualGrants.grantedFrom, input.after)));
+  for (const row of laterGrants) {
+    const shifted = getShiftedPeriod(row, input);
+    if (shifted !== null) await tx.update(manualGrants).set(shifted).where(eq(manualGrants.id, row.id));
+  }
+}
+
+export interface TakeBackGrantInput {
+  readonly userId: string;
+  /** What the refunded payment or revoked grant added; null for a payment stored before grants were (revokes paid access). */
+  readonly grant: PaymentGrant | null;
+  readonly now: Date;
+  /** Whether something else still pays for lifetime access; asked under the entitlement lock. */
+  readonly hasOtherLifetime: () => Promise<boolean>;
+  /** The part of a payment a partial refund returns; omitted to take back the whole grant. */
+  readonly share?: RefundShare;
+}
+
+/** Where the account stands after a take-back, and the local days its period lost (0 when nothing moved). */
+export interface TakeBack {
+  readonly entitlement: Entitlement;
+  readonly days: number;
+}
+
+/** The change taking back `grant` makes, decided under the entitlement lock, or null when it takes nothing back. */
+async function getTakeBackEvent(ctx: BillingContext, input: TakeBackGrantInput, record: EntitlementRecord): Promise<EntitlementEvent | null> {
+  const { grant, share } = input;
+  // A partial refund of a payment without a recorded grant, or of a lifetime, takes nothing back.
+  if (!isFullShare(share) && grant?.kind !== "period") return null;
+  if (grant === null) return { type: "revoke" };
+  if (grant.kind === "lifetime" && (await input.hasOtherLifetime())) return null;
+  return getRefundEvent(record, grant, { now: input.now, timezone: ctx.config.timezone, share });
+}
+
+/**
+ * Takes back what one grant added (its share, for a partial refund), inside the caller's transaction
+ * (`ctx.db` is it), and returns where the account stands after and how many days its period lost.
+ * The caller locked the account and the entitlement (`lockEntitlementRow`) and flipped its row
+ * first: a lifetime granted at the same time is either committed and seen below, or waits for the
+ * entitlement lock and is applied after.
+ */
+export async function takeBackGrant(ctx: BillingContext, input: TakeBackGrantInput): Promise<TakeBack> {
+  const tx = ctx.db;
+  const record = await findEntitlementRecord(ctx, input.userId);
+  // The caller's row references the account, which its key share lock keeps.
+  if (record === null) throw new Error("@softure-ai/billing: a grant to take back has no account");
+  const event = await getTakeBackEvent(ctx, input, record);
+  if (event === null) return { entitlement: resolveEntitlement(record, input.now, getEntitlementPolicy(ctx.config)), days: 0 };
+  const { grant } = input;
+  const { timezone } = ctx.config;
+  let days = 0;
+  if (grant?.kind === "period") {
+    days = getTakenBackDays(grant, { now: input.now, timezone, share: input.share });
+    await shiftLaterPeriods(tx, { userId: input.userId, after: grant.until, days, direction: "back", timezone });
+  }
+  const changed = await changeEntitlement(ctx, input.userId, event);
+  // The account is locked and these events are never refused.
+  if (!changed.ok) throw new Error(`@softure-ai/billing: taking back a grant failed with ${changed.error}`);
+  return { entitlement: changed.value, days };
+}
+
+export interface GiveBackDaysInput {
+  readonly userId: string;
+  /** The period the refunded payment stores now. */
+  readonly grant: Extract<PaymentGrant, { kind: "period" }>;
+  /** Whether the payment was still paid (refunded in part) before the failure. */
+  readonly isPaid: boolean;
+  readonly days: number;
+  readonly now: Date;
+}
+
+/** Where the account stands after days were given back, and the period the payment pays for now. */
+export interface GiveBack {
+  readonly entitlement: Entitlement;
+  readonly period: Extract<PaymentGrant, { kind: "period" }>;
+}
+
+/**
+ * Gives back `days` local days a failed refund had taken, inside the caller's transaction, under the
+ * same locks as `takeBackGrant`. While the payment is paid and its period still ahead, the days go
+ * back right after that period: dated access and every later stored period move forward by them
+ * (the take-back in reverse). Otherwise (refunded in full, or the period used up) they are a grant
+ * at the end, from the latest of the trial's end, dated access and now, and that is the period the
+ * payment pays for.
+ */
+export async function giveBackDays(ctx: BillingContext, input: GiveBackDaysInput): Promise<GiveBack> {
+  const record = await findEntitlementRecord(ctx, input.userId);
+  // The caller's payment row references the account, which its key share lock keeps.
+  if (record === null) throw new Error("@softure-ai/billing: days to give back have no account");
+  const { timezone } = ctx.config;
+  const { grant, days, now } = input;
+  const { paidUntil } = record;
+  let period: GiveBack["period"];
+  let until: Date;
+  if (input.isPaid && grant.until > now && paidUntil !== null && paidUntil >= grant.until) {
+    await shiftLaterPeriods(ctx.db, { userId: input.userId, after: grant.until, days, direction: "forward", timezone });
+    period = { kind: "period", from: grant.from, until: moveForwardByDays(grant.until, days, timezone) };
+    until = moveForwardByDays(paidUntil, days, timezone);
+  } else {
+    const from = getGrantStart(record, now);
+    until = moveForwardByDays(from, days, timezone);
+    period = { kind: "period", from, until };
+  }
+  const changed = await changeEntitlement(ctx, input.userId, { type: "grant", until });
+  // The account is locked and the end lies at least a day past dated access and now.
+  if (!changed.ok) throw new Error(`@softure-ai/billing: giving back refunded days failed with ${changed.error}`);
+  return { entitlement: changed.value, period };
+}

package/src/server/user-id.ts

@@ -0,0 +1,12 @@
+// Account ids are auth's uuids, and the module's own rows use uuids too; anything else names no row
+// and is answered without a query (Postgres would refuse to compare it with a uuid column).
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Whether `value` can be a row id (a uuid). */
+export function isUuid(value: string): boolean {
+  return UUID.test(value);
+}
+
+export function isUserId(value: string): boolean {
+  return isUuid(value);
+}

package/src/stripe-currency.ts

@@ -0,0 +1,65 @@
+// Stripe's unit for an amount (https://docs.stripe.com/currencies, read 2026-10-04): the minor unit
+// of a two-decimal currency unless Stripe lists the currency as zero- or three-decimal. Billing keeps
+// every amount in the minor unit it pins (`src/currency-digits.ts`, ISO 4217); the two differ where
+// ISO has no minor unit and Stripe keeps one (ISK and UGX, Stripe's "special cases") or ISO has three
+// decimals Stripe does not take (IQD, LYD), so the adapter converts at its boundary: amounts sent to
+// Checkout, and amounts the webhook reads back.
+import type { PlanPrice } from "./contract.js";
+import { getMinorUnitDigits } from "./price.js";
+
+/**
+ * Charged without a minor unit. UGX is not here: Stripe still takes it as a two-decimal value whose
+ * decimals are always 00 (as ISK). The guide's text export omits the list; this is Stripe's
+ * long-standing list, which the guide's index matches.
+ */
+export const STRIPE_ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BIF", "CLP", "DJF", "GNF", "JPY", "KMF", "KRW", "MGA", "PYG", "RWF", "VND", "VUV", "XAF", "XOF", "XPF",
+]);
+
+/**
+ * Charged with three decimals, and the last one must be 0 (Stripe's earlier guide; the current
+ * text export omits the section).
+ */
+export const STRIPE_THREE_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set(["BHD", "JOD", "KWD", "OMR", "TND"]);
+
+/** Digits of the unit Stripe takes for `currency` (ISO 4217, upper case): 0, 2 or 3. */
+export function getStripeMinorUnitDigits(currency: string): number {
+  if (STRIPE_ZERO_DECIMAL_CURRENCIES.has(currency)) return 0;
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(currency)) return 3;
+  return 2;
+}
+
+/** How many digits Stripe's unit has beyond billing's (negative when it has fewer). */
+function getDigitShift(currency: string): number {
+  return getStripeMinorUnitDigits(currency) - getMinorUnitDigits(currency);
+}
+
+/**
+ * The price as Stripe's `unit_amount`, e.g. ISK 1,500 (`amount: 1500`) as 150000; null when Stripe
+ * cannot charge it exactly (a fraction of Stripe's unit, or a three-decimal amount not ending in 0).
+ */
+export function toStripeAmount(price: PlanPrice): number | null {
+  const shift = getDigitShift(price.currency);
+  const amount = shift >= 0 ? price.amount * 10 ** shift : price.amount / 10 ** -shift;
+  if (!Number.isInteger(amount)) return null;
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(price.currency) && amount % 10 !== 0) return null;
+  return amount;
+}
+
+/**
+ * An amount Stripe reports (a checkout's total, a charge's refunded total) in billing's unit,
+ * rounded down when it is not whole, so a refunded total is never over-counted.
+ */
+export function fromStripeAmount(amount: number, currency: string): number {
+  const shift = getDigitShift(currency);
+  return shift >= 0 ? Math.floor(amount / 10 ** shift) : amount * 10 ** -shift;
+}
+
+/** Why Stripe cannot charge `price` exactly, for the config error; null when it can. */
+export function describeStripePriceProblem(price: PlanPrice): string | null {
+  if (toStripeAmount(price) !== null) return null;
+  if (STRIPE_THREE_DECIMAL_CURRENCIES.has(price.currency)) {
+    return `stripe() charges ${price.currency} in multiples of 10 of its minor unit; round the amount to end in 0`;
+  }
+  return `stripe() charges ${price.currency} with ${String(getStripeMinorUnitDigits(price.currency))} decimals; the amount must be a whole number of them`;
+}

package/src/stripe-webhook.ts

@@ -0,0 +1,278 @@
+// Stripe webhooks, pure: the `Stripe-Signature` check and the events billing acts on, narrowed with
+// zod. Stripe signs `<timestamp>.<raw body>` with HMAC-SHA256 under the endpoint's secret
+// (https://docs.stripe.com/webhooks#verify-manually); a timestamp older or newer than the tolerance
+// is a replay and fails like a wrong signature. Nothing here touches the database.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import { z } from "zod";
+import { fromStripeAmount } from "./stripe-currency.js";
+
+/** The header Stripe signs every delivery with (lower case, as `Headers` returns it). */
+export const STRIPE_SIGNATURE_HEADER = "stripe-signature";
+/** How far a delivery's timestamp may be from now, in seconds: Stripe's default replay window. */
+export const STRIPE_SIGNATURE_TOLERANCE_SECONDS = 300;
+/** The metadata keys a checkout session carries (`stripe()` sets them). */
+export const STRIPE_METADATA = { userId: "softure_user_id", planId: "softure_plan_id" } as const;
+
+export type StripeWebhookError = "billing.webhook_invalid";
+
+/** The longest id billing stores; Stripe's ids are far shorter. */
+const MAX_ID_LENGTH = 255;
+const SIGNATURE_PATTERN = /^[0-9a-f]{64}$/;
+
+function sign(secret: string, timestamp: number, payload: string): string {
+  return createHmac("sha256", secret).update(`${String(timestamp)}.${payload}`, "utf8").digest("hex");
+}
+
+export interface SignStripePayloadInput {
+  readonly payload: string;
+  readonly secret: string;
+  /** Unix seconds. */
+  readonly timestamp: number;
+}
+
+/** A `Stripe-Signature` value as Stripe sends it, e.g. for a test that plays Stripe. */
+export function signStripePayload({ payload, secret, timestamp }: SignStripePayloadInput): string {
+  return `t=${String(timestamp)},v1=${sign(secret, timestamp, payload)}`;
+}
+
+export interface VerifyStripeSignatureInput {
+  readonly payload: string;
+  /** The `Stripe-Signature` header, or null when the request had none. */
+  readonly header: string | null;
+  readonly secret: string;
+  readonly now: Date;
+  readonly toleranceSeconds?: number;
+}
+
+/**
+ * Whether Stripe signed `payload` with `secret` within the tolerance of `now`. Any `v1` entry may
+ * match: Stripe sends one per secret while an old secret is still rolling off.
+ */
+export function verifyStripeSignature(input: VerifyStripeSignatureInput): Ok<undefined> | Err<StripeWebhookError> {
+  const { payload, header, secret, now } = input;
+  const tolerance = input.toleranceSeconds ?? STRIPE_SIGNATURE_TOLERANCE_SECONDS;
+  if (header === null || secret === "") return err("billing.webhook_invalid");
+
+  let timestamp: number | null = null;
+  const signatures: string[] = [];
+  for (const part of header.split(",")) {
+    const separator = part.indexOf("=");
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (key === "t" && /^\d{1,12}$/.test(value)) timestamp = Number(value);
+    if (key === "v1" && SIGNATURE_PATTERN.test(value)) signatures.push(value);
+  }
+  if (timestamp === null || signatures.length === 0) return err("billing.webhook_invalid");
+  if (Math.abs(Math.floor(now.getTime() / 1000) - timestamp) > tolerance) return err("billing.webhook_invalid");
+
+  const expected = Buffer.from(sign(secret, timestamp, payload), "hex");
+  const isSigned = signatures.some((signature) => timingSafeEqual(Buffer.from(signature, "hex"), expected));
+  return isSigned ? ok() : err("billing.webhook_invalid");
+}
+
+/** A checkout Stripe reports as paid, with what `stripe()` put in its metadata. */
+export interface PaidCheckout {
+  /** The Checkout Session id (`cs_...`). */
+  readonly checkoutId: string;
+  /** The PaymentIntent id (`pi_...`) refunds name; null for a checkout without a charge. */
+  readonly paymentId: string | null;
+  readonly userId: string;
+  readonly planId: string;
+  /** What Stripe charged, in billing's unit (the pinned minor unit, converted from Stripe's). */
+  readonly amount: number;
+  /** ISO 4217, upper case. */
+  readonly currency: string;
+}
+
+/** A refund Stripe reports as failed or canceled: its money is back with the customer's payment. */
+export interface FailedRefund {
+  /** The PaymentIntent id (`pi_...`) of the refunded payment. */
+  readonly paymentId: string;
+  /** The Refund id (`re_...`). */
+  readonly refundId: string;
+  /** What the refund was for, in billing's unit. */
+  readonly amount: number;
+  /** When Stripe created the refund. */
+  readonly refundCreatedAt: Date;
+  /** When Stripe reported the failure (the event's `created`). */
+  readonly failedAt: Date;
+}
+
+/** What one delivery asks of billing. */
+export type StripeWebhookEvent =
+  /** A paid checkout: grant its plan, once. */
+  | { readonly type: "checkout_paid"; readonly eventId: string; readonly checkout: PaidCheckout }
+  /** A charge refunded in full: take back the access its payment gave, once. `snapshotAt`: when Stripe took the charge's state (the event's `created`). */
+  | { readonly type: "payment_refunded"; readonly eventId: string; readonly paymentId: string; readonly snapshotAt: Date }
+  /** A charge refunded in part: `amountRefunded` is the total refunded so far, in billing's unit, as of `snapshotAt`. */
+  | {
+      readonly type: "payment_partially_refunded";
+      readonly eventId: string;
+      readonly paymentId: string;
+      readonly amountRefunded: number;
+      readonly snapshotAt: Date;
+    }
+  /** A refund that failed (or was canceled): give back what it took, once per refund. */
+  | { readonly type: "refund_failed"; readonly eventId: string; readonly failure: FailedRefund }
+  /** Nothing to do: another event type, a checkout still waiting for its money, a charge with nothing refunded, a session billing did not create. */
+  | { readonly type: "ignored"; readonly eventId: string; readonly reason: string };
+
+const idSchema = z.string().min(1).max(MAX_ID_LENGTH);
+
+/** Unix seconds, as Stripe dates every event and object (up to the end of year 9999). */
+const unixSecondsSchema = z.number().int().min(0).max(253_402_300_799);
+
+const envelopeSchema = z.object({
+  id: idSchema,
+  type: z.string().min(1).max(MAX_ID_LENGTH),
+  /** When the event (and the snapshot of its object) was made; billing needs it for refunds only. */
+  created: unixSecondsSchema.optional(),
+  data: z.object({ object: z.unknown() }),
+});
+
+/** An expanded object or its id. */
+const referenceSchema = z.union([idSchema, z.object({ id: idSchema })]).transform((value) => (typeof value === "string" ? value : value.id));
+
+const sessionSchema = z.object({
+  id: idSchema,
+  mode: z.string(),
+  payment_status: z.string(),
+  payment_intent: referenceSchema.nullish(),
+  amount_total: z.number().int().min(0).nullish(),
+  currency: z.string().regex(/^[a-zA-Z]{3}$/).nullish(),
+  metadata: z.record(z.string(), z.string()).nullish(),
+});
+
+const chargeSchema = z.object({
+  payment_intent: referenceSchema.nullish(),
+  refunded: z.boolean(),
+  /** Stripe sends it on every charge; needed only for a partial refund, to convert the amount. */
+  currency: z.string().regex(/^[a-zA-Z]{3}$/).optional(),
+  /** The total refunded so far (Stripe sends it on every charge); needed only for a partial refund. */
+  amount_refunded: z.number().int().min(0).optional(),
+});
+
+const refundSchema = z.object({
+  id: idSchema,
+  payment_intent: referenceSchema.nullish(),
+  amount: z.number().int().min(0),
+  currency: z.string().regex(/^[a-zA-Z]{3}$/),
+  created: unixSecondsSchema,
+  status: z.string().nullish(),
+});
+
+/** Refund statuses whose money went back to the payment: the refund took nothing in the end. */
+const FAILED_REFUND_STATUSES: ReadonlySet<string> = new Set(["failed", "canceled"]);
+
+/** Payment statuses of a checkout that has its money (`no_payment_required`: a 100% discount). */
+const SETTLED_PAYMENT_STATUSES: ReadonlySet<string> = new Set(["paid", "no_payment_required"]);
+
+function readCheckout(eventId: string, object: unknown): StripeWebhookEvent | null {
+  const parsed = sessionSchema.safeParse(object);
+  if (!parsed.success) return null;
+  const session = parsed.data;
+  const userId = session.metadata?.[STRIPE_METADATA.userId];
+  const planId = session.metadata?.[STRIPE_METADATA.planId];
+  if (session.mode !== "payment" || userId === undefined || planId === undefined) {
+    return { type: "ignored", eventId, reason: "a checkout billing did not create" };
+  }
+  if (!SETTLED_PAYMENT_STATUSES.has(session.payment_status)) {
+    // A delayed method (a bank transfer): `checkout.session.async_payment_succeeded` follows.
+    return { type: "ignored", eventId, reason: `a checkout whose payment is ${session.payment_status}` };
+  }
+  if (session.amount_total === null || session.amount_total === undefined || session.currency === null || session.currency === undefined) return null;
+  const currency = session.currency.toUpperCase();
+  return {
+    type: "checkout_paid",
+    eventId,
+    checkout: {
+      checkoutId: session.id,
+      paymentId: session.payment_intent ?? null,
+      userId,
+      planId,
+      amount: fromStripeAmount(session.amount_total, currency),
+      currency,
+    },
+  };
+}
+
+function fromUnixSeconds(seconds: number): Date {
+  return new Date(seconds * 1000);
+}
+
+function readRefund(eventId: string, object: unknown, created: number | undefined): StripeWebhookEvent | null {
+  const parsed = chargeSchema.safeParse(object);
+  if (!parsed.success || created === undefined) return null;
+  const paymentId = parsed.data.payment_intent;
+  if (paymentId === null || paymentId === undefined) return { type: "ignored", eventId, reason: "a refunded charge without a payment" };
+  const snapshotAt = fromUnixSeconds(created);
+  if (parsed.data.refunded) return { type: "payment_refunded", eventId, paymentId, snapshotAt };
+  const { amount_refunded: amountRefunded, currency } = parsed.data;
+  if (amountRefunded === undefined || currency === undefined) return null;
+  if (amountRefunded === 0) return { type: "ignored", eventId, reason: "a charge with nothing refunded" };
+  return { type: "payment_partially_refunded", eventId, paymentId, amountRefunded: fromStripeAmount(amountRefunded, currency.toUpperCase()), snapshotAt };
+}
+
+/** A Refund event: `refund.failed` always reports a failure, the update events only with a failed or canceled status. */
+function readFailedRefund(eventId: string, object: unknown, created: number | undefined, isFailure: boolean): StripeWebhookEvent | null {
+  const parsed = refundSchema.safeParse(object);
+  if (!parsed.success || created === undefined) return null;
+  const refund = parsed.data;
+  if (!isFailure && !FAILED_REFUND_STATUSES.has(refund.status ?? "")) {
+    return { type: "ignored", eventId, reason: `a refund whose status is ${refund.status ?? "unknown"}` };
+  }
+  const paymentId = refund.payment_intent;
+  if (paymentId === null || paymentId === undefined) return { type: "ignored", eventId, reason: "a failed refund without a payment" };
+  const failure: FailedRefund = {
+    paymentId,
+    refundId: refund.id,
+    amount: fromStripeAmount(refund.amount, refund.currency.toUpperCase()),
+    refundCreatedAt: fromUnixSeconds(refund.created),
+    failedAt: fromUnixSeconds(created),
+  };
+  return { type: "refund_failed", eventId, failure };
+}
+
+/**
+ * The event a verified payload carries. A body that is not a Stripe event, or an event billing acts
+ * on whose object lacks what billing needs, is `billing.webhook_invalid`.
+ */
+export function parseStripeEvent(payload: string): Ok<StripeWebhookEvent> | Err<StripeWebhookError> {
+  let json: unknown;
+  try {
+    json = JSON.parse(payload);
+  } catch {
+    return err("billing.webhook_invalid");
+  }
+  const envelope = envelopeSchema.safeParse(json);
+  if (!envelope.success) return err("billing.webhook_invalid");
+  const { id, type, data, created } = envelope.data;
+  let event: StripeWebhookEvent | null;
+  switch (type) {
+    case "checkout.session.completed":
+    case "checkout.session.async_payment_succeeded":
+      event = readCheckout(id, data.object);
+      break;
+    case "charge.refunded":
+      event = readRefund(id, data.object, created);
+      break;
+    case "refund.failed":
+      event = readFailedRefund(id, data.object, created, true);
+      break;
+    case "refund.updated":
+    case "charge.refund.updated":
+      event = readFailedRefund(id, data.object, created, false);
+      break;
+    default:
+      event = { type: "ignored", eventId: id, reason: `the event type ${type}` };
+  }
+  return event === null ? err("billing.webhook_invalid") : ok(event);
+}
+
+/** `verifyStripeSignature`, then `parseStripeEvent`: nothing unsigned is parsed. */
+export function readStripeWebhook(input: VerifyStripeSignatureInput): Ok<StripeWebhookEvent> | Err<StripeWebhookError> {
+  const verified = verifyStripeSignature(input);
+  return verified.ok ? parseStripeEvent(input.payload) : verified;
+}