@dineway-ai/plugin-payment 0.2.6 → 0.2.8

package/src/subscriptions/service.ts

@@ -5,12 +5,21 @@ import type { Kysely } from "kysely";
 import Stripe from "stripe";
 
 import { StripeNodeWebhookVerifier } from "../stripe/webhook-verifier.js";
+import type { StripeWebhookEvent } from "../types.js";
+import { collectBounded, invoiceFunding, inspectCharge } from "./funding.js";
 import {
 	recurringPrice,
 	invoicePeriods,
 	memberProjection,
 	subscriptionProjection,
 } from "./projection.js";
+import {
+	createPurchase,
+	resumePurchase,
+	digest as purchaseDigest,
+	relationId,
+} from "./purchases.js";
+import { refundCharge, type SubscriptionRefundInput } from "./refunds.js";
 import { SubscriptionRepository, subscriptionScopeKey } from "./repository.js";
 import {
 	checkoutSchema,
@@ -18,6 +27,7 @@ import {
 	saveSubscriptionPlanSchema,
 	stripeProductListSchema,
 	stripePriceListSchema,
+	billingSubjectSchema,
 } from "./schemas.js";
 import {
 	SubscriptionError,
@@ -30,6 +40,8 @@ import {
 	type SubscriptionCatalogPage,
 	type SubscriptionProduct,
 	type StripeSubscriptionPrice,
+	type BillingSubject,
+	type SubscriptionPurchaseInput,
 } from "./types.js";
 
 export interface SubscriptionServiceOptions {
@@ -42,7 +54,7 @@ export interface SubscriptionServiceOptions {
 	stripe?: Stripe;
 }
 const terminal = new Set(["canceled", "incomplete_expired"]);
-const events = new Set([
+export const SUBSCRIPTION_WEBHOOK_EVENTS = [
 	"checkout.session.completed",
 	"checkout.session.async_payment_succeeded",
 	"checkout.session.async_payment_failed",
@@ -56,7 +68,17 @@ const events = new Set([
 	"invoice.payment_action_required",
 	"invoice.voided",
 	"invoice.marked_uncollectible",
-]);
+	"charge.refunded",
+	"charge.failed",
+	"charge.dispute.created",
+	"charge.dispute.updated",
+	"charge.dispute.closed",
+	"refund.created",
+	"refund.updated",
+	"refund.failed",
+	"payment_intent.payment_failed",
+] as const;
+const events = new Set<string>(SUBSCRIPTION_WEBHOOK_EVENTS);
 const localeSchema = checkoutSchema.shape.locale;
 const fingerprint = (values: unknown[]) =>
 	createHash("sha256").update(JSON.stringify(values)).digest("hex");
@@ -201,208 +223,221 @@ export class PaymentSubscriptionService {
 	private async user(userId: string) {
 		const user = await this.options.db
 			.selectFrom("users")
-			.select(["id", "email", "disabled"])
+			.select(["id", "email", "disabled", "email_verified"])
 			.where("id", "=", userId)
 			.executeTakeFirst();
-		if (!user || user.disabled)
+		if (!user || user.disabled || !user.email_verified)
 			throw new SubscriptionError("UNAUTHORIZED", "An active member account is required", 401);
 		return user;
 	}
-	private metadata(userId: string) {
-		return { dineway_app: this.options.scope.namespace, user_id: userId };
-	}
-	private sessionOwned(
-		session: Stripe.Checkout.Session,
-		userId: string,
-		customer: string,
-	): boolean {
-		const owner = typeof session.customer === "string" ? session.customer : session.customer?.id;
-		return (
-			owner === customer &&
-			session.mode === "subscription" &&
-			session.livemode === (this.options.scope.mode === "live") &&
-			session.metadata?.dineway_app === this.options.scope.namespace &&
-			session.metadata.user_id === userId &&
-			session.client_reference_id === userId
+	private purchaseContext() {
+		return {
+			stripe: this.stripe,
+			repository: this.repository,
+			scope: this.options.scope,
+			now: this.now,
+			origin: this.origin,
+		};
+	}
+	private async resolveSubject(subject: BillingSubject | string) {
+		if (typeof subject === "string") {
+			const user = await this.user(subject);
+			return {
+				key: user.id,
+				subject: { realm: "dineway", id: user.id, email: user.email, emailVerified: true },
+			};
+		}
+		const parsed = billingSubjectSchema.parse(subject);
+		return { key: "external:" + purchaseDigest([parsed.realm, parsed.id]), subject: parsed };
+	}
+	async createPurchase(subject: BillingSubject | string, input: SubscriptionPurchaseInput) {
+		const resolved = await this.resolveSubject(subject);
+		return createPurchase(this.purchaseContext(), resolved.key, resolved.subject, input);
+	}
+	async getPurchase(subject: BillingSubject | string, reference: string) {
+		const resolved = await this.resolveSubject(subject);
+		const purchase = await this.repository.purchase(reference);
+		if (!purchase || purchase.userId !== resolved.key)
+			throw new SubscriptionError("NOT_FOUND", "Purchase not found", 404);
+		return purchase;
+	}
+	async recoverCheckout(subject: BillingSubject | string, reference: string) {
+		const purchase = await this.getPurchase(subject, reference);
+		return this.repository.withLock("member:" + purchase.userId, (store) =>
+			resumePurchase(this.purchaseContext(), store, purchase),
 		);
 	}
-	async createCheckout(userId: string, input: SubscriptionCheckoutInput): Promise<{ url: string }> {
-		const parsed = checkoutSchema.parse(input);
-		const user = await this.user(userId);
-		const returnUrl = this.returnUrl(parsed.returnPath);
-		const successUrl = new URL(returnUrl);
-		successUrl.searchParams.set("checkout", "returned");
-		return this.repository.withLock("member:" + userId, async (repository) => {
-			const plans = await repository.plans();
-			const plan = plans.find((value) => value.code === parsed.planCode && value.enabled);
-			const price = plan?.prices.find(
-				(value) => value.interval === parsed.interval && value.enabled,
-			);
-			if (!price) throw new SubscriptionError("PLAN_UNAVAILABLE", "This plan is unavailable", 409);
-			const livePrice = recurringPrice(
-				await this.stripe.prices.retrieve(price.id),
-				this.options.scope,
-			);
-			if (
-				livePrice.currency !== price.currency ||
-				livePrice.amount !== price.amount ||
-				livePrice.productId !== price.productId ||
-				livePrice.interval !== price.interval
-			) {
-				throw new SubscriptionError("PRICE_CHANGED", "Refresh the plan price before checkout", 409);
-			}
-			let customer = await repository.customer(userId);
-			if (!customer) {
-				const created = await this.stripe.customers.create(
-					{ email: user.email, metadata: this.metadata(userId) },
-					{ idempotencyKey: providerIdempotency(this.options.scope, "customer", userId) },
-				);
-				customer = created.id;
-				await repository.saveCustomer(userId, customer);
-			}
-			const subscriptions = await this.stripe.subscriptions.list({
-				customer,
-				status: "all",
-				limit: 100,
+	async getSubscription(subject: BillingSubject | string, id: string) {
+		const resolved = await this.resolveSubject(subject);
+		const snapshot = await this.repository.snapshot(id);
+		if (snapshot.subscription.userId !== resolved.key)
+			throw new SubscriptionError("NOT_FOUND", "Subscription not found", 404);
+		return snapshot;
+	}
+	/** Only trusted server operations may request immediate cancellation. */
+	async cancelPurchase(
+		subject: BillingSubject | string,
+		reference: string,
+		mode: "period_end" | "immediate" = "period_end",
+	) {
+		const purchase = await this.getPurchase(subject, reference);
+		if (mode !== "period_end" && mode !== "immediate")
+			throw new SubscriptionError("INVALID_CANCELLATION", "Invalid cancellation mode");
+		await this.repository.withLock("member:" + purchase.userId, async (store) => {
+			const current = (await store.purchase(reference))!;
+			await store.updatePurchase(reference, {
+				cancel_mode: current.cancelMode === "immediate" ? "immediate" : mode,
+				last_attempt_at: this.now(),
 			});
-			if (subscriptions.has_more)
-				throw new SubscriptionError("REVIEW_REQUIRED", "Subscription review is required", 409);
-			if (
-				subscriptions.data.some(
-					(subscription) =>
-						subscription.metadata.dineway_app === this.options.scope.namespace &&
-						!terminal.has(subscription.status),
-				)
-			) {
+			await this.applyCancellation(store, (await store.purchase(reference))!);
+		});
+		const updated = (await this.repository.purchase(reference))!;
+		if (updated.subscriptionId) await this.refreshSubscription(updated.subscriptionId);
+		return this.repository.purchase(reference);
+	}
+	private async applyCancellation(
+		store: SubscriptionRepository,
+		purchase: NonNullable<Awaited<ReturnType<SubscriptionRepository["purchase"]>>>,
+	) {
+		if (!purchase.cancelMode) return;
+		if (!purchase.subscriptionId) {
+			await resumePurchase(this.purchaseContext(), store, purchase);
+			purchase = (await store.purchase(purchase.reference))!;
+		}
+		if (!purchase.subscriptionId) {
+			if (!purchase.sessionId)
 				throw new SubscriptionError(
-					"SUBSCRIPTION_EXISTS",
-					"Manage the existing subscription in the billing portal",
+					"CHECKOUT_REVIEW_REQUIRED",
+					"Confirm the checkout before canceling",
 					409,
 				);
-			}
-			const open = await this.stripe.checkout.sessions.list({
-				customer,
-				status: "open",
-				limit: 100,
-			});
-			const owned = open.data.filter(
-				(session) => session.metadata?.dineway_app === this.options.scope.namespace,
-			);
-			if (open.has_more || owned.length > 1)
-				throw new SubscriptionError("REVIEW_REQUIRED", "Checkout review is required", 409);
-			const previous = owned[0];
-			const locale = parsed.locale ?? "auto";
-			const remembered = await repository.attempt(userId);
-			const digest = fingerprint([customer, price.id, returnUrl, locale]);
-			if (previous) {
-				if (!this.sessionOwned(previous, userId, customer))
-					throw new SubscriptionError("OWNER_CONFLICT", "Checkout ownership conflict", 409);
-				const lines = await this.stripe.checkout.sessions.listLineItems(previous.id, { limit: 2 });
-				if (
-					previous.locale === locale &&
-					previous.success_url === successUrl.href &&
-					previous.cancel_url === returnUrl &&
-					previous.expires_at * 1000 > this.now() &&
-					previous.allow_promotion_codes === false &&
-					!lines.has_more &&
-					lines.data.length === 1 &&
-					lines.data[0]?.quantity === 1 &&
-					lines.data[0].price?.id === price.id
-				) {
-					if (remembered && !remembered.session_id && remembered.fingerprint === digest) {
-						await repository.saveAttempt(userId, { ...remembered, session_id: previous.id });
-					}
-					return { url: this.checkoutUrl(previous.url) };
-				}
-				const expired = await this.stripe.checkout.sessions.expire(previous.id);
+			const session = await this.stripe.checkout.sessions.retrieve(purchase.sessionId);
+			if (session.status === "open") {
+				const expired = await this.stripe.checkout.sessions.expire(session.id);
 				if (expired.status !== "expired")
 					throw new SubscriptionError(
-						"REVIEW_REQUIRED",
-						"Checkout changed; refresh and try again",
+						"CHECKOUT_REVIEW_REQUIRED",
+						"Checkout changed during cancellation",
 						409,
 					);
+			} else if (session.status !== "expired")
+				throw new SubscriptionError(
+					"CHECKOUT_REVIEW_REQUIRED",
+					"Confirm the checkout before canceling",
+					409,
+				);
+			await store.updatePurchase(purchase.reference, { closed: 1, last_error: null });
+			return;
+		}
+		const subscription = await this.stripe.subscriptions.retrieve(purchase.subscriptionId);
+		subscriptionProjection(
+			subscription,
+			await store.plans(),
+			this.options.scope,
+			purchase.userId,
+			(await store.customer(purchase.userId))!,
+			this.now(),
+			purchase,
+		);
+		if (!terminal.has(subscription.status)) {
+			const request = {
+				idempotencyKey: providerIdempotency(
+					this.options.scope,
+					purchase.reference,
+					"cancel",
+					purchase.cancelMode,
+				),
+			};
+			if (purchase.cancelMode === "immediate")
+				await this.stripe.subscriptions.cancel(
+					subscription.id,
+					{ invoice_now: false, prorate: false },
+					request,
+				);
+			else if (!subscription.cancel_at_period_end)
+				await this.stripe.subscriptions.update(
+					subscription.id,
+					{ cancel_at_period_end: true },
+					request,
+				);
+		}
+		await store.updatePurchase(purchase.reference, {
+			last_error: null,
+			last_attempt_at: this.now(),
+		});
+	}
+	async createCheckout(userId: string, input: SubscriptionCheckoutInput): Promise<{ url: string }> {
+		const parsed = checkoutSchema.parse(input);
+		await this.user(userId);
+		this.returnUrl(parsed.returnPath);
+		return this.repository.withLock("catalogue:" + userId, async () => {
+			const plan = (await this.repository.plans()).find(
+				(value) => value.code === parsed.planCode && value.enabled,
+			);
+			if (!plan?.prices.some((price) => price.enabled && price.interval === parsed.interval))
+				throw new SubscriptionError("PLAN_UNAVAILABLE", "This plan is unavailable", 409);
+			const customer = await this.repository.customer(userId);
+			if (customer) {
+				const subscriptions = await this.stripe.subscriptions.list({
+					customer,
+					status: "all",
+					limit: 100,
+				});
+				if (subscriptions.has_more)
+					throw new SubscriptionError("REVIEW_REQUIRED", "Subscription review is required", 409);
+				for (const subscription of subscriptions.data) {
+					if (
+						subscription.metadata.dineway_app !== this.options.scope.namespace ||
+						terminal.has(subscription.status)
+					)
+						continue;
+					const purchase = subscription.metadata.purchase_reference
+						? await this.repository.purchase(subscription.metadata.purchase_reference)
+						: null;
+					if (!purchase || purchase.contract.groupKey === "membership")
+						throw new SubscriptionError(
+							"SUBSCRIPTION_EXISTS",
+							"Manage the existing subscription in the billing portal",
+							409,
+						);
+				}
 			}
-			if (!previous && remembered?.session_id) {
-				const session = await this.stripe.checkout.sessions.retrieve(remembered.session_id);
-				if (!this.sessionOwned(session, userId, customer))
-					throw new SubscriptionError("OWNER_CONFLICT", "Checkout ownership conflict", 409);
-				const relation = session.subscription;
-				const subscriptionId = typeof relation === "string" ? relation : relation?.id;
-				const old = subscriptions.data.find((subscription) => subscription.id === subscriptionId);
-				if (
-					session.status !== "expired" &&
-					!(session.status === "complete" && old && terminal.has(old.status))
-				) {
-					throw new SubscriptionError(
-						"SUBSCRIPTION_EXISTS",
-						"Confirm the previous subscription before starting another",
-						409,
-					);
+			let existing = await this.repository.openPurchase(userId, "membership");
+			if (existing) {
+				const pricing = existing.contract.pricing;
+				const compatible =
+					pricing.kind === "catalogue" &&
+					pricing.planCode === parsed.planCode &&
+					pricing.interval === parsed.interval &&
+					existing.contract.returnPath === parsed.returnPath &&
+					(existing.contract.locale ?? "auto") === (parsed.locale ?? "auto");
+				if (!compatible) {
+					await this.cancelPurchase(userId, existing.reference);
+					existing = null;
 				}
 			}
-			if (
-				!previous &&
-				remembered &&
-				!remembered.session_id &&
-				(remembered.fingerprint !== digest || this.now() - remembered.created_at > 23 * 3600000)
-			) {
+			const result = await this.createPurchase(userId, {
+				reference: existing?.reference ?? randomUUID(),
+				groupKey: "membership",
+				pricing: { kind: "catalogue", planCode: parsed.planCode, interval: parsed.interval },
+				returnPath: parsed.returnPath,
+				locale: parsed.locale,
+			});
+			if (!result.url)
 				throw new SubscriptionError(
-					"REVIEW_REQUIRED",
-					"An unconfirmed checkout requires review",
+					"SUBSCRIPTION_EXISTS",
+					"Confirm your subscription status before starting another",
 					409,
 				);
-			}
-			const attempt =
-				!previous && remembered && !remembered.session_id
-					? remembered
-					: {
-							fingerprint: digest,
-							request_id: randomUUID(),
-							session_id: null,
-							created_at: this.now(),
-						};
-			await repository.saveAttempt(userId, attempt);
-			const session = await this.stripe.checkout.sessions.create(
-				{
-					mode: "subscription",
-					customer,
-					locale,
-					line_items: [{ price: price.id, quantity: 1 }],
-					client_reference_id: userId,
-					metadata: this.metadata(userId),
-					subscription_data: { metadata: this.metadata(userId) },
-					success_url: successUrl.href,
-					cancel_url: returnUrl,
-					allow_promotion_codes: false,
-				},
-				{
-					idempotencyKey: providerIdempotency(
-						this.options.scope,
-						"checkout",
-						userId,
-						attempt.request_id,
-					),
-				},
-			);
-			if (!this.sessionOwned(session, userId, customer))
-				throw new SubscriptionError("OWNER_CONFLICT", "Checkout ownership conflict", 409);
-			await repository.saveAttempt(userId, { ...attempt, session_id: session.id });
-			if (session.status !== "open")
-				throw new SubscriptionError("CHECKOUT_COMPLETED", "Refresh your subscription status", 409);
-			return { url: this.checkoutUrl(session.url) };
+			return { url: result.url };
 		});
 	}
-	private checkoutUrl(value: string | null): string {
-		if (!value || new URL(value).origin !== "https://checkout.stripe.com")
-			throw new SubscriptionError("INVALID_DESTINATION", "Invalid checkout destination", 502);
-		return value;
-	}
 	async createPortal(
-		userId: string,
+		subject: BillingSubject | string,
 		input: { returnPath: string; locale?: string },
 	): Promise<{ url: string }> {
 		const parsed = portalSchema.parse(input);
-		await this.user(userId);
+		const { key: userId } = await this.resolveSubject(subject);
 		const customer = await this.repository.customer(userId);
 		if (!customer)
 			throw new SubscriptionError("CUSTOMER_NOT_FOUND", "No billing account exists", 404);
@@ -432,6 +467,9 @@ export class PaymentSubscriptionService {
 					!config.active ||
 					config.livemode !== (this.options.scope.mode === "live") ||
 					config.features.subscription_update.enabled ||
+					!config.features.invoice_history.enabled ||
+					!config.features.payment_method_update.enabled ||
+					config.features.customer_update.enabled ||
 					!config.features.subscription_cancel.enabled ||
 					config.features.subscription_cancel.mode !== "at_period_end"
 				) {
@@ -460,11 +498,39 @@ export class PaymentSubscriptionService {
 			await this.repository.withLock("subscription:" + id, async (repository) => {
 				if (eventId && (await repository.eventSeen(eventId))) return;
 				const live = await this.stripe.subscriptions.retrieve(id);
-				if (live.metadata.dineway_app !== this.options.scope.namespace) return;
+				if (live.metadata.dineway_app !== this.options.scope.namespace) {
+					if (previous)
+						throw new SubscriptionError("OWNER_CONFLICT", "Subscription application changed", 409);
+					return;
+				}
 				const customerId = typeof live.customer === "string" ? live.customer : live.customer.id;
+				if (
+					previous &&
+					(previous.customerId !== customerId ||
+						(previous.purchaseReference ?? null) !== (live.metadata.purchase_reference ?? null))
+				)
+					throw new SubscriptionError(
+						"OWNER_CONFLICT",
+						"Subscription purchase identity changed",
+						409,
+					);
 				const userId = await repository.customerOwner(customerId);
-				if (!userId) return;
+				if (!userId)
+					throw new SubscriptionError(
+						"CUSTOMER_NOT_FOUND",
+						"The billing account has not been synchronized",
+						503,
+					);
 				const plans = await repository.plans();
+				const purchase = live.metadata.purchase_reference
+					? await repository.purchase(live.metadata.purchase_reference)
+					: null;
+				if (live.metadata.purchase_reference && !purchase)
+					throw new SubscriptionError(
+						"PURCHASE_NOT_FOUND",
+						"The purchase has not been synchronized",
+						503,
+					);
 				const state = subscriptionProjection(
 					live,
 					plans,
@@ -472,28 +538,103 @@ export class PaymentSubscriptionService {
 					userId,
 					customerId,
 					this.now(),
+					purchase,
+				);
+				const invoices = await collectBounded(
+					this.stripe.invoices.list({
+						customer: customerId,
+						subscription: id,
+						status: "paid",
+						limit: 100,
+					}),
 				);
-				const invoices = await this.stripe.invoices
-					.list({ customer: customerId, subscription: id, status: "paid", limit: 100 })
-					.autoPagingToArray({ limit: 1000 });
 				const periods = [];
-				for (const invoice of invoices) {
-					const lines = invoice.lines.has_more
-						? await this.stripe.invoices
-								.listLineItems(invoice.id, { limit: 100 })
-								.autoPagingToArray({ limit: 1000 })
-						: invoice.lines.data;
-					periods.push(...invoicePeriods(invoice, lines, state, plans, this.options.scope));
+				const previousPeriods = (await repository.periods(userId)).filter(
+					(period) => period.subscriptionId === id,
+				);
+				const invoiceIds = new Set([
+					...invoices.map((invoice) => invoice.id),
+					...previousPeriods.map((period) => period.invoiceId),
+				]);
+				for (const invoiceId of invoiceIds) {
+					const invoice = await this.stripe.invoices.retrieve(invoiceId, {
+						expand: ["discounts.source.coupon"],
+					});
+					const evidence = await invoiceFunding(
+						this.stripe,
+						this.options.scope,
+						live,
+						invoice,
+						purchase?.contract ?? null,
+						this.now(),
+					);
+					const old = previousPeriods.filter((period) => period.invoiceId === invoiceId);
+					const projected = old.length
+						? old
+						: invoice.status === "paid"
+							? invoicePeriods(invoice, invoice.lines.data, state, plans, this.options.scope)
+							: [];
+					const historyChanged = old.some(
+						(period) =>
+							!invoice.lines.data.some(
+								(line) =>
+									period.id === invoice.id + ":" + line.id &&
+									line.period.start === period.startsAt &&
+									line.period.end === period.endsAt,
+							),
+					);
+					if (historyChanged) evidence.reason = "PAID_PERIOD_CHANGED";
+					periods.push(
+						...projected.map((period) => ({
+							...period,
+							eligible: evidence.reason === null,
+							evidence,
+						})),
+					);
+					if (evidence.reason) state.lastError = evidence.reason;
 				}
 				await repository.saveSubscription(state, periods, eventId);
 			});
 		} catch (error) {
-			if (previous) await this.repository.recordSyncFailure(id, previous.verifiedAt);
+			if (
+				previous &&
+				error instanceof SubscriptionError &&
+				[
+					"OWNER_CONFLICT",
+					"UNRECOGNIZED_SUBSCRIPTION",
+					"INVALID_PRICE",
+					"INVALID_INVOICE",
+					"INVALID_EVIDENCE",
+					"MODE_MISMATCH",
+					"PURCHASE_CONFLICT",
+				].includes(error.code)
+			) {
+				await this.repository.withLock("subscription:" + id, async (store) => {
+					const current = await store.subscription(id);
+					if (current?.revision !== previous.revision) return;
+					const periods = (await store.periods(previous.userId))
+						.filter((period) => period.subscriptionId === id)
+						.map((period) => ({
+							...period,
+							eligible: false,
+							evidence: period.evidence
+								? { ...period.evidence, verifiedAt: this.now(), reason: error.code }
+								: undefined,
+						}));
+					await store.saveSubscription(
+						{ ...previous, verifiedAt: this.now(), lastError: error.code },
+						periods,
+					);
+				});
+			} else if (previous) await this.repository.recordSyncFailure(id, previous.verifiedAt);
 			throw error;
 		}
 	}
-	async getMemberBilling(userId: string, refresh = true): Promise<MemberBilling> {
-		await this.user(userId);
+	async getMemberBilling(subject: BillingSubject | string, refresh = true): Promise<MemberBilling> {
+		const { key } = await this.resolveSubject(subject);
+		return this.memberBilling(key, refresh);
+	}
+	private async memberBilling(userId: string, refresh = true): Promise<MemberBilling> {
 		const customer = await this.repository.customer(userId);
 		let states = await this.repository.subscriptions(userId);
 		if (refresh && customer) {
@@ -532,16 +673,48 @@ export class PaymentSubscriptionService {
 			this.now(),
 		);
 	}
-	async getEntitlements(userId: string) {
+	async getEntitlements(userId: BillingSubject | string) {
 		return (await this.getMemberBilling(userId)).entitlements;
 	}
 	async listSubscriptions(cursor?: string, limit = 50) {
-		return this.repository.listSubscriptions(cursor, Math.max(1, Math.min(100, limit)));
+		const page = await this.repository.listSubscriptions(cursor, Math.max(1, Math.min(100, limit)));
+		return {
+			...page,
+			items: await Promise.all(
+				page.items.map(async (state) => ({
+					...state,
+					subject: await this.repository.subject(state.userId),
+				})),
+			),
+		};
+	}
+	async listPurchases(cursor?: string, limit = 50) {
+		return this.repository.listPurchases(cursor, Math.max(1, Math.min(100, limit)));
+	}
+	async pendingChanges(limit = 50) {
+		return this.repository.changes(Math.max(1, Math.min(100, limit)));
+	}
+	async acknowledgeChange(id: string) {
+		await this.repository.acknowledgeChange(id);
+	}
+	async inspectCharge(subject: BillingSubject | string, chargeId: string) {
+		const { key } = await this.resolveSubject(subject);
+		const evidence = await inspectCharge(this.stripe, this.options.scope, chargeId);
+		if (!evidence.customerId || (await this.repository.customerOwner(evidence.customerId)) !== key)
+			throw new SubscriptionError("NOT_FOUND", "Charge not found", 404);
+		return evidence;
+	}
+	async refundCharge(subject: BillingSubject | string, input: SubscriptionRefundInput) {
+		const { key } = await this.resolveSubject(subject);
+		return refundCharge(this.purchaseContext(), key, input);
 	}
 	async subscriptionDetail(id: string) {
 		const state = await this.repository.subscription(id);
 		if (!state) throw new SubscriptionError("NOT_FOUND", "Subscription not found", 404);
-		return { subscription: state, member: await this.getMemberBilling(state.userId, false) };
+		return {
+			...(await this.repository.snapshot(id)),
+			member: await this.memberBilling(state.userId, false),
+		};
 	}
 	async receiveWebhook(rawBody: Uint8Array, signature: string | null): Promise<void> {
 		const verified = new StripeNodeWebhookVerifier().verify({
@@ -552,16 +725,126 @@ export class PaymentSubscriptionService {
 		});
 		if (!verified.ok)
 			throw new SubscriptionError("INVALID_SIGNATURE", "Invalid Stripe webhook", 400);
-		const event = verified.event;
+		await this.receiveVerifiedWebhook(verified.event, rawBody);
+	}
+	async receiveVerifiedWebhook(event: StripeWebhookEvent, rawBody: Uint8Array): Promise<void> {
 		if (event.livemode !== (this.options.scope.mode === "live"))
 			throw new SubscriptionError("MODE_MISMATCH", "Invalid webhook mode", 400);
-		if (
-			!events.has(event.eventType) ||
-			!event.subscriptionId ||
-			(await this.repository.eventSeen(event.eventId))
-		)
-			return;
-		await this.refreshSubscription(event.subscriptionId, event.eventId);
+		if (!events.has(event.eventType)) return;
+		await this.repository.receiveEvent({
+			id: event.eventId,
+			digest: event.payloadSha256,
+			type: event.eventType,
+			objectType: event.objectType,
+			objectId: event.objectId,
+			subscriptionId: event.subscriptionId ?? null,
+			payload: new TextDecoder().decode(rawBody),
+		});
+	}
+	private async eventSubscriptions(event: {
+		subscription_id: string | null;
+		object_type: string | null;
+		object_id: string | null;
+	}): Promise<string[]> {
+		if (event.subscription_id) return [event.subscription_id];
+		const id = event.object_id;
+		if (!id) return [];
+		let intent: string | null = null;
+		if (event.object_type === "payment_intent") intent = id;
+		else {
+			let charge: string | null = null;
+			if (event.object_type === "charge") charge = id;
+			if (event.object_type === "refund")
+				charge = relationId((await this.stripe.refunds.retrieve(id)).charge);
+			if (event.object_type === "dispute")
+				charge = relationId((await this.stripe.disputes.retrieve(id)).charge);
+			if (charge) {
+				const payment = await this.stripe.charges.retrieve(charge);
+				if (payment.livemode !== (this.options.scope.mode === "live"))
+					throw new SubscriptionError("MODE_MISMATCH", "Invalid charge mode");
+				intent = relationId(payment.payment_intent);
+			}
+		}
+		if (!intent) return [];
+		const payments = await collectBounded(
+			this.stripe.invoicePayments.list({
+				payment: { type: "payment_intent", payment_intent: intent },
+				limit: 100,
+			}),
+		);
+		const ids = new Set<string>();
+		for (const payment of payments) {
+			const invoiceId = relationId(payment.invoice);
+			if (!invoiceId) continue;
+			const invoice = await this.stripe.invoices.retrieve(invoiceId);
+			if (invoice.livemode !== (this.options.scope.mode === "live"))
+				throw new SubscriptionError("MODE_MISMATCH", "Invalid invoice mode");
+			const subscription = relationId(invoice.parent?.subscription_details?.subscription);
+			if (subscription) ids.add(subscription);
+		}
+		return [...ids];
+	}
+	async reconcilePending(limit = 25) {
+		const bounded = Math.max(1, Math.min(100, Math.floor(limit)));
+		const result = { processed: 0, failed: 0 };
+		for (const event of await this.repository.pendingEvents(bounded)) {
+			try {
+				await this.repository.withLock("event:" + event.id, async (store) => {
+					if (await store.eventSeen(event.id)) return;
+					try {
+						for (const id of await this.eventSubscriptions(event))
+							await this.refreshSubscription(id);
+						await store.finishEvent(event.id, null);
+						result.processed++;
+					} catch (error) {
+						await store.finishEvent(
+							event.id,
+							error instanceof SubscriptionError ? error.code : "SYNC_UNAVAILABLE",
+						);
+						result.failed++;
+					}
+				});
+			} catch {
+				result.failed++;
+			}
+		}
+		return result;
+	}
+	/** Run from a protected scheduler; domain consumers acknowledge changes after their own commit. */
+	async reconcile(limit = 25) {
+		const bounded = Math.max(1, Math.min(100, Math.floor(limit)));
+		const result = await this.reconcilePending(bounded);
+		for (const row of await this.repository.pendingPurchases(bounded)) {
+			const purchase = (await this.repository.purchase(row.id))!;
+			try {
+				await this.repository.withLock("member:" + purchase.userId, async (store) => {
+					try {
+						if (purchase.cancelMode) await this.applyCancellation(store, purchase);
+						else await resumePurchase(this.purchaseContext(), store, purchase);
+					} catch (error) {
+						await store.updatePurchase(row.id, {
+							last_attempt_at: this.now(),
+							last_error: error instanceof SubscriptionError ? error.code : "SYNC_UNAVAILABLE",
+						});
+						throw error;
+					}
+				});
+				const current = (await this.repository.purchase(row.id))!;
+				if (current.subscriptionId) await this.refreshSubscription(current.subscriptionId);
+				result.processed++;
+			} catch {
+				result.failed++;
+			}
+		}
+		for (const row of await this.repository.staleSubscriptions(bounded)) {
+			try {
+				await this.refreshSubscription(row.id);
+				result.processed++;
+			} catch {
+				result.failed++;
+			}
+		}
+		return result;
 	}
 }