@dineway-ai/plugin-payment 0.2.6 → 0.2.7

package/src/subscriptions/projection.ts

@@ -8,6 +8,7 @@ import {
 	type SubscriptionPlan,
 	type SubscriptionPrice,
 	type SubscriptionScope,
+	type SubscriptionPurchase,
 } from "./types.js";
 
 export function recurringPrice(
@@ -76,30 +77,53 @@ export function subscriptionProjection(
 	userId: string,
 	customerId: string,
 	now: number,
+	purchase?: SubscriptionPurchase | null,
 ): MemberSubscription {
 	ownedSubscription(subscription, scope, userId, customerId);
 	const item = subscription.items.data[0];
 	const plan = plans.find((value) => value.prices.some((price) => price.id === item?.price.id));
 	if (
-		!plan ||
+		(!plan && purchase?.contract.pricing.kind !== "dynamic") ||
 		subscription.items.has_more ||
 		subscription.items.data.length !== 1 ||
 		item?.quantity !== 1
 	) {
 		throw new SubscriptionError("UNRECOGNIZED_SUBSCRIPTION", "Subscription requires review", 409);
 	}
-	recurringPrice(item.price, scope, false);
+	if (purchase) {
+		const { contract } = purchase;
+		if (
+			purchase.userId !== userId ||
+			subscription.metadata.purchase_reference !== purchase.reference ||
+			(purchase.subscriptionId && purchase.subscriptionId !== subscription.id) ||
+			item.price.livemode !== (scope.mode === "live") ||
+			item.price.currency !== contract.currency ||
+			item.price.unit_amount !== contract.amount ||
+			item.price.recurring?.interval !== contract.interval ||
+			item.price.recurring.interval_count !== contract.intervalCount ||
+			item.price.recurring.usage_type !== "licensed" ||
+			item.price.billing_scheme !== "per_unit" ||
+			item.price.transform_quantity ||
+			(contract.priceId && item.price.id !== contract.priceId)
+		)
+			throw new SubscriptionError(
+				"UNRECOGNIZED_SUBSCRIPTION",
+				"Subscription does not match its purchase",
+				409,
+			);
+	} else recurringPrice(item.price, scope, false);
 	return {
 		id: subscription.id,
 		userId,
 		customerId,
-		planCode: plan.code,
+		planCode: purchase?.contract.pricing.kind === "dynamic" ? "" : plan!.code,
 		priceId: item.price.id,
-		status: subscription.status,
+		status: subscription.pause_collection ? "paused" : subscription.status,
 		periodEnd: item.current_period_end,
 		cancelAtPeriodEnd: subscription.cancel_at_period_end,
 		verifiedAt: now,
 		lastError: null,
+		purchaseReference: purchase?.reference ?? null,
 	};
 }
 
@@ -134,7 +158,7 @@ export function invoicePeriods(
 			!details ||
 			details.subscription !== subscription.id ||
 			details.proration ||
-			!plan ||
+			(!plan && !subscription.purchaseReference) ||
 			line.quantity !== 1 ||
 			line.amount <= 0
 		)
@@ -150,7 +174,7 @@ export function invoicePeriods(
 				id: invoice.id + ":" + line.id,
 				invoiceId: invoice.id,
 				subscriptionId: subscription.id,
-				planCode: plan.code,
+				planCode: plan?.code ?? "",
 				startsAt: line.period.start,
 				endsAt: line.period.end,
 			},
@@ -166,7 +190,15 @@ export function memberProjection(
 	now: number,
 ): MemberBilling {
 	const valid = periods.filter(
-		(period) => period.startsAt * 1000 <= now && period.endsAt * 1000 > now,
+		(period) =>
+			period.eligible === true &&
+			period.startsAt * 1000 <= now &&
+			period.endsAt * 1000 > now &&
+			subscriptions.some(
+				(subscription) =>
+					subscription.id === period.subscriptionId &&
+					["active", "past_due", "canceled"].includes(subscription.status),
+			),
 	);
 	const entitlements: Record<string, boolean | number> = {};
 	for (const period of valid) {

package/src/subscriptions/purchases.ts

@@ -0,0 +1,329 @@
+import { createHash } from "node:crypto";
+
+import type Stripe from "stripe";
+
+import { recurringPrice } from "./projection.js";
+import type { SubscriptionRepository } from "./repository.js";
+import { purchaseSchema } from "./schemas.js";
+import {
+	SubscriptionError,
+	type BillingSubject,
+	type PurchaseContract,
+	type SubscriptionPurchaseInput,
+	type SubscriptionPurchase,
+	type SubscriptionScope,
+} from "./types.js";
+
+export const digest = (value: unknown) =>
+	createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const relationId = (value: string | { id: string } | null | undefined) =>
+	typeof value === "string" ? value : (value?.id ?? null);
+export interface PurchaseContext {
+	stripe: Stripe;
+	repository: SubscriptionRepository;
+	scope: SubscriptionScope;
+	now: () => number;
+	origin: string;
+}
+const idempotency = (context: PurchaseContext, ...values: unknown[]) =>
+	"dineway:" + digest([context.repository.scope, ...values]);
+const purchaseInput = ({
+	reference,
+	groupKey,
+	pricing,
+	firstPeriodCredit,
+	returnPath,
+	locale,
+}: SubscriptionPurchaseInput) =>
+	purchaseSchema.parse({ reference, groupKey, pricing, firstPeriodCredit, returnPath, locale });
+export function purchaseMetadata(context: PurchaseContext, userId: string, reference: string) {
+	return { dineway_app: context.scope.namespace, user_id: userId, purchase_reference: reference };
+}
+
+async function customer(
+	context: PurchaseContext,
+	store: SubscriptionRepository,
+	userId: string,
+	subject: BillingSubject,
+) {
+	const existing = await store.customer(userId);
+	if (existing) return existing;
+	const attemptKey = "customer:" + userId;
+	const attempt = await store.attempt(attemptKey);
+	if (attempt) {
+		const listed = await context.stripe.customers.list({ email: attempt.fingerprint, limit: 100 });
+		if (listed.has_more)
+			throw new SubscriptionError(
+				"CUSTOMER_REVIEW_REQUIRED",
+				"Customer recovery exceeds its safe limit",
+				409,
+			);
+		const matches = listed.data.filter(
+			(value) =>
+				value.metadata.dineway_app === context.scope.namespace &&
+				value.metadata.user_id === userId &&
+				value.livemode === (context.scope.mode === "live"),
+		);
+		if (matches.length > 1)
+			throw new SubscriptionError(
+				"CUSTOMER_REVIEW_REQUIRED",
+				"Multiple customers match this billing subject",
+				409,
+			);
+		if (matches[0]) {
+			await store.saveCustomer(userId, matches[0].id, subject);
+			return matches[0].id;
+		}
+	}
+	if (attempt && context.now() - attempt.created_at > 23 * 3600000) {
+		throw new SubscriptionError(
+			"CUSTOMER_REVIEW_REQUIRED",
+			"An unconfirmed customer creation requires reconciliation",
+			409,
+		);
+	}
+	// Pin the email as part of the request so a retry cannot change Stripe's idempotent payload.
+	const email = attempt ? attempt.fingerprint : subject.email;
+	if (!attempt)
+		await store.saveAttempt(attemptKey, {
+			fingerprint: email,
+			request_id: userId,
+			created_at: context.now(),
+			session_id: null,
+		});
+	const created = await context.stripe.customers.create(
+		{ email, metadata: { dineway_app: context.scope.namespace, user_id: userId } },
+		{ idempotencyKey: idempotency(context, "customer", userId) },
+	);
+	if (created.livemode !== (context.scope.mode === "live"))
+		throw new SubscriptionError("MODE_MISMATCH", "Invalid customer mode");
+	await store.saveCustomer(userId, created.id, subject);
+	return created.id;
+}
+
+export async function createPurchase(
+	context: PurchaseContext,
+	userId: string,
+	subject: BillingSubject,
+	input: SubscriptionPurchaseInput,
+) {
+	const parsed = purchaseSchema.parse(input);
+	return context.repository.withLock("member:" + userId, async (store) => {
+		const previous = await store.purchase(parsed.reference);
+		if (previous) {
+			if (previous.userId !== userId)
+				throw new SubscriptionError("NOT_FOUND", "Purchase not found", 404);
+			if (digest(purchaseInput(previous.contract)) !== digest(parsed))
+				throw new SubscriptionError(
+					"PURCHASE_CONFLICT",
+					"A purchase reference cannot change its contract",
+					409,
+				);
+			return resumePurchase(context, store, previous);
+		}
+		const open = await store.openPurchase(userId, parsed.groupKey);
+		if (open)
+			throw new SubscriptionError(
+				"SUBSCRIPTION_EXISTS",
+				"Resolve the existing purchase before starting another",
+				409,
+			);
+		let contract: PurchaseContract;
+		if (parsed.pricing.kind === "catalogue") {
+			const pricing = parsed.pricing;
+			const plan = (await store.plans()).find(
+				(value) => value.enabled && value.code === pricing.planCode,
+			);
+			const price = plan?.prices.find(
+				(value) => value.enabled && value.interval === pricing.interval,
+			);
+			if (!price) throw new SubscriptionError("PLAN_UNAVAILABLE", "This plan is unavailable", 409);
+			const verified = recurringPrice(
+				await context.stripe.prices.retrieve(price.id),
+				context.scope,
+			);
+			if (
+				verified.amount !== price.amount ||
+				verified.currency !== price.currency ||
+				verified.productId !== price.productId ||
+				verified.interval !== price.interval
+			)
+				throw new SubscriptionError("PRICE_CHANGED", "Refresh the plan price before checkout", 409);
+			contract = {
+				...parsed,
+				amount: price.amount,
+				currency: price.currency,
+				interval: price.interval,
+				intervalCount: 1,
+				priceId: price.id,
+				couponId: null,
+			};
+		} else {
+			contract = {
+				...parsed,
+				amount: parsed.pricing.amount,
+				currency: parsed.pricing.currency,
+				interval: parsed.pricing.interval,
+				intervalCount: parsed.pricing.intervalCount,
+				priceId: null,
+				couponId: null,
+			};
+		}
+		if (
+			parsed.firstPeriodCredit > contract.amount ||
+			(parsed.pricing.kind === "catalogue" && parsed.firstPeriodCredit)
+		)
+			throw new SubscriptionError(
+				"INVALID_CREDIT",
+				"Credit must fit a dynamic purchase's first invoice",
+			);
+		if (parsed.firstPeriodCredit)
+			contract.couponId = "dw_" + digest([store.scope, parsed.reference, "credit"]);
+		await customer(context, store, userId, subject);
+		await store.savePurchase(
+			userId,
+			contract,
+			digest(parsed),
+			Math.floor(context.now() / 1000) + 3600,
+		);
+		return resumePurchase(context, store, (await store.purchase(parsed.reference))!);
+	});
+}
+
+export async function resumePurchase(
+	context: PurchaseContext,
+	store: SubscriptionRepository,
+	purchase: SubscriptionPurchase,
+): Promise<{ reference: string; url: string | null; status: string }> {
+	const customerId = await store.customer(purchase.userId);
+	if (!customerId)
+		throw new SubscriptionError("CUSTOMER_NOT_FOUND", "No billing account exists", 404);
+	const { contract } = purchase;
+	let session: Stripe.Checkout.Session | undefined;
+	if (purchase.sessionId)
+		session = await context.stripe.checkout.sessions.retrieve(purchase.sessionId);
+	else {
+		const sessions = await context.stripe.checkout.sessions.list({
+			customer: customerId,
+			limit: 100,
+		});
+		if (sessions.has_more)
+			throw new SubscriptionError(
+				"REVIEW_REQUIRED",
+				"Checkout recovery exceeds its safe limit",
+				409,
+			);
+		const matches = sessions.data.filter(
+			(value) =>
+				value.metadata?.dineway_app === context.scope.namespace &&
+				value.metadata.purchase_reference === purchase.reference,
+		);
+		if (matches.length > 1)
+			throw new SubscriptionError("REVIEW_REQUIRED", "Purchase has multiple checkouts", 409);
+		session = matches[0];
+	}
+	if (!session) {
+		if (
+			purchase.closed ||
+			purchase.cancelMode ||
+			purchase.expiresAt < Math.floor(context.now() / 1000) + 1800
+		)
+			throw new SubscriptionError(
+				"CHECKOUT_REVIEW_REQUIRED",
+				"The checkout outcome must be confirmed before retrying",
+				409,
+			);
+		const metadata = purchaseMetadata(context, purchase.userId, purchase.reference);
+		if (contract.couponId) {
+			const coupon = await context.stripe.coupons.create(
+				{
+					id: contract.couponId,
+					amount_off: contract.firstPeriodCredit,
+					currency: contract.currency,
+					duration: "once",
+					max_redemptions: 1,
+					metadata,
+				},
+				{ idempotencyKey: idempotency(context, "coupon", purchase.reference) },
+			);
+			if (
+				coupon.id !== contract.couponId ||
+				coupon.amount_off !== contract.firstPeriodCredit ||
+				coupon.currency !== contract.currency ||
+				coupon.livemode !== (context.scope.mode === "live") ||
+				coupon.duration !== "once" ||
+				coupon.max_redemptions !== 1 ||
+				coupon.percent_off !== null ||
+				Object.entries(metadata).some(([key, value]) => coupon.metadata?.[key] !== value)
+			)
+				throw new SubscriptionError(
+					"INVALID_CREDIT",
+					"Credit coupon does not match the purchase",
+					409,
+				);
+		}
+		const returnUrl = new URL(contract.returnPath, context.origin);
+		if (returnUrl.origin !== context.origin)
+			throw new SubscriptionError("INVALID_RETURN_URL", "Return to this site");
+		const successUrl = new URL(returnUrl);
+		successUrl.searchParams.set("checkout", "returned");
+		const line: Stripe.Checkout.SessionCreateParams.LineItem = contract.priceId
+			? { price: contract.priceId, quantity: 1 }
+			: {
+					quantity: 1,
+					price_data: {
+						currency: contract.currency,
+						unit_amount: contract.amount,
+						recurring: { interval: contract.interval, interval_count: contract.intervalCount },
+						product_data: {
+							name: contract.pricing.kind === "dynamic" ? contract.pricing.name : "Subscription",
+							metadata,
+						},
+					},
+				};
+		await store.updatePurchase(purchase.reference, { last_attempt_at: context.now() });
+		session = await context.stripe.checkout.sessions.create(
+			{
+				mode: "subscription",
+				customer: customerId,
+				line_items: [line],
+				payment_method_types: ["card"],
+				payment_method_collection: "always",
+				client_reference_id: purchase.reference,
+				metadata,
+				subscription_data: { metadata },
+				success_url: successUrl.href,
+				cancel_url: returnUrl.href,
+				locale: purchaseInput(contract).locale,
+				expires_at: purchase.expiresAt,
+				allow_promotion_codes: false,
+				...(contract.couponId ? { discounts: [{ coupon: contract.couponId }] } : {}),
+			},
+			{ idempotencyKey: idempotency(context, "checkout", purchase.reference) },
+		);
+	}
+	if (
+		relationId(session.customer) !== customerId ||
+		session.mode !== "subscription" ||
+		session.livemode !== (context.scope.mode === "live") ||
+		session.metadata?.dineway_app !== context.scope.namespace ||
+		session.metadata.user_id !== purchase.userId ||
+		session.metadata.purchase_reference !== purchase.reference ||
+		session.client_reference_id !== purchase.reference
+	)
+		throw new SubscriptionError("OWNER_CONFLICT", "Checkout ownership conflict", 409);
+	await store.updatePurchase(purchase.reference, {
+		session_id: session.id,
+		subscription_id: relationId(session.subscription),
+		closed: Number(session.status === "expired"),
+		last_error: null,
+		last_attempt_at: context.now(),
+	});
+	if (session.url && new URL(session.url).origin !== "https://checkout.stripe.com")
+		throw new SubscriptionError("INVALID_DESTINATION", "Invalid checkout destination", 502);
+	return {
+		reference: purchase.reference,
+		url: session.status === "open" ? session.url : null,
+		status: session.status ?? "unknown",
+	};
+}

package/src/subscriptions/refunds.ts

@@ -0,0 +1,134 @@
+import { z } from "astro/zod";
+import type Stripe from "stripe";
+
+import { collectBounded, inspectCharge } from "./funding.js";
+import { digest, relationId, type PurchaseContext } from "./purchases.js";
+import { SubscriptionError } from "./types.js";
+
+export interface SubscriptionRefundInput {
+	reference: string;
+	chargeId: string;
+	amount: number;
+	currency: string;
+	metadata?: Record<string, string>;
+}
+const schema = z
+	.object({
+		reference: z
+			.string()
+			.min(1)
+			.max(160)
+			.regex(/^[A-Za-z0-9_.:-]+$/),
+		chargeId: z.string().regex(/^ch_[A-Za-z0-9]+$/),
+		amount: z.number().int().min(1).max(99999999),
+		currency: z.string().regex(/^[a-z]{3}$/),
+		metadata: z
+			.record(
+				z
+					.string()
+					.min(1)
+					.max(40)
+					.regex(/^[a-zA-Z0-9_.-]+$/),
+				z.string().max(500),
+			)
+			.refine((value) => Object.keys(value).length <= 40)
+			.default({}),
+	})
+	.strict();
+
+export async function refundCharge(
+	context: PurchaseContext,
+	userId: string,
+	input: SubscriptionRefundInput,
+) {
+	const parsed = schema.parse(input);
+	const fingerprint = JSON.stringify({ ...parsed, userId });
+	const key = "refund:" + parsed.reference;
+	return context.repository.withLock("refunds", async (store) => {
+		const previous = await store.attempt(key);
+		if (previous && previous.fingerprint !== fingerprint)
+			throw new SubscriptionError(
+				"REFUND_CONFLICT",
+				"A refund reference cannot change its amount or owner",
+				409,
+			);
+		const charge = await inspectCharge(context.stripe, context.scope, parsed.chargeId);
+		if (!charge.customerId || (await store.customerOwner(charge.customerId)) !== userId)
+			throw new SubscriptionError("NOT_FOUND", "Charge not found", 404);
+		const metadata = {
+			...parsed.metadata,
+			dineway_app: context.scope.namespace,
+			user_id: userId,
+			refund_reference: parsed.reference,
+		};
+		const known = await collectBounded(
+			context.stripe.refunds.list({ charge: parsed.chargeId, limit: 100 }),
+		);
+		const matches = known.filter(
+			(refund) =>
+				refund.metadata?.dineway_app === context.scope.namespace &&
+				refund.metadata.refund_reference === parsed.reference,
+		);
+		if (matches.length > 1)
+			throw new SubscriptionError(
+				"REFUND_REVIEW_REQUIRED",
+				"Multiple refunds match the reference",
+				409,
+			);
+		let refund: Stripe.Refund | undefined = previous?.session_id
+			? await context.stripe.refunds.retrieve(previous.session_id)
+			: matches[0];
+		const attempt = previous ?? {
+			fingerprint,
+			request_id: parsed.reference,
+			session_id: null,
+			created_at: context.now(),
+		};
+		if (!refund) {
+			if (context.now() - attempt.created_at > 23 * 3600000)
+				throw new SubscriptionError(
+					"REFUND_REVIEW_REQUIRED",
+					"The refund outcome must be confirmed before retrying",
+					409,
+				);
+			const reserved = known
+				.filter((value) => !["failed", "canceled"].includes(value.status ?? "unknown"))
+				.reduce((total, value) => total + value.amount, 0);
+			if (
+				!charge.settled ||
+				charge.disputes.some((value) => !["won", "warning_closed"].includes(value.status)) ||
+				charge.currency !== parsed.currency ||
+				parsed.amount > charge.amount - Math.max(reserved, charge.refunded)
+			)
+				throw new SubscriptionError(
+					"REFUND_UNAVAILABLE",
+					"The charge has insufficient refundable funds",
+					409,
+				);
+			await store.saveAttempt(key, attempt);
+			refund = await context.stripe.refunds.create(
+				{ charge: parsed.chargeId, amount: parsed.amount, metadata },
+				{ idempotencyKey: "dineway-refund:" + digest([store.scope, parsed.reference]) },
+			);
+		}
+		if (
+			relationId(refund.charge) !== parsed.chargeId ||
+			refund.amount !== parsed.amount ||
+			refund.currency !== parsed.currency ||
+			Object.entries(metadata).some(([name, value]) => refund.metadata?.[name] !== value)
+		)
+			throw new SubscriptionError(
+				"REFUND_CONFLICT",
+				"Refund evidence does not match the request",
+				409,
+			);
+		await store.saveAttempt(key, { ...attempt, session_id: refund.id });
+		return {
+			id: refund.id,
+			amount: refund.amount,
+			currency: refund.currency,
+			status: refund.status ?? "unknown",
+			metadata: refund.metadata ?? {},
+		};
+	});
+}