@dineway-ai/plugin-payment 0.2.5 → 0.2.7

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 ?? {},
+		};
+	});
+}

package/src/subscriptions/repository.ts

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 
 import type { Database } from "dineway";
-import type { Kysely, Transaction } from "kysely";
+import type { Kysely, Transaction, Selectable } from "kysely";
 
+import type { PaymentDatabase, PaymentTables } from "../database/types.js";
 import { entitlementSchema } from "./schemas.js";
 import {
 	SubscriptionError,
@@ -12,11 +13,16 @@ import {
 	type SubscriptionPlan,
 	type SubscriptionPrice,
 	type SubscriptionScope,
+	type BillingSubject,
+	type PurchaseContract,
+	type SubscriptionPurchase,
+	type SubscriptionSnapshot,
+	type SubscriptionChange,
 } from "./types.js";
 
-type Db = Kysely<Database>;
-type Trx = Transaction<Database>;
-type SubscriptionRow = Database["payment_member_subscriptions"];
+type Db = Kysely<PaymentDatabase>;
+type Trx = Transaction<PaymentDatabase>;
+type SubscriptionRow = Selectable<PaymentDatabase["payment_member_subscriptions"]>;
 const scopedId = ["scope", "id"] as const;
 const accountPattern = /^acct_[A-Za-z0-9]+$/;
 const namespacePattern = /^[a-z][a-z0-9_-]{0,63}$/;
@@ -35,12 +41,14 @@ export function subscriptionScopeKey(scope: SubscriptionScope): string {
 
 export class SubscriptionRepository {
 	readonly scope: string;
+	readonly db: Db;
 	constructor(
-		readonly db: Db,
+		db: Kysely<Database> | Kysely<PaymentDatabase>,
 		scope: SubscriptionScope,
 		readonly now: () => number = Date.now,
 		private readonly lease?: { id: string; token: string },
 	) {
+		this.db = db.withTables<PaymentTables>();
 		this.scope = subscriptionScopeKey(scope);
 		this.scopeDetails = scope;
 	}
@@ -141,7 +149,13 @@ export class SubscriptionRepository {
 						enabled: Number(price.enabled),
 					})
 					.onConflict((conflict) =>
-						conflict.columns(keyColumns()).doUpdateSet({ enabled: Number(price.enabled) }),
+						conflict.columns(keyColumns()).doUpdateSet({
+							product_id: price.productId,
+							currency: price.currency,
+							amount: price.amount,
+							interval: price.interval,
+							enabled: Number(price.enabled),
+						}),
 					)
 					.execute();
 			}
@@ -168,12 +182,27 @@ export class SubscriptionRepository {
 		return row?.id ?? null;
 	}
 
-	async saveCustomer(userId: string, customerId: string): Promise<void> {
+	async subject(userId: string): Promise<BillingSubject | null> {
+		const row = await this.db
+			.selectFrom("payment_subscription_customers")
+			.select("subject")
+			.where("scope", "=", this.scope)
+			.where("id", "=", userId)
+			.executeTakeFirst();
+		return row?.subject ? JSON.parse(row.subject) : null;
+	}
+
+	async saveCustomer(userId: string, customerId: string, subject?: BillingSubject): Promise<void> {
 		await this.db.transaction().execute(async (trx) => {
 			await this.assertLease(trx);
 			await trx
 				.insertInto("payment_subscription_customers")
-				.values({ scope: this.scope, id: userId, customer_id: customerId })
+				.values({
+					scope: this.scope,
+					id: userId,
+					customer_id: customerId,
+					subject: subject ? JSON.stringify(subject) : null,
+				})
 				.onConflict((conflict) => conflict.columns(keyColumns()).doNothing())
 				.execute();
 			const saved = await trx
@@ -245,6 +274,8 @@ export class SubscriptionRepository {
 			planCode: row.plan_code,
 			startsAt: row.starts_at,
 			endsAt: row.ends_at,
+			eligible: row.eligible === 1,
+			evidence: JSON.parse(row.evidence),
 		}));
 	}
 
@@ -263,7 +294,7 @@ export class SubscriptionRepository {
 				.executeTakeFirst();
 			const existing = await trx
 				.selectFrom("payment_member_subscriptions")
-				.select(["user_id", "customer_id"])
+				.select(["user_id", "customer_id", "revision"])
 				.where("scope", "=", this.scope)
 				.where("id", "=", state.id)
 				.executeTakeFirst();
@@ -283,7 +314,10 @@ export class SubscriptionRepository {
 				period_end: state.periodEnd,
 				cancel_at_period_end: Number(state.cancelAtPeriodEnd),
 				verified_at: state.verifiedAt,
+				sync_attempted_at: this.now(),
 				last_error: state.lastError,
+				purchase_reference: state.purchaseReference ?? null,
+				revision: (existing?.revision ?? 0) + 1,
 			};
 			await trx
 				.insertInto("payment_member_subscriptions")
@@ -301,15 +335,69 @@ export class SubscriptionRepository {
 						plan_code: period.planCode,
 						starts_at: period.startsAt,
 						ends_at: period.endsAt,
+						eligible: Number(period.eligible === true),
+						evidence: JSON.stringify(period.evidence ?? {}),
 					})
-					.onConflict((conflict) => conflict.columns(keyColumns()).doNothing())
+					.onConflict((conflict) =>
+						conflict.columns(keyColumns()).doUpdateSet({
+							eligible: Number(period.eligible === true),
+							evidence: JSON.stringify(period.evidence ?? {}),
+						}),
+					)
+					.execute();
+			}
+			if (state.purchaseReference) {
+				const purchase = await trx
+					.selectFrom("payment_subscription_purchases")
+					.select(["subscription_id", "user_id", "closed"])
+					.where("scope", "=", this.scope)
+					.where("id", "=", state.purchaseReference)
+					.executeTakeFirst();
+				if (
+					!purchase ||
+					purchase.user_id !== state.userId ||
+					(purchase.subscription_id && purchase.subscription_id !== state.id)
+				)
+					throw new SubscriptionError("PURCHASE_CONFLICT", "Purchase subscription conflict", 409);
+				await trx
+					.updateTable("payment_subscription_purchases")
+					.set({
+						subscription_id: state.id,
+						closed:
+							purchase.closed || Number(["canceled", "incomplete_expired"].includes(state.status)),
+						last_error: null,
+					})
+					.where("scope", "=", this.scope)
+					.where("id", "=", state.purchaseReference)
 					.execute();
 			}
+			const transactional = new SubscriptionRepository(trx, this.scopeDetails, this.now);
+			const snapshot = await transactional.snapshot(state.id);
+			await trx
+				.insertInto("payment_subscription_changes")
+				.values({
+					scope: this.scope,
+					id: randomUUID(),
+					subscription_id: state.id,
+					revision: values.revision,
+					snapshot: JSON.stringify(snapshot),
+					created_at: this.now(),
+				})
+				.execute();
 			if (eventId)
 				await trx
 					.insertInto("payment_subscription_events")
-					.values({ scope: this.scope, id: eventId, received_at: this.now() })
-					.onConflict((conflict) => conflict.columns(keyColumns()).doNothing())
+					.values({
+						scope: this.scope,
+						id: eventId,
+						received_at: this.now(),
+						processed_at: this.now(),
+					})
+					.onConflict((conflict) =>
+						conflict
+							.columns(keyColumns())
+							.doUpdateSet({ processed_at: this.now(), last_error: null }),
+					)
 					.execute();
 		});
 	}
@@ -317,7 +405,7 @@ export class SubscriptionRepository {
 	async recordSyncFailure(id: string, verifiedAt: number): Promise<void> {
 		await this.db
 			.updateTable("payment_member_subscriptions")
-			.set({ last_error: "SYNC_UNAVAILABLE" })
+			.set({ last_error: "SYNC_UNAVAILABLE", sync_attempted_at: this.now() })
 			.where("scope", "=", this.scope)
 			.where("id", "=", id)
 			.where("verified_at", "=", verifiedAt)
@@ -330,6 +418,7 @@ export class SubscriptionRepository {
 				.select("id")
 				.where("scope", "=", this.scope)
 				.where("id", "=", id)
+				.where("processed_at", "is not", null)
 				.executeTakeFirst(),
 		);
 	}
@@ -379,6 +468,254 @@ export class SubscriptionRepository {
 		});
 	}
 
+	async purchase(reference: string): Promise<SubscriptionPurchase | null> {
+		const row = await this.db
+			.selectFrom("payment_subscription_purchases")
+			.selectAll()
+			.where("scope", "=", this.scope)
+			.where("id", "=", reference)
+			.executeTakeFirst();
+		if (!row) return null;
+		return {
+			reference: row.id,
+			userId: row.user_id,
+			contract: JSON.parse(row.contract),
+			createdAt: row.created_at,
+			expiresAt: row.expires_at,
+			sessionId: row.session_id,
+			subscriptionId: row.subscription_id,
+			closed: row.closed === 1,
+			cancelMode: row.cancel_mode as SubscriptionPurchase["cancelMode"],
+			lastError: row.last_error,
+		};
+	}
+	async openPurchase(userId: string, groupKey: string) {
+		const row = await this.db
+			.selectFrom("payment_subscription_purchases")
+			.select("id")
+			.where("scope", "=", this.scope)
+			.where("user_id", "=", userId)
+			.where("group_key", "=", groupKey)
+			.where("closed", "=", 0)
+			.executeTakeFirst();
+		return row ? this.purchase(row.id) : null;
+	}
+	async listPurchases(cursor?: string, limit = 50) {
+		let query = this.db
+			.selectFrom("payment_subscription_purchases")
+			.select("id")
+			.where("scope", "=", this.scope);
+		if (cursor) query = query.where("id", ">", cursor);
+		const rows = await query
+			.orderBy("id")
+			.limit(limit + 1)
+			.execute();
+		const items = await Promise.all(
+			rows.slice(0, limit).map(async (row) => {
+				const purchase = (await this.purchase(row.id))!;
+				return { ...purchase, subject: await this.subject(purchase.userId) };
+			}),
+		);
+		return { items, nextCursor: rows.length > limit ? rows[limit - 1]?.id : undefined };
+	}
+	async savePurchase(
+		userId: string,
+		contract: PurchaseContract,
+		digest: string,
+		expiresAt: number,
+	) {
+		await this.db.transaction().execute(async (trx) => {
+			await this.assertLease(trx);
+			await trx
+				.insertInto("payment_subscription_purchases")
+				.values({
+					scope: this.scope,
+					id: contract.reference,
+					user_id: userId,
+					group_key: contract.groupKey,
+					contract: JSON.stringify(contract),
+					fingerprint: digest,
+					created_at: this.now(),
+					expires_at: expiresAt,
+				})
+				.execute();
+		});
+	}
+	async updatePurchase(
+		reference: string,
+		values: Partial<
+			Pick<
+				Selectable<PaymentDatabase["payment_subscription_purchases"]>,
+				| "session_id"
+				| "subscription_id"
+				| "closed"
+				| "cancel_mode"
+				| "last_attempt_at"
+				| "last_error"
+			>
+		>,
+	) {
+		await this.db.transaction().execute(async (trx) => {
+			await this.assertLease(trx);
+			const current = await trx
+				.selectFrom("payment_subscription_purchases")
+				.select(["session_id", "subscription_id", "closed", "cancel_mode"])
+				.where("scope", "=", this.scope)
+				.where("id", "=", reference)
+				.executeTakeFirstOrThrow();
+			for (const field of ["session_id", "subscription_id"] as const) {
+				if (current[field] && values[field] && current[field] !== values[field])
+					throw new SubscriptionError(
+						"PURCHASE_CONFLICT",
+						"Purchase provider identity changed",
+						409,
+					);
+			}
+			await trx
+				.updateTable("payment_subscription_purchases")
+				.set({
+					...values,
+					session_id: current.session_id ?? values.session_id,
+					subscription_id: current.subscription_id ?? values.subscription_id,
+					closed: current.closed || values.closed,
+					cancel_mode:
+						current.cancel_mode === "immediate"
+							? "immediate"
+							: (values.cancel_mode ?? current.cancel_mode),
+				})
+				.where("scope", "=", this.scope)
+				.where("id", "=", reference)
+				.execute();
+		});
+	}
+	async snapshot(id: string): Promise<SubscriptionSnapshot> {
+		const subscription = await this.subscription(id);
+		if (!subscription) throw new SubscriptionError("NOT_FOUND", "Subscription not found", 404);
+		return {
+			subscription,
+			subject: await this.subject(subscription.userId),
+			purchase: subscription.purchaseReference
+				? await this.purchase(subscription.purchaseReference)
+				: null,
+			periods: (await this.periods(subscription.userId)).filter(
+				(period) => period.subscriptionId === id,
+			),
+		};
+	}
+	async changes(limit = 50): Promise<SubscriptionChange[]> {
+		const rows = await this.db
+			.selectFrom("payment_subscription_changes")
+			.selectAll()
+			.where("scope", "=", this.scope)
+			.where("acknowledged_at", "is", null)
+			.orderBy("created_at")
+			.orderBy("subscription_id")
+			.orderBy("revision")
+			.limit(limit)
+			.execute();
+		return rows.map((row) => ({
+			id: row.id,
+			revision: row.revision,
+			createdAt: row.created_at,
+			snapshot: JSON.parse(row.snapshot),
+		}));
+	}
+	async acknowledgeChange(id: string) {
+		await this.db
+			.updateTable("payment_subscription_changes")
+			.set({ acknowledged_at: this.now() })
+			.where("scope", "=", this.scope)
+			.where("id", "=", id)
+			.where("acknowledged_at", "is", null)
+			.execute();
+	}
+	async receiveEvent(event: {
+		id: string;
+		digest: string;
+		type: string;
+		objectType: string | null;
+		objectId: string | null;
+		subscriptionId: string | null;
+		payload: string;
+	}) {
+		await this.db.transaction().execute(async (trx) => {
+			await trx
+				.insertInto("payment_subscription_events")
+				.values({
+					scope: this.scope,
+					id: event.id,
+					digest: event.digest,
+					event_type: event.type,
+					object_type: event.objectType,
+					object_id: event.objectId,
+					subscription_id: event.subscriptionId,
+					payload: event.payload,
+					received_at: this.now(),
+				})
+				.onConflict((conflict) => conflict.columns(keyColumns()).doNothing())
+				.execute();
+			const stored = await trx
+				.selectFrom("payment_subscription_events")
+				.select("digest")
+				.where("scope", "=", this.scope)
+				.where("id", "=", event.id)
+				.executeTakeFirstOrThrow();
+			if (stored.digest && stored.digest !== event.digest)
+				throw new SubscriptionError("EVENT_CONFLICT", "Webhook event content changed", 409);
+		});
+	}
+	async pendingEvents(limit: number) {
+		return this.db
+			.selectFrom("payment_subscription_events")
+			.selectAll()
+			.where("scope", "=", this.scope)
+			.where("processed_at", "is", null)
+			.orderBy("last_attempt_at")
+			.orderBy("received_at")
+			.orderBy("id")
+			.limit(limit)
+			.execute();
+	}
+	async finishEvent(id: string, error: string | null) {
+		await this.db.transaction().execute(async (trx) => {
+			await this.assertLease(trx);
+			await trx
+				.updateTable("payment_subscription_events")
+				.set({
+					last_attempt_at: this.now(),
+					last_error: error,
+					processed_at: error ? null : this.now(),
+				})
+				.where("scope", "=", this.scope)
+				.where("id", "=", id)
+				.where("processed_at", "is", null)
+				.execute();
+		});
+	}
+	async pendingPurchases(limit: number) {
+		return this.db
+			.selectFrom("payment_subscription_purchases")
+			.select("id")
+			.where("scope", "=", this.scope)
+			.where("closed", "=", 0)
+			.where((eb) => eb.or([eb("subscription_id", "is", null), eb("cancel_mode", "is not", null)]))
+			.orderBy("last_attempt_at")
+			.orderBy("id")
+			.limit(limit)
+			.execute();
+	}
+	async staleSubscriptions(limit: number) {
+		return this.db
+			.selectFrom("payment_member_subscriptions")
+			.select("id")
+			.where("scope", "=", this.scope)
+			.where("sync_attempted_at", "<", this.now() - 900000)
+			.orderBy("sync_attempted_at")
+			.orderBy("id")
+			.limit(limit)
+			.execute();
+	}
+
 	async withLock<T>(
 		id: string,
 		action: (repository: SubscriptionRepository) => Promise<T>,
@@ -439,5 +776,7 @@ function projectSubscription(row: SubscriptionRow): MemberSubscription {
 		cancelAtPeriodEnd: row.cancel_at_period_end === 1,
 		verifiedAt: row.verified_at,
 		lastError: row.last_error,
+		purchaseReference: row.purchase_reference,
+		revision: row.revision,
 	};
 }

package/src/subscriptions/routes.ts

@@ -12,6 +12,8 @@ import {
 	memberListSchema,
 	saveSubscriptionPlanSchema,
 	subscriptionIdSchema,
+	stripeProductListSchema,
+	stripePriceListSchema,
 } from "./schemas.js";
 import type { PaymentSubscriptionService } from "./service.js";
 import { SubscriptionError, type SubscriptionOptions } from "./types.js";
@@ -95,6 +97,16 @@ export function createSubscriptionRoutes(
 		"subscriptions/plans/list": privateRoute(empty, "payments:manage", async () => ({
 			items: await (await service()).listPlans(true),
 		})),
+		"subscriptions/products/list": privateRoute(
+			stripeProductListSchema,
+			"payments:manage",
+			async (context) => (await service()).listStripeProducts(context.input),
+		),
+		"subscriptions/prices/list": privateRoute(
+			stripePriceListSchema,
+			"payments:manage",
+			async (context) => (await service()).listStripePrices(context.input),
+		),
 		"subscriptions/plans/save": privateRoute(
 			saveSubscriptionPlanSchema,
 			"payments:manage",
@@ -106,6 +118,14 @@ export function createSubscriptionRoutes(
 		"subscriptions/get": privateRoute(subscriptionIdSchema, "payments:manage", async (context) =>
 			(await service()).subscriptionDetail(context.input.subscriptionId),
 		),
+		"subscriptions/purchases/list": privateRoute(
+			memberListSchema,
+			"payments:manage",
+			async (context) => (await service()).listPurchases(context.input.cursor, context.input.limit),
+		),
+		"subscriptions/reconcile": privateRoute(empty, "payments:manage", async () =>
+			(await service()).reconcile(10),
+		),
 		"subscriptions/sync": privateRoute(subscriptionIdSchema, "payments:manage", async (context) => {
 			const client = await service();
 			await client.subscriptionDetail(context.input.subscriptionId);