@dineway-ai/plugin-payment 0.2.3 → 0.2.5

package/src/subscriptions/service.ts

@@ -0,0 +1,510 @@
+import { createHash, randomUUID } from "node:crypto";
+
+import type { Database } from "dineway";
+import type { Kysely } from "kysely";
+import Stripe from "stripe";
+
+import { StripeNodeWebhookVerifier } from "../stripe/webhook-verifier.js";
+import {
+	recurringPrice,
+	invoicePeriods,
+	memberProjection,
+	subscriptionProjection,
+} from "./projection.js";
+import { SubscriptionRepository, subscriptionScopeKey } from "./repository.js";
+import { checkoutSchema, portalSchema, saveSubscriptionPlanSchema } from "./schemas.js";
+import {
+	SubscriptionError,
+	type MemberBilling,
+	type SaveSubscriptionPlan,
+	type SubscriptionCheckoutInput,
+	type SubscriptionOptions,
+	type SubscriptionScope,
+} from "./types.js";
+
+export interface SubscriptionServiceOptions {
+	db: Kysely<Database>;
+	scope: SubscriptionScope;
+	siteUrl: string;
+	secretKey: string;
+	webhookSecret: string;
+	now?: () => number;
+	stripe?: Stripe;
+}
+const terminal = new Set(["canceled", "incomplete_expired"]);
+const events = new Set([
+	"checkout.session.completed",
+	"checkout.session.async_payment_succeeded",
+	"checkout.session.async_payment_failed",
+	"customer.subscription.created",
+	"customer.subscription.updated",
+	"customer.subscription.deleted",
+	"customer.subscription.paused",
+	"customer.subscription.resumed",
+	"invoice.paid",
+	"invoice.payment_failed",
+	"invoice.payment_action_required",
+	"invoice.voided",
+	"invoice.marked_uncollectible",
+]);
+const localeSchema = checkoutSchema.shape.locale;
+const fingerprint = (values: unknown[]) =>
+	createHash("sha256").update(JSON.stringify(values)).digest("hex");
+const providerIdempotency = (scope: SubscriptionScope, ...values: unknown[]) =>
+	"dineway-subscriptions:" + fingerprint([scope, ...values]);
+
+export class PaymentSubscriptionService {
+	private readonly stripe: Stripe;
+	private readonly repository: SubscriptionRepository;
+	private readonly now: () => number;
+	private readonly origin: string;
+	constructor(private readonly options: SubscriptionServiceOptions) {
+		this.now = options.now ?? Date.now;
+		this.repository = new SubscriptionRepository(options.db, options.scope, this.now);
+		this.stripe =
+			options.stripe ??
+			new Stripe(options.secretKey, {
+				maxNetworkRetries: 0,
+				timeout: 15000,
+				appInfo: { name: "Dineway Subscriptions" },
+			});
+		const url = new URL(options.siteUrl);
+		if (
+			url.username ||
+			url.password ||
+			url.pathname !== "/" ||
+			url.search ||
+			url.hash ||
+			(url.protocol !== "https:" &&
+				!(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+		) {
+			throw new SubscriptionError("INVALID_SITE_URL", "Configure the public site origin");
+		}
+		this.origin = url.origin;
+	}
+	async listPlans(includeArchived = false) {
+		const plans = await this.repository.plans();
+		return includeArchived
+			? plans
+			: plans
+					.filter((plan) => plan.enabled)
+					.map((plan) => ({ ...plan, prices: plan.prices.filter((price) => price.enabled) }));
+	}
+	async savePlan(input: SaveSubscriptionPlan) {
+		const parsed = saveSubscriptionPlanSchema.parse(input);
+		const allPlans = await this.repository.plans();
+		for (const [key, value] of Object.entries(parsed.entitlements)) {
+			if (
+				allPlans.some(
+					(plan) =>
+						plan.entitlements[key] !== undefined && typeof plan.entitlements[key] !== typeof value,
+				)
+			) {
+				throw new SubscriptionError(
+					"ENTITLEMENT_TYPE_CONFLICT",
+					"An entitlement must have the same type across plans",
+				);
+			}
+		}
+		const prices = [];
+		for (const [interval, id] of [
+			["month", parsed.monthlyPriceId],
+			["year", parsed.yearlyPriceId],
+		] as const) {
+			if (!id) continue;
+			const price = recurringPrice(
+				await this.stripe.prices.retrieve(id),
+				this.options.scope,
+				parsed.enabled,
+			);
+			if (price.interval !== interval)
+				throw new SubscriptionError("INVALID_PRICE", "Price interval does not match its binding");
+			prices.push(price);
+		}
+		if (parsed.enabled && !prices.length)
+			throw new SubscriptionError("INVALID_PRICE", "An enabled plan needs a price");
+		if (
+			new Set(prices.map((price) => price.productId)).size > 1 ||
+			new Set(prices.map((price) => price.currency)).size > 1
+		) {
+			throw new SubscriptionError("INVALID_PRICE", "Plan prices must share a product and currency");
+		}
+		await this.repository.savePlan(parsed, prices);
+		return (await this.repository.plans()).find((plan) => plan.code === parsed.code)!;
+	}
+	private returnUrl(path: string): string {
+		portalSchema.shape.returnPath.parse(path);
+		const url = new URL(path, this.origin);
+		if (url.origin !== this.origin)
+			throw new SubscriptionError("INVALID_RETURN_URL", "Return to this site");
+		return url.href;
+	}
+	private async user(userId: string) {
+		const user = await this.options.db
+			.selectFrom("users")
+			.select(["id", "email", "disabled"])
+			.where("id", "=", userId)
+			.executeTakeFirst();
+		if (!user || user.disabled)
+			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
+		);
+	}
+	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,
+			});
+			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),
+				)
+			) {
+				throw new SubscriptionError(
+					"SUBSCRIPTION_EXISTS",
+					"Manage the existing subscription in the billing portal",
+					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);
+				if (expired.status !== "expired")
+					throw new SubscriptionError(
+						"REVIEW_REQUIRED",
+						"Checkout changed; refresh and try again",
+						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,
+					);
+				}
+			}
+			if (
+				!previous &&
+				remembered &&
+				!remembered.session_id &&
+				(remembered.fingerprint !== digest || this.now() - remembered.created_at > 23 * 3600000)
+			) {
+				throw new SubscriptionError(
+					"REVIEW_REQUIRED",
+					"An unconfirmed checkout requires review",
+					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) };
+		});
+	}
+	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,
+		input: { returnPath: string; locale?: string },
+	): Promise<{ url: string }> {
+		const parsed = portalSchema.parse(input);
+		await this.user(userId);
+		const customer = await this.repository.customer(userId);
+		if (!customer)
+			throw new SubscriptionError("CUSTOMER_NOT_FOUND", "No billing account exists", 404);
+		const configuration = await this.repository.withLock(
+			"portal-configuration",
+			async (repository) => {
+				let id = await repository.portalConfiguration();
+				if (!id) {
+					const created = await this.stripe.billingPortal.configurations.create(
+						{
+							features: {
+								invoice_history: { enabled: true },
+								payment_method_update: { enabled: true },
+								subscription_cancel: { enabled: true, mode: "at_period_end" },
+								subscription_update: { enabled: false },
+								customer_update: { enabled: false },
+							},
+							metadata: { dineway_app: this.options.scope.namespace },
+						},
+						{ idempotencyKey: providerIdempotency(this.options.scope, "portal") },
+					);
+					id = created.id;
+					await repository.savePortalConfiguration(id);
+				}
+				const config = await this.stripe.billingPortal.configurations.retrieve(id);
+				if (
+					!config.active ||
+					config.livemode !== (this.options.scope.mode === "live") ||
+					config.features.subscription_update.enabled ||
+					!config.features.subscription_cancel.enabled ||
+					config.features.subscription_cancel.mode !== "at_period_end"
+				) {
+					throw new SubscriptionError(
+						"PORTAL_CONFIGURATION_INVALID",
+						"The portal must use period-end cancellation without plan changes",
+						503,
+					);
+				}
+				return id;
+			},
+		);
+		const session = await this.stripe.billingPortal.sessions.create({
+			customer,
+			configuration,
+			locale: localeSchema.parse(parsed.locale) ?? "auto",
+			return_url: this.returnUrl(parsed.returnPath),
+		});
+		if (new URL(session.url).origin !== "https://billing.stripe.com")
+			throw new SubscriptionError("INVALID_DESTINATION", "Invalid billing destination", 502);
+		return { url: session.url };
+	}
+	async refreshSubscription(id: string, eventId?: string): Promise<void> {
+		const previous = await this.repository.subscription(id);
+		try {
+			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;
+				const customerId = typeof live.customer === "string" ? live.customer : live.customer.id;
+				const userId = await repository.customerOwner(customerId);
+				if (!userId) return;
+				const plans = await repository.plans();
+				const state = subscriptionProjection(
+					live,
+					plans,
+					this.options.scope,
+					userId,
+					customerId,
+					this.now(),
+				);
+				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));
+				}
+				await repository.saveSubscription(state, periods, eventId);
+			});
+		} catch (error) {
+			if (previous) await this.repository.recordSyncFailure(id, previous.verifiedAt);
+			throw error;
+		}
+	}
+	async getMemberBilling(userId: string, refresh = true): Promise<MemberBilling> {
+		await this.user(userId);
+		const customer = await this.repository.customer(userId);
+		let states = await this.repository.subscriptions(userId);
+		if (refresh && customer) {
+			// A completed checkout can precede its webhook and local subscription row.
+			if (!states.length || states.every((state) => terminal.has(state.status))) {
+				try {
+					const live = await this.stripe.subscriptions.list({
+						customer,
+						status: "all",
+						limit: 100,
+					});
+					for (const subscription of live.data) {
+						if (subscription.metadata.dineway_app === this.options.scope.namespace)
+							await this.refreshSubscription(subscription.id);
+					}
+				} catch {
+					/* An unavailable provider cannot create access. */
+				}
+			} else {
+				for (const state of states) {
+					if (this.now() - state.verifiedAt < 900000) continue;
+					try {
+						await this.refreshSubscription(state.id);
+					} catch {
+						/* Reconciliation records the failure without extending access. */
+					}
+				}
+			}
+			states = await this.repository.subscriptions(userId);
+		}
+		return memberProjection(
+			Boolean(customer),
+			states,
+			await this.repository.periods(userId),
+			await this.repository.plans(),
+			this.now(),
+		);
+	}
+	async getEntitlements(userId: 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)));
+	}
+	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) };
+	}
+	async receiveWebhook(rawBody: Uint8Array, signature: string | null): Promise<void> {
+		const verified = new StripeNodeWebhookVerifier().verify({
+			secretKey: this.options.secretKey,
+			webhookSecret: this.options.webhookSecret,
+			rawBody,
+			signature,
+		});
+		if (!verified.ok)
+			throw new SubscriptionError("INVALID_SIGNATURE", "Invalid Stripe webhook", 400);
+		const event = verified.event;
+		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);
+	}
+}
+
+export type { SubscriptionOptions };
+export { subscriptionScopeKey };

package/src/subscriptions/types.ts

@@ -0,0 +1,80 @@
+import type { StripeMode } from "../types.js";
+
+export type SubscriptionEntitlements = Record<string, boolean | number>;
+export type SubscriptionInterval = "month" | "year";
+export interface SubscriptionScope {
+	accountId: string;
+	mode: StripeMode;
+	namespace: string;
+}
+export interface SubscriptionOptions {
+	namespace: string;
+	siteUrl: string;
+}
+export interface SubscriptionPrice {
+	id: string;
+	productId: string;
+	currency: string;
+	amount: number;
+	interval: SubscriptionInterval;
+	enabled: boolean;
+}
+export interface SubscriptionPlan {
+	code: string;
+	name: string;
+	enabled: boolean;
+	version: number;
+	entitlements: SubscriptionEntitlements;
+	prices: SubscriptionPrice[];
+}
+export interface SaveSubscriptionPlan {
+	code: string;
+	name: string;
+	enabled: boolean;
+	expectedVersion: number;
+	entitlements: SubscriptionEntitlements;
+	monthlyPriceId: string | null;
+	yearlyPriceId: string | null;
+}
+export interface MemberSubscription {
+	id: string;
+	userId: string;
+	customerId: string;
+	planCode: string;
+	priceId: string;
+	status: string;
+	periodEnd: number;
+	cancelAtPeriodEnd: boolean;
+	verifiedAt: number;
+	lastError: string | null;
+}
+export interface PaidSubscriptionPeriod {
+	id: string;
+	invoiceId: string;
+	subscriptionId: string;
+	planCode: string;
+	startsAt: number;
+	endsAt: number;
+}
+export interface MemberBilling {
+	customer: boolean;
+	subscriptions: MemberSubscription[];
+	paidThrough: number | null;
+	entitlements: SubscriptionEntitlements;
+}
+export interface SubscriptionCheckoutInput {
+	planCode: string;
+	interval: SubscriptionInterval;
+	locale?: string;
+	returnPath: string;
+}
+export class SubscriptionError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = "SubscriptionError";
+	}
+}

package/src/types.ts

@@ -261,6 +261,7 @@ export interface StripeWebhookRefund {
 }
 
 export interface StripeWebhookEvent {
+	subscriptionId?: string;
 	eventId: string;
 	eventType: string;
 	eventCreated: number;