refactor progress

packages/api/src/stripe/ProductRegistry.tsx

@@ -0,0 +1,119 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {Config} from '@fluxer/api/src/Config';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+
+export enum ProductType {
+	MONTHLY_SUBSCRIPTION = 'monthly_subscription',
+	YEARLY_SUBSCRIPTION = 'yearly_subscription',
+	GIFT_1_MONTH = 'gift_1_month',
+	GIFT_1_YEAR = 'gift_1_year',
+}
+
+export interface ProductInfo {
+	type: ProductType;
+	premiumType: 1 | 2;
+	durationMonths: number;
+	isGift: boolean;
+	billingCycle?: 'monthly' | 'yearly';
+}
+
+export class ProductRegistry {
+	private products = new Map<string, ProductInfo>();
+
+	constructor() {
+		const prices = Config.stripe.prices;
+		if (!prices) return;
+
+		this.registerProduct(prices.monthlyUsd, {
+			type: ProductType.MONTHLY_SUBSCRIPTION,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 1,
+			isGift: false,
+			billingCycle: 'monthly',
+		});
+
+		this.registerProduct(prices.monthlyEur, {
+			type: ProductType.MONTHLY_SUBSCRIPTION,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 1,
+			isGift: false,
+			billingCycle: 'monthly',
+		});
+
+		this.registerProduct(prices.yearlyUsd, {
+			type: ProductType.YEARLY_SUBSCRIPTION,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 12,
+			isGift: false,
+			billingCycle: 'yearly',
+		});
+
+		this.registerProduct(prices.yearlyEur, {
+			type: ProductType.YEARLY_SUBSCRIPTION,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 12,
+			isGift: false,
+			billingCycle: 'yearly',
+		});
+
+		this.registerProduct(prices.gift1MonthUsd, {
+			type: ProductType.GIFT_1_MONTH,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 1,
+			isGift: true,
+		});
+
+		this.registerProduct(prices.gift1MonthEur, {
+			type: ProductType.GIFT_1_MONTH,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 1,
+			isGift: true,
+		});
+
+		this.registerProduct(prices.gift1YearUsd, {
+			type: ProductType.GIFT_1_YEAR,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 12,
+			isGift: true,
+		});
+
+		this.registerProduct(prices.gift1YearEur, {
+			type: ProductType.GIFT_1_YEAR,
+			premiumType: UserPremiumTypes.SUBSCRIPTION,
+			durationMonths: 12,
+			isGift: true,
+		});
+	}
+
+	private registerProduct(priceId: string | undefined, info: ProductInfo): void {
+		if (priceId) {
+			this.products.set(priceId, info);
+		}
+	}
+
+	getProduct(priceId: string): ProductInfo | null {
+		return this.products.get(priceId) || null;
+	}
+
+	isRecurringSubscription(info: ProductInfo): boolean {
+		return !info.isGift && info.premiumType === UserPremiumTypes.SUBSCRIPTION;
+	}
+}

packages/api/src/stripe/StripeController.tsx

@@ -0,0 +1,322 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {DefaultUserOnly, LoginRequired} from '@fluxer/api/src/middleware/AuthMiddleware';
+import {RateLimitMiddleware} from '@fluxer/api/src/middleware/RateLimitMiddleware';
+import {OpenAPI} from '@fluxer/api/src/middleware/ResponseTypeMiddleware';
+import {RateLimitConfigs} from '@fluxer/api/src/RateLimitConfig';
+import {mapGiftCodeToMetadataResponse, mapGiftCodeToResponse} from '@fluxer/api/src/stripe/StripeModel';
+import type {HonoApp} from '@fluxer/api/src/types/HonoEnv';
+import {Validator} from '@fluxer/api/src/Validator';
+import {StripeWebhookSignatureMissingError} from '@fluxer/errors/src/domains/payment/StripeWebhookSignatureMissingError';
+import {GiftCodeParam} from '@fluxer/schema/src/domains/common/CommonParamSchemas';
+import {
+	CreateCheckoutSessionRequest,
+	GiftCodeMetadataResponse,
+	GiftCodeResponse,
+} from '@fluxer/schema/src/domains/premium/GiftCodeSchemas';
+import {
+	PriceIdsQueryRequest,
+	PriceIdsResponse,
+	UrlResponse,
+	WebhookReceivedResponse,
+} from '@fluxer/schema/src/domains/premium/PremiumSchemas';
+import {z} from 'zod';
+
+export function StripeController(app: HonoApp) {
+	app.post(
+		'/stripe/webhook',
+		OpenAPI({
+			operationId: 'process_stripe_webhook',
+			summary: 'Process Stripe webhook',
+			description: 'Handles incoming Stripe webhook events for payment processing and subscription management.',
+			responseSchema: WebhookReceivedResponse,
+			statusCode: 200,
+			security: [],
+			tags: 'Billing',
+		}),
+		async (ctx) => {
+			const signature = ctx.req.header('stripe-signature');
+			if (!signature) {
+				throw new StripeWebhookSignatureMissingError();
+			}
+			const body = await ctx.req.text();
+			await ctx.get('stripeService').handleWebhook({body, signature});
+			return ctx.json({received: true});
+		},
+	);
+
+	app.post(
+		'/stripe/checkout/subscription',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_CHECKOUT_SUBSCRIPTION),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'create_checkout_session',
+			summary: 'Create checkout session',
+			description: 'Initiates a Stripe checkout session for user subscription purchases.',
+			responseSchema: UrlResponse,
+			statusCode: 200,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Billing',
+		}),
+		Validator('json', CreateCheckoutSessionRequest),
+		async (ctx) => {
+			const {price_id} = ctx.req.valid('json');
+			const userId = ctx.get('user').id;
+			const checkoutUrl = await ctx.get('stripeService').createCheckoutSession({
+				userId,
+				priceId: price_id,
+				isGift: false,
+			});
+			return ctx.json({url: checkoutUrl});
+		},
+	);
+
+	app.post(
+		'/stripe/checkout/gift',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_CHECKOUT_GIFT),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'create_gift_checkout_session',
+			summary: 'Create gift checkout session',
+			description: 'Creates a checkout session for purchasing premium gifts to send to other users.',
+			responseSchema: UrlResponse,
+			statusCode: 200,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Billing',
+		}),
+		Validator('json', CreateCheckoutSessionRequest),
+		async (ctx) => {
+			const {price_id} = ctx.req.valid('json');
+			const userId = ctx.get('user').id;
+			const checkoutUrl = await ctx.get('stripeService').createCheckoutSession({
+				userId,
+				priceId: price_id,
+				isGift: true,
+			});
+			return ctx.json({url: checkoutUrl});
+		},
+	);
+
+	app.get(
+		'/gifts/:code',
+		RateLimitMiddleware(RateLimitConfigs.GIFT_CODE_GET),
+		OpenAPI({
+			operationId: 'get_gift_code',
+			summary: 'Get gift code',
+			description: 'Retrieves information about a gift code, including sender details and premium entitlements.',
+			responseSchema: GiftCodeResponse,
+			statusCode: 200,
+			security: [],
+			tags: 'Gifts',
+		}),
+		Validator('param', GiftCodeParam),
+		async (ctx) => {
+			const {code} = ctx.req.valid('param');
+			const giftCode = await ctx.get('stripeService').getGiftCode(code);
+			const response = await mapGiftCodeToResponse({
+				giftCode,
+				userCacheService: ctx.get('userCacheService'),
+				requestCache: ctx.get('requestCache'),
+				includeCreator: true,
+			});
+			return ctx.json(response);
+		},
+	);
+
+	app.post(
+		'/gifts/:code/redeem',
+		RateLimitMiddleware(RateLimitConfigs.GIFT_CODE_REDEEM),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'redeem_gift_code',
+			summary: 'Redeem gift code',
+			description: 'Redeems a gift code for the authenticated user, applying premium benefits.',
+			responseSchema: null,
+			statusCode: 204,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Gifts',
+		}),
+		Validator('param', GiftCodeParam),
+		async (ctx) => {
+			const {code} = ctx.req.valid('param');
+			const userId = ctx.get('user').id;
+			await ctx.get('stripeService').redeemGiftCode(userId, code);
+			return ctx.body(null, 204);
+		},
+	);
+
+	app.get(
+		'/users/@me/gifts',
+		RateLimitMiddleware(RateLimitConfigs.GIFTS_LIST),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'list_user_gifts',
+			summary: 'List user gifts',
+			description: 'Lists all gift codes created by the authenticated user.',
+			responseSchema: z.array(GiftCodeMetadataResponse),
+			statusCode: 200,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Users',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			const gifts = await ctx.get('stripeService').getUserGifts(userId);
+			const responses = await Promise.all(
+				gifts.map((gift) =>
+					mapGiftCodeToMetadataResponse({
+						giftCode: gift,
+						userCacheService: ctx.get('userCacheService'),
+						requestCache: ctx.get('requestCache'),
+					}),
+				),
+			);
+			return ctx.json(responses);
+		},
+	);
+
+	app.get(
+		'/premium/price-ids',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_PRICE_IDS),
+		Validator('query', PriceIdsQueryRequest),
+		OpenAPI({
+			operationId: 'get_price_ids',
+			summary: 'Get Stripe price IDs',
+			description: 'Retrieves Stripe price IDs for premium subscriptions based on geographic location.',
+			responseSchema: PriceIdsResponse,
+			statusCode: 200,
+			security: [],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const priceIds = await ctx.get('stripeService').getPriceIds(ctx.req.valid('query').country_code);
+			return ctx.json(priceIds);
+		},
+	);
+
+	app.post(
+		'/premium/customer-portal',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_CUSTOMER_PORTAL),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'create_customer_portal',
+			summary: 'Create customer portal',
+			description:
+				'Creates a session URL for the authenticated user to manage their Stripe subscription via the customer portal.',
+			responseSchema: UrlResponse,
+			statusCode: 200,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			const url = await ctx.get('stripeService').createCustomerPortalSession(userId);
+			return ctx.json({url});
+		},
+	);
+
+	app.post(
+		'/premium/cancel-subscription',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_SUBSCRIPTION_CANCEL),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'cancel_subscription',
+			summary: 'Cancel subscription',
+			description: "Cancels the authenticated user's premium subscription at the end of the current billing period.",
+			responseSchema: null,
+			statusCode: 204,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			await ctx.get('stripeService').cancelSubscriptionAtPeriodEnd(userId);
+			return ctx.body(null, 204);
+		},
+	);
+
+	app.post(
+		'/premium/reactivate-subscription',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_SUBSCRIPTION_REACTIVATE),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'reactivate_subscription',
+			summary: 'Reactivate subscription',
+			description: 'Reactivates a previously cancelled premium subscription for the authenticated user.',
+			responseSchema: null,
+			statusCode: 204,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			await ctx.get('stripeService').reactivateSubscription(userId);
+			return ctx.body(null, 204);
+		},
+	);
+
+	app.post(
+		'/premium/visionary/rejoin',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_VISIONARY_REJOIN),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'rejoin_visionary_guild',
+			summary: 'Rejoin visionary guild',
+			description: 'Adds the authenticated user back to the visionary community guild after premium re-subscription.',
+			responseSchema: null,
+			statusCode: 204,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			await ctx.get('stripeService').rejoinVisionariesGuild(userId);
+			return ctx.body(null, 204);
+		},
+	);
+
+	app.post(
+		'/premium/operator/rejoin',
+		RateLimitMiddleware(RateLimitConfigs.STRIPE_VISIONARY_REJOIN),
+		LoginRequired,
+		DefaultUserOnly,
+		OpenAPI({
+			operationId: 'rejoin_operator_guild',
+			summary: 'Rejoin operator guild',
+			description: 'Adds the authenticated user back to the operator community guild after premium re-subscription.',
+			responseSchema: null,
+			statusCode: 204,
+			security: ['botToken', 'bearerToken', 'sessionToken'],
+			tags: 'Premium',
+		}),
+		async (ctx) => {
+			const userId = ctx.get('user').id;
+			await ctx.get('stripeService').rejoinOperatorsGuild(userId);
+			return ctx.body(null, 204);
+		},
+	);
+}

packages/api/src/stripe/StripeModel.tsx

@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {UserCacheService} from '@fluxer/api/src/infrastructure/UserCacheService';
+import type {RequestCache} from '@fluxer/api/src/middleware/RequestCacheMiddleware';
+import type {GiftCode} from '@fluxer/api/src/models/GiftCode';
+import {getCachedUserPartialResponse} from '@fluxer/api/src/user/UserCacheHelpers';
+import type {GiftCodeMetadataResponse, GiftCodeResponse} from '@fluxer/schema/src/domains/premium/GiftCodeSchemas';
+
+interface MapGiftCodeToResponseParams {
+	giftCode: GiftCode;
+	userCacheService: UserCacheService;
+	requestCache: RequestCache;
+	includeCreator?: boolean;
+}
+
+interface MapGiftCodeToMetadataResponseParams {
+	giftCode: GiftCode;
+	userCacheService: UserCacheService;
+	requestCache: RequestCache;
+}
+
+export async function mapGiftCodeToResponse({
+	giftCode,
+	userCacheService,
+	requestCache,
+	includeCreator = false,
+}: MapGiftCodeToResponseParams): Promise<GiftCodeResponse> {
+	let createdBy = null;
+	if (includeCreator) {
+		createdBy = await getCachedUserPartialResponse({
+			userId: giftCode.createdByUserId,
+			userCacheService,
+			requestCache,
+		});
+	}
+
+	return {
+		code: giftCode.code,
+		duration_months: giftCode.durationMonths,
+		redeemed: !!giftCode.redeemedAt,
+		created_by: createdBy,
+	};
+}
+
+export async function mapGiftCodeToMetadataResponse({
+	giftCode,
+	userCacheService,
+	requestCache,
+}: MapGiftCodeToMetadataResponseParams): Promise<GiftCodeMetadataResponse> {
+	const [createdBy, redeemedBy] = await Promise.all([
+		getCachedUserPartialResponse({
+			userId: giftCode.createdByUserId,
+			userCacheService,
+			requestCache,
+		}),
+		giftCode.redeemedByUserId
+			? getCachedUserPartialResponse({
+					userId: giftCode.redeemedByUserId,
+					userCacheService,
+					requestCache,
+				})
+			: null,
+	]);
+
+	return {
+		code: giftCode.code,
+		duration_months: giftCode.durationMonths,
+		created_at: giftCode.createdAt.toISOString(),
+		created_by: createdBy,
+		redeemed_at: giftCode.redeemedAt?.toISOString() ?? null,
+		redeemed_by: redeemedBy,
+	};
+}

packages/api/src/stripe/StripeService.tsx

@@ -0,0 +1,170 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {AuthService} from '@fluxer/api/src/auth/AuthService';
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import type {IDonationRepository} from '@fluxer/api/src/donation/IDonationRepository';
+import type {IGuildRepositoryAggregate} from '@fluxer/api/src/guild/repositories/IGuildRepositoryAggregate';
+import type {GuildService} from '@fluxer/api/src/guild/services/GuildService';
+import type {IGatewayService} from '@fluxer/api/src/infrastructure/IGatewayService';
+import type {UserCacheService} from '@fluxer/api/src/infrastructure/UserCacheService';
+import type {GiftCode} from '@fluxer/api/src/models/GiftCode';
+import type {User} from '@fluxer/api/src/models/User';
+import {ProductRegistry} from '@fluxer/api/src/stripe/ProductRegistry';
+import type {CreateCheckoutSessionParams} from '@fluxer/api/src/stripe/services/StripeCheckoutService';
+import {StripeCheckoutService} from '@fluxer/api/src/stripe/services/StripeCheckoutService';
+import {StripeGiftService} from '@fluxer/api/src/stripe/services/StripeGiftService';
+import {StripePremiumService} from '@fluxer/api/src/stripe/services/StripePremiumService';
+import {StripeSubscriptionService} from '@fluxer/api/src/stripe/services/StripeSubscriptionService';
+import type {HandleWebhookParams} from '@fluxer/api/src/stripe/services/StripeWebhookService';
+import {StripeWebhookService} from '@fluxer/api/src/stripe/services/StripeWebhookService';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import type {Currency} from '@fluxer/api/src/utils/CurrencyUtils';
+import type {ICacheService} from '@fluxer/cache/src/ICacheService';
+import type {IEmailService} from '@fluxer/email/src/IEmailService';
+import Stripe from 'stripe';
+
+export class StripeService {
+	private stripe: Stripe | null = null;
+	private productRegistry: ProductRegistry;
+	private checkoutService: StripeCheckoutService;
+	private subscriptionService: StripeSubscriptionService;
+	private giftService: StripeGiftService;
+	private premiumService: StripePremiumService;
+	private webhookService: StripeWebhookService;
+
+	constructor(
+		private userRepository: IUserRepository,
+		private userCacheService: UserCacheService,
+		private authService: AuthService,
+		private gatewayService: IGatewayService,
+		private emailService: IEmailService,
+		private guildRepository: IGuildRepositoryAggregate,
+		private guildService: GuildService,
+		private cacheService: ICacheService,
+		private donationRepository: IDonationRepository,
+	) {
+		this.productRegistry = new ProductRegistry();
+
+		if (Config.stripe.enabled && Config.stripe.secretKey) {
+			this.stripe = new Stripe(Config.stripe.secretKey, {
+				apiVersion: '2026-01-28.clover',
+				httpClient: Config.dev.testModeEnabled ? Stripe.createFetchHttpClient() : undefined,
+			});
+		}
+
+		this.premiumService = new StripePremiumService(
+			this.userRepository,
+			this.gatewayService,
+			this.guildRepository,
+			this.guildService,
+		);
+
+		this.checkoutService = new StripeCheckoutService(this.stripe, this.userRepository, this.productRegistry);
+
+		this.subscriptionService = new StripeSubscriptionService(
+			this.stripe,
+			this.userRepository,
+			this.cacheService,
+			this.gatewayService,
+		);
+
+		this.giftService = new StripeGiftService(
+			this.stripe,
+			this.userRepository,
+			this.cacheService,
+			this.gatewayService,
+			this.checkoutService,
+			this.premiumService,
+			this.subscriptionService,
+		);
+
+		this.webhookService = new StripeWebhookService(
+			this.stripe,
+			this.userRepository,
+			this.userCacheService,
+			this.authService,
+			this.emailService,
+			this.gatewayService,
+			this.productRegistry,
+			this.giftService,
+			this.premiumService,
+			this.donationRepository,
+		);
+	}
+
+	getStripe(): Stripe | null {
+		return this.stripe;
+	}
+
+	async createCheckoutSession(params: CreateCheckoutSessionParams): Promise<string> {
+		return this.checkoutService.createCheckoutSession(params);
+	}
+
+	async createCustomerPortalSession(userId: UserID): Promise<string> {
+		return this.checkoutService.createCustomerPortalSession(userId);
+	}
+
+	getPriceIds(countryCode?: string): {
+		monthly: string | null;
+		yearly: string | null;
+		gift_1_month: string | null;
+		gift_1_year: string | null;
+		currency: Currency;
+	} {
+		return this.checkoutService.getPriceIds(countryCode);
+	}
+
+	async cancelSubscriptionAtPeriodEnd(userId: UserID): Promise<void> {
+		return this.subscriptionService.cancelSubscriptionAtPeriodEnd(userId);
+	}
+
+	async reactivateSubscription(userId: UserID): Promise<void> {
+		return this.subscriptionService.reactivateSubscription(userId);
+	}
+
+	async extendSubscriptionWithGiftTrial(user: User, durationMonths: number, idempotencyKey: string): Promise<void> {
+		return this.subscriptionService.extendSubscriptionWithGiftTrial(user, durationMonths, idempotencyKey);
+	}
+
+	async getGiftCode(code: string): Promise<GiftCode> {
+		return this.giftService.getGiftCode(code);
+	}
+
+	async redeemGiftCode(userId: UserID, code: string): Promise<void> {
+		return this.giftService.redeemGiftCode(userId, code);
+	}
+
+	async getUserGifts(userId: UserID): Promise<Array<GiftCode>> {
+		return this.giftService.getUserGifts(userId);
+	}
+
+	async rejoinVisionariesGuild(userId: UserID): Promise<void> {
+		return this.premiumService.rejoinVisionariesGuild(userId);
+	}
+
+	async rejoinOperatorsGuild(userId: UserID): Promise<void> {
+		return this.premiumService.rejoinOperatorsGuild(userId);
+	}
+
+	async handleWebhook(params: HandleWebhookParams): Promise<void> {
+		return this.webhookService.handleWebhook(params);
+	}
+}

packages/api/src/stripe/StripeSubscriptionPeriod.tsx

@@ -0,0 +1,58 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type Stripe from 'stripe';
+
+export function getPrimarySubscriptionItem(subscription: Stripe.Subscription): Stripe.SubscriptionItem | null {
+	const items = subscription.items?.data ?? [];
+	if (items.length === 0) {
+		return null;
+	}
+
+	const recurringItem = items.find((item) => Boolean(item.price?.recurring));
+	return recurringItem ?? items[0];
+}
+
+export function getSubscriptionItemPeriodEndUnix(item: Stripe.SubscriptionItem | null): number | null {
+	return item?.current_period_end ?? null;
+}
+
+export function getSubscriptionItemPeriodEnd(item: Stripe.SubscriptionItem | null): Date | null {
+	const periodEnd = getSubscriptionItemPeriodEndUnix(item);
+	return periodEnd == null ? null : new Date(periodEnd * 1000);
+}
+
+export function getSubscriptionCurrentPeriodEnd(subscription: Stripe.Subscription): Date | null {
+	const items = subscription.items?.data ?? [];
+	if (items.length === 0) {
+		return null;
+	}
+
+	let latestPeriodEnd: number | null = null;
+	for (const item of items) {
+		if (item.current_period_end == null) {
+			continue;
+		}
+		if (latestPeriodEnd == null || item.current_period_end > latestPeriodEnd) {
+			latestPeriodEnd = item.current_period_end;
+		}
+	}
+
+	return latestPeriodEnd == null ? null : new Date(latestPeriodEnd * 1000);
+}

packages/api/src/stripe/StripeUtils.tsx

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export function extractId(value: string | {id: string} | null | undefined): string | null {
+	if (!value) return null;
+	if (typeof value === 'string') return value || null;
+	return value.id || null;
+}
+
+export function addMonthsClamp(date: Date, months: number): Date {
+	const d = new Date(date);
+	const originalDay = d.getDate();
+	const targetMonth = d.getMonth() + months;
+	d.setMonth(targetMonth);
+
+	if (d.getDate() < originalDay) {
+		d.setDate(0);
+	}
+	return d;
+}

packages/api/src/stripe/VisionarySlotInitializer.tsx

@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {Config} from '@fluxer/api/src/Config';
+import {Logger} from '@fluxer/api/src/Logger';
+import {VisionarySlotRepository} from '@fluxer/api/src/user/repositories/VisionarySlotRepository';
+
+const DEFAULT_SLOT_COUNT = 100;
+
+export class VisionarySlotInitializer {
+	async initialize(): Promise<void> {
+		if (!Config.dev.testModeEnabled || !Config.stripe.enabled) {
+			return;
+		}
+
+		try {
+			const repository = new VisionarySlotRepository();
+			const existingSlots = await repository.listVisionarySlots();
+
+			if (existingSlots.length === 0) {
+				Logger.info(`[VisionarySlotInitializer] Creating ${DEFAULT_SLOT_COUNT} test visionary slots...`);
+				await repository.expandVisionarySlots(DEFAULT_SLOT_COUNT);
+				Logger.info(`[VisionarySlotInitializer] Successfully created ${DEFAULT_SLOT_COUNT} visionary slots`);
+			} else {
+				Logger.info(`[VisionarySlotInitializer] Found ${existingSlots.length} existing slots, skipping initialization`);
+			}
+		} catch (error) {
+			Logger.error({error}, '[VisionarySlotInitializer] Failed to create visionary slots');
+			throw error;
+		}
+	}
+}

packages/api/src/stripe/services/StripeCheckoutService.tsx

@@ -0,0 +1,262 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {Logger} from '@fluxer/api/src/Logger';
+import type {User} from '@fluxer/api/src/models/User';
+import type {ProductRegistry} from '@fluxer/api/src/stripe/ProductRegistry';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import {type Currency, getCurrency} from '@fluxer/api/src/utils/CurrencyUtils';
+import {UserFlags, UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {PremiumPurchaseBlockedError} from '@fluxer/errors/src/domains/payment/PremiumPurchaseBlockedError';
+import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
+import {StripeInvalidProductConfigurationError} from '@fluxer/errors/src/domains/payment/StripeInvalidProductConfigurationError';
+import {StripeInvalidProductError} from '@fluxer/errors/src/domains/payment/StripeInvalidProductError';
+import {StripeNoPurchaseHistoryError} from '@fluxer/errors/src/domains/payment/StripeNoPurchaseHistoryError';
+import {StripePaymentNotAvailableError} from '@fluxer/errors/src/domains/payment/StripePaymentNotAvailableError';
+import {UnclaimedAccountCannotMakePurchasesError} from '@fluxer/errors/src/domains/user/UnclaimedAccountCannotMakePurchasesError';
+import {UnknownUserError} from '@fluxer/errors/src/domains/user/UnknownUserError';
+import type Stripe from 'stripe';
+
+const FIRST_REFUND_BLOCK_DAYS = 30;
+
+export interface CreateCheckoutSessionParams {
+	userId: UserID;
+	priceId: string;
+	isGift?: boolean;
+}
+
+export class StripeCheckoutService {
+	constructor(
+		private stripe: Stripe | null,
+		private userRepository: IUserRepository,
+		private productRegistry: ProductRegistry,
+	) {}
+
+	async createCheckoutSession({userId, priceId, isGift = false}: CreateCheckoutSessionParams): Promise<string> {
+		if (!this.stripe) {
+			throw new StripePaymentNotAvailableError();
+		}
+
+		const productInfo = this.productRegistry.getProduct(priceId);
+		if (!productInfo) {
+			Logger.error({priceId, userId}, 'Invalid or unknown price ID');
+			throw new StripeInvalidProductError();
+		}
+
+		if (productInfo.isGift !== isGift) {
+			Logger.error(
+				{priceId, userId, expectedIsGift: productInfo.isGift, providedIsGift: isGift},
+				'Gift parameter mismatch',
+			);
+			throw new StripeInvalidProductConfigurationError();
+		}
+
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new UnknownUserError();
+		}
+
+		if (
+			user.premiumType === UserPremiumTypes.LIFETIME &&
+			this.productRegistry.isRecurringSubscription(productInfo) &&
+			!productInfo.isGift
+		) {
+			throw new PremiumPurchaseBlockedError();
+		}
+
+		this.validateUserCanPurchase(user);
+
+		const customerId = await this.ensureStripeCustomer(user);
+
+		const checkoutMode: Stripe.Checkout.SessionCreateParams.Mode = this.productRegistry.isRecurringSubscription(
+			productInfo,
+		)
+			? 'subscription'
+			: 'payment';
+
+		const checkoutParams: Stripe.Checkout.SessionCreateParams = {
+			customer: customerId,
+			line_items: [
+				{
+					price: priceId,
+					quantity: 1,
+				},
+			],
+			mode: checkoutMode,
+			success_url: `${Config.endpoints.webApp}/premium-callback?status=success`,
+			cancel_url: `${Config.endpoints.webApp}/premium-callback?status=cancel`,
+			...(checkoutMode === 'payment'
+				? {
+						invoice_creation: {
+							enabled: true,
+						},
+					}
+				: {}),
+			automatic_tax: {
+				enabled: true,
+			},
+			customer_update: {
+				address: 'auto',
+			},
+			allow_promotion_codes: true,
+		};
+
+		try {
+			const session = await this.stripe.checkout.sessions.create(checkoutParams);
+			if (!session.url) {
+				Logger.error({userId, sessionId: session.id}, 'Stripe checkout session missing url');
+				throw new StripeError('Stripe checkout session missing url');
+			}
+
+			await this.userRepository.createPayment({
+				checkout_session_id: session.id,
+				user_id: userId,
+				price_id: priceId,
+				product_type: productInfo.type,
+				status: 'pending',
+				is_gift: isGift,
+				created_at: new Date(),
+			});
+
+			Logger.debug({userId, sessionId: session.id, productType: productInfo.type}, 'Checkout session created');
+
+			return session.url;
+		} catch (error: unknown) {
+			Logger.error({error, userId}, 'Failed to create Stripe checkout session');
+			const message = error instanceof Error ? error.message : 'Failed to create checkout session';
+			throw new StripeError(message);
+		}
+	}
+
+	async createCustomerPortalSession(userId: UserID): Promise<string> {
+		if (!this.stripe) {
+			throw new StripePaymentNotAvailableError();
+		}
+
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new UnknownUserError();
+		}
+
+		if (!user.stripeCustomerId) {
+			throw new StripeNoPurchaseHistoryError();
+		}
+
+		try {
+			const session = await this.stripe.billingPortal.sessions.create({
+				customer: user.stripeCustomerId,
+				return_url: `${Config.endpoints.webApp}/premium-callback?status=closed-billing-portal`,
+			});
+
+			if (!session.url) {
+				Logger.error({userId, customerId: user.stripeCustomerId}, 'Stripe customer portal session missing url');
+				throw new StripeError('Stripe customer portal session missing url');
+			}
+
+			return session.url;
+		} catch (error: unknown) {
+			Logger.error({error, userId, customerId: user.stripeCustomerId}, 'Failed to create customer portal session');
+			const message = error instanceof Error ? error.message : 'Failed to create customer portal session';
+			throw new StripeError(message);
+		}
+	}
+
+	getPriceIds(countryCode?: string): {
+		monthly: string | null;
+		yearly: string | null;
+		gift_1_month: string | null;
+		gift_1_year: string | null;
+		currency: Currency;
+	} {
+		const currency = getCurrency(countryCode);
+		const prices = Config.stripe.prices;
+
+		if (currency === 'EUR') {
+			if (!prices?.monthlyEur || !prices.yearlyEur || !prices.gift1MonthEur || !prices.gift1YearEur) {
+				throw new StripeError('Stripe price ids missing for EUR');
+			}
+			return {
+				monthly: prices.monthlyEur,
+				yearly: prices.yearlyEur,
+				gift_1_month: prices.gift1MonthEur,
+				gift_1_year: prices.gift1YearEur,
+				currency,
+			};
+		}
+
+		if (!prices?.monthlyUsd || !prices.yearlyUsd || !prices.gift1MonthUsd || !prices.gift1YearUsd) {
+			throw new StripeError('Stripe price ids missing for USD');
+		}
+		return {
+			monthly: prices.monthlyUsd,
+			yearly: prices.yearlyUsd,
+			gift_1_month: prices.gift1MonthUsd,
+			gift_1_year: prices.gift1YearUsd,
+			currency,
+		};
+	}
+
+	validateUserCanPurchase(user: User): void {
+		if (user.isUnclaimedAccount()) {
+			throw new UnclaimedAccountCannotMakePurchasesError();
+		}
+
+		if (user.flags & UserFlags.PREMIUM_PURCHASE_DISABLED) {
+			throw new PremiumPurchaseBlockedError();
+		}
+
+		if (user.firstRefundAt) {
+			const daysSinceFirstRefund = Math.floor((Date.now() - user.firstRefundAt.getTime()) / (1000 * 60 * 60 * 24));
+			if (daysSinceFirstRefund < FIRST_REFUND_BLOCK_DAYS) {
+				throw new PremiumPurchaseBlockedError();
+			}
+		}
+	}
+
+	private async ensureStripeCustomer(user: User): Promise<string> {
+		if (user.stripeCustomerId) {
+			return user.stripeCustomerId;
+		}
+
+		if (!this.stripe) {
+			throw new StripePaymentNotAvailableError();
+		}
+
+		const customer = await this.stripe.customers.create({
+			email: user.email ?? undefined,
+			metadata: {
+				userId: user.id.toString(),
+			},
+		});
+
+		await this.userRepository.patchUpsert(
+			user.id,
+			{
+				stripe_customer_id: customer.id,
+			},
+			user.toRow(),
+		);
+
+		Logger.debug({userId: user.id, customerId: customer.id}, 'Stripe customer created');
+
+		return customer.id;
+	}
+}

packages/api/src/stripe/services/StripeGiftService.tsx

@@ -0,0 +1,252 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import type {IGatewayService} from '@fluxer/api/src/infrastructure/IGatewayService';
+import {Logger} from '@fluxer/api/src/Logger';
+import type {GiftCode} from '@fluxer/api/src/models/GiftCode';
+import type {User} from '@fluxer/api/src/models/User';
+import type {ProductInfo} from '@fluxer/api/src/stripe/ProductRegistry';
+import type {StripeCheckoutService} from '@fluxer/api/src/stripe/services/StripeCheckoutService';
+import type {StripePremiumService} from '@fluxer/api/src/stripe/services/StripePremiumService';
+import type {StripeSubscriptionService} from '@fluxer/api/src/stripe/services/StripeSubscriptionService';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import {mapUserToPrivateResponse} from '@fluxer/api/src/user/UserMappers';
+import * as RandomUtils from '@fluxer/api/src/utils/RandomUtils';
+import type {ICacheService} from '@fluxer/cache/src/ICacheService';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {CannotRedeemPlutoniumWithVisionaryError} from '@fluxer/errors/src/domains/payment/CannotRedeemPlutoniumWithVisionaryError';
+import {GiftCodeAlreadyRedeemedError} from '@fluxer/errors/src/domains/payment/GiftCodeAlreadyRedeemedError';
+import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
+import {StripeGiftRedemptionInProgressError} from '@fluxer/errors/src/domains/payment/StripeGiftRedemptionInProgressError';
+import {UnknownGiftCodeError} from '@fluxer/errors/src/domains/payment/UnknownGiftCodeError';
+import {UnknownUserError} from '@fluxer/errors/src/domains/user/UnknownUserError';
+import {seconds} from 'itty-time';
+import type Stripe from 'stripe';
+
+export class StripeGiftService {
+	constructor(
+		private stripe: Stripe | null,
+		private userRepository: IUserRepository,
+		private cacheService: ICacheService,
+		private gatewayService: IGatewayService,
+		private checkoutService: StripeCheckoutService,
+		private premiumService: StripePremiumService,
+		private subscriptionService: StripeSubscriptionService,
+	) {}
+
+	async getGiftCode(code: string): Promise<GiftCode> {
+		const giftCode = await this.userRepository.findGiftCode(code);
+		if (!giftCode) {
+			throw new UnknownGiftCodeError();
+		}
+		return giftCode;
+	}
+
+	async redeemGiftCode(userId: UserID, code: string): Promise<void> {
+		const inflightKey = `gift_redeem_inflight:${code}`;
+		const appliedKey = `gift_redeem_applied:${code}`;
+
+		if (await this.cacheService.get<boolean>(appliedKey)) {
+			throw new GiftCodeAlreadyRedeemedError();
+		}
+		if (await this.cacheService.get<boolean>(inflightKey)) {
+			throw new StripeGiftRedemptionInProgressError();
+		}
+		await this.cacheService.set(inflightKey, seconds('1 minute'));
+
+		try {
+			const giftCode = await this.userRepository.findGiftCode(code);
+			if (!giftCode) {
+				throw new UnknownGiftCodeError();
+			}
+
+			if (giftCode.redeemedByUserId) {
+				await this.cacheService.set(appliedKey, seconds('365 days'));
+				throw new GiftCodeAlreadyRedeemedError();
+			}
+
+			if (await this.cacheService.get<boolean>(`redeemed_gift_codes:${code}`)) {
+				await this.cacheService.set(appliedKey, seconds('365 days'));
+				throw new GiftCodeAlreadyRedeemedError();
+			}
+
+			const user = await this.userRepository.findUnique(userId);
+			if (!user) {
+				throw new UnknownUserError();
+			}
+
+			this.checkoutService.validateUserCanPurchase(user);
+
+			if (user.premiumType === UserPremiumTypes.LIFETIME) {
+				throw new CannotRedeemPlutoniumWithVisionaryError();
+			}
+
+			const redeemResult = await this.userRepository.redeemGiftCode(code, userId);
+			if (!redeemResult.applied) {
+				throw new GiftCodeAlreadyRedeemedError();
+			}
+
+			const premiumType = giftCode.durationMonths === 0 ? UserPremiumTypes.LIFETIME : UserPremiumTypes.SUBSCRIPTION;
+			if (premiumType === UserPremiumTypes.LIFETIME && user.stripeSubscriptionId && this.stripe) {
+				await this.cancelStripeSubscriptionImmediately(user);
+			}
+
+			if (premiumType === UserPremiumTypes.SUBSCRIPTION && user.stripeSubscriptionId && this.stripe) {
+				await this.subscriptionService.extendSubscriptionWithGiftTrial(user, giftCode.durationMonths, code);
+			} else if (premiumType === UserPremiumTypes.LIFETIME && giftCode.visionarySequenceNumber != null) {
+				const GIFT_CODE_SENTINEL_USER_ID = createUserID(-1n);
+				await this.userRepository.unreserveVisionarySlot(giftCode.visionarySequenceNumber, GIFT_CODE_SENTINEL_USER_ID);
+				await this.premiumService.grantPremiumFromGift(
+					userId,
+					premiumType,
+					giftCode.durationMonths,
+					giftCode.visionarySequenceNumber,
+				);
+				await this.userRepository.reserveVisionarySlot(giftCode.visionarySequenceNumber, userId);
+			} else {
+				await this.premiumService.grantPremium(userId, premiumType, giftCode.durationMonths, null, false);
+			}
+
+			await this.cacheService.set(`redeemed_gift_codes:${code}`, seconds('5 minutes'));
+			await this.cacheService.set(appliedKey, seconds('365 days'));
+
+			Logger.debug({userId, giftCode: code, durationMonths: giftCode.durationMonths}, 'Gift code redeemed');
+		} finally {
+			await this.cacheService.delete(inflightKey);
+		}
+	}
+
+	async getUserGifts(userId: UserID): Promise<Array<GiftCode>> {
+		const gifts = await this.userRepository.findGiftCodesByCreator(userId);
+		return gifts.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+	}
+
+	async prepareGiftCode(
+		checkoutSessionId: string,
+		purchaser: User,
+		productInfo: ProductInfo,
+		paymentIntentId: string | null,
+	): Promise<string> {
+		const payment = await this.userRepository.getPaymentByCheckoutSession(checkoutSessionId);
+		if (!payment) {
+			Logger.error({checkoutSessionId}, 'Payment not found for gift code creation');
+			throw new StripeError('Payment not found for gift code creation');
+		}
+
+		if (payment.giftCode) {
+			Logger.debug({checkoutSessionId, code: payment.giftCode}, 'Gift code already exists for checkout session');
+			return payment.giftCode;
+		}
+		if (paymentIntentId) {
+			const existingGift = await this.userRepository.findGiftCodeByPaymentIntent(paymentIntentId);
+			if (existingGift) {
+				await this.userRepository.linkGiftCodeToCheckoutSession(existingGift.code, checkoutSessionId);
+				Logger.warn(
+					{checkoutSessionId, paymentIntentId, code: existingGift.code},
+					'Reused existing gift code for checkout session',
+				);
+				return existingGift.code;
+			}
+		}
+
+		const code = await this.generateUniqueGiftCode();
+
+		await this.userRepository.createGiftCode({
+			code,
+			duration_months: productInfo.durationMonths,
+			created_at: new Date(),
+			created_by_user_id: purchaser.id,
+			redeemed_at: null,
+			redeemed_by_user_id: null,
+			stripe_payment_intent_id: paymentIntentId,
+			visionary_sequence_number: null,
+			checkout_session_id: checkoutSessionId,
+			version: 1,
+		});
+
+		await this.userRepository.linkGiftCodeToCheckoutSession(code, checkoutSessionId);
+
+		Logger.debug(
+			{code, purchaserId: purchaser.id, durationMonths: productInfo.durationMonths, productType: productInfo.type},
+			'Gift code prepared',
+		);
+
+		return code;
+	}
+
+	async finaliseGiftCode(purchaserId: UserID): Promise<void> {
+		const currentUser = await this.userRepository.findUnique(purchaserId);
+		if (!currentUser) {
+			Logger.error({userId: purchaserId}, 'Purchaser not found for gift finalisation');
+			return;
+		}
+		const updatedUser = await this.userRepository.patchUpsert(
+			purchaserId,
+			{
+				gift_inventory_server_seq: (currentUser.giftInventoryServerSeq ?? 0) + 1,
+			},
+			currentUser.toRow(),
+		);
+		await this.dispatchUser(updatedUser);
+	}
+
+	private async generateUniqueGiftCode(): Promise<string> {
+		let code: string;
+		let exists = true;
+
+		while (exists) {
+			code = RandomUtils.randomString(32);
+			const existing = await this.userRepository.findGiftCode(code);
+			exists = !!existing;
+		}
+
+		return code!;
+	}
+
+	private async cancelStripeSubscriptionImmediately(user: User): Promise<void> {
+		if (!this.stripe) {
+			throw new StripeError('Stripe client not available for immediate cancellation');
+		}
+		if (!user.stripeSubscriptionId) {
+			throw new StripeError('User missing subscription id for immediate cancellation');
+		}
+		await this.stripe.subscriptions.cancel(user.stripeSubscriptionId, {invoice_now: false, prorate: false});
+		const updatedUser = await this.userRepository.patchUpsert(
+			user.id,
+			{
+				stripe_subscription_id: null,
+				premium_billing_cycle: null,
+				premium_will_cancel: false,
+			},
+			user.toRow(),
+		);
+		await this.dispatchUser(updatedUser);
+		Logger.debug({userId: user.id}, 'Canceled active subscription due to lifetime grant');
+	}
+
+	private async dispatchUser(user: User): Promise<void> {
+		await this.gatewayService.dispatchPresence({
+			userId: user.id,
+			event: 'USER_UPDATE',
+			data: mapUserToPrivateResponse(user),
+		});
+	}
+}

packages/api/src/stripe/services/StripePremiumService.tsx

@@ -0,0 +1,248 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import {createGuildID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import type {IGuildRepositoryAggregate} from '@fluxer/api/src/guild/repositories/IGuildRepositoryAggregate';
+import type {GuildService} from '@fluxer/api/src/guild/services/GuildService';
+import type {IGatewayService} from '@fluxer/api/src/infrastructure/IGatewayService';
+import {Logger} from '@fluxer/api/src/Logger';
+import {createRequestCache} from '@fluxer/api/src/middleware/RequestCacheMiddleware';
+import type {User} from '@fluxer/api/src/models/User';
+import {addMonthsClamp} from '@fluxer/api/src/stripe/StripeUtils';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import {mapUserToPrivateResponse} from '@fluxer/api/src/user/UserMappers';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {MissingAccessError} from '@fluxer/errors/src/domains/core/MissingAccessError';
+import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
+
+export class StripePremiumService {
+	constructor(
+		private userRepository: IUserRepository,
+		private gatewayService: IGatewayService,
+		private guildRepository: IGuildRepositoryAggregate,
+		private guildService: GuildService,
+	) {}
+
+	async grantPremium(
+		userId: UserID,
+		premiumType: 1 | 2,
+		durationMonths: number,
+		billingCycle: string | null = null,
+		hasEverPurchased: boolean = false,
+	): Promise<void> {
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new StripeError('User not found for premium grant');
+		}
+
+		const now = new Date();
+		let premiumUntil: Date | null = null;
+		let visionarySequence: number | null = user.premiumLifetimeSequence;
+
+		if (durationMonths > 0) {
+			const currentPremiumUntil = user.premiumUntil && user.premiumUntil > now ? user.premiumUntil : now;
+			premiumUntil = addMonthsClamp(currentPremiumUntil, durationMonths);
+		}
+
+		if (premiumType === UserPremiumTypes.LIFETIME && !visionarySequence) {
+			const allSlots = await this.userRepository.listVisionarySlots();
+
+			const myReservedSlot = allSlots
+				.slice()
+				.sort((a, b) => a.slotIndex - b.slotIndex)
+				.find((slot) => slot.userId === userId);
+
+			if (myReservedSlot) {
+				visionarySequence = myReservedSlot.slotIndex;
+			} else {
+				const unreservedSlot = allSlots
+					.slice()
+					.sort((a, b) => a.slotIndex - b.slotIndex)
+					.find((slot) => !slot.isReserved());
+
+				if (!unreservedSlot) {
+					const maxSlotIndex = allSlots.length > 0 ? Math.max(...allSlots.map((s) => s.slotIndex)) : -1;
+					const newSlotIndex = maxSlotIndex + 1;
+
+					await this.userRepository.expandVisionarySlots(1);
+					visionarySequence = newSlotIndex;
+					await this.userRepository.reserveVisionarySlot(newSlotIndex, userId);
+
+					Logger.warn(
+						{userId, newSlotIndex, totalSlots: allSlots.length + 1},
+						'Auto-expanded visionary slots due to payment completion',
+					);
+				} else {
+					visionarySequence = unreservedSlot.slotIndex;
+					await this.userRepository.reserveVisionarySlot(unreservedSlot.slotIndex, userId);
+				}
+			}
+
+			await this.addToVisionariesGuild(userId);
+		}
+
+		const freshUser = await this.userRepository.findUnique(userId);
+		if (!freshUser) {
+			throw new StripeError('User not found after premium grant update');
+		}
+
+		const updatedUser = await this.userRepository.patchUpsert(
+			userId,
+			{
+				premium_type: premiumType,
+				premium_since: freshUser.premiumSince || now,
+				premium_until: premiumUntil,
+				premium_lifetime_sequence: visionarySequence,
+				has_ever_purchased: hasEverPurchased,
+				premium_will_cancel: false,
+				premium_billing_cycle: billingCycle,
+			},
+			freshUser.toRow(),
+		);
+
+		await this.dispatchUser(updatedUser);
+
+		Logger.debug({userId, premiumType, durationMonths, visionarySequence, billingCycle}, 'Premium granted to user');
+	}
+
+	async grantPremiumFromGift(
+		userId: UserID,
+		premiumType: 1 | 2,
+		durationMonths: number,
+		visionarySequenceNumber: number,
+	): Promise<void> {
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new StripeError('User not found for gift premium grant');
+		}
+
+		const now = new Date();
+		let premiumUntil: Date | null = null;
+
+		if (durationMonths > 0) {
+			const currentPremiumUntil = user.premiumUntil && user.premiumUntil > now ? user.premiumUntil : now;
+			premiumUntil = addMonthsClamp(currentPremiumUntil, durationMonths);
+		}
+
+		if (premiumType === UserPremiumTypes.LIFETIME) {
+			await this.addToVisionariesGuild(userId);
+		}
+
+		const updatedUser = await this.userRepository.patchUpsert(
+			userId,
+			{
+				premium_type: premiumType,
+				premium_since: user.premiumSince || now,
+				premium_until: premiumUntil,
+				premium_lifetime_sequence:
+					premiumType === UserPremiumTypes.LIFETIME ? visionarySequenceNumber : user.premiumLifetimeSequence,
+				premium_will_cancel: false,
+			},
+			user.toRow(),
+		);
+
+		await this.dispatchUser(updatedUser);
+
+		Logger.debug(
+			{userId, premiumType, durationMonths, lifetimeSequence: visionarySequenceNumber},
+			'Premium granted to user from gift',
+		);
+	}
+
+	async revokePremium(userId: UserID): Promise<void> {
+		const user = await this.userRepository.findUniqueAssert(userId);
+		const updatedUser = await this.userRepository.patchUpsert(
+			userId,
+			{
+				premium_type: UserPremiumTypes.NONE,
+				premium_until: null,
+			},
+			user.toRow(),
+		);
+
+		await this.dispatchUser(updatedUser);
+	}
+
+	async rejoinVisionariesGuild(userId: UserID): Promise<void> {
+		await this.assertHasVisionaryCommunityAccess(userId);
+		await this.addToVisionariesGuild(userId);
+	}
+
+	async rejoinOperatorsGuild(userId: UserID): Promise<void> {
+		await this.assertHasVisionaryCommunityAccess(userId);
+		await this.addToOperatorsGuild(userId);
+	}
+
+	private async assertHasVisionaryCommunityAccess(userId: UserID): Promise<void> {
+		const user = await this.userRepository.findUniqueAssert(userId);
+		if (user.premiumType !== UserPremiumTypes.LIFETIME) {
+			throw new MissingAccessError();
+		}
+	}
+
+	private async addToVisionariesGuild(userId: UserID): Promise<void> {
+		if (!Config.instance.visionariesGuildId) {
+			throw new StripeError('Visionaries guild id not configured');
+		}
+
+		const visionariesGuildId = createGuildID(BigInt(Config.instance.visionariesGuildId));
+		const existingMember = await this.guildRepository.getMember(visionariesGuildId, userId);
+
+		if (!existingMember) {
+			await this.guildService.addUserToGuild({
+				userId,
+				guildId: visionariesGuildId,
+				sendJoinMessage: true,
+				skipBanCheck: true,
+				requestCache: createRequestCache(),
+			});
+			Logger.debug({userId, guildId: visionariesGuildId}, 'Added visionary user to visionaries guild');
+		}
+	}
+
+	private async addToOperatorsGuild(userId: UserID): Promise<void> {
+		if (!Config.instance.operatorsGuildId) {
+			throw new StripeError('Operators guild id not configured');
+		}
+
+		const operatorsGuildId = createGuildID(BigInt(Config.instance.operatorsGuildId));
+		const existingMember = await this.guildRepository.getMember(operatorsGuildId, userId);
+
+		if (!existingMember) {
+			await this.guildService.addUserToGuild({
+				userId,
+				guildId: operatorsGuildId,
+				sendJoinMessage: true,
+				skipBanCheck: true,
+				requestCache: createRequestCache(),
+			});
+			Logger.debug({userId, guildId: operatorsGuildId}, 'Added operator user to operators guild');
+		}
+	}
+
+	private async dispatchUser(user: User): Promise<void> {
+		await this.gatewayService.dispatchPresence({
+			userId: user.id,
+			event: 'USER_UPDATE',
+			data: mapUserToPrivateResponse(user),
+		});
+	}
+}

packages/api/src/stripe/services/StripeSubscriptionService.tsx

@@ -0,0 +1,207 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import type {IGatewayService} from '@fluxer/api/src/infrastructure/IGatewayService';
+import {Logger} from '@fluxer/api/src/Logger';
+import type {User} from '@fluxer/api/src/models/User';
+import {
+	getPrimarySubscriptionItem,
+	getSubscriptionItemPeriodEndUnix,
+} from '@fluxer/api/src/stripe/StripeSubscriptionPeriod';
+import {addMonthsClamp} from '@fluxer/api/src/stripe/StripeUtils';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import {mapUserToPrivateResponse} from '@fluxer/api/src/user/UserMappers';
+import type {ICacheService} from '@fluxer/cache/src/ICacheService';
+import {NoActiveSubscriptionError} from '@fluxer/errors/src/domains/payment/NoActiveSubscriptionError';
+import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
+import {StripeNoActiveSubscriptionError} from '@fluxer/errors/src/domains/payment/StripeNoActiveSubscriptionError';
+import {StripeNoSubscriptionError} from '@fluxer/errors/src/domains/payment/StripeNoSubscriptionError';
+import {StripePaymentNotAvailableError} from '@fluxer/errors/src/domains/payment/StripePaymentNotAvailableError';
+import {StripeSubscriptionAlreadyCancelingError} from '@fluxer/errors/src/domains/payment/StripeSubscriptionAlreadyCancelingError';
+import {StripeSubscriptionNotCancelingError} from '@fluxer/errors/src/domains/payment/StripeSubscriptionNotCancelingError';
+import {UnknownUserError} from '@fluxer/errors/src/domains/user/UnknownUserError';
+import {seconds} from 'itty-time';
+import type Stripe from 'stripe';
+
+export class StripeSubscriptionService {
+	constructor(
+		private stripe: Stripe | null,
+		private userRepository: IUserRepository,
+		private cacheService: ICacheService,
+		private gatewayService: IGatewayService,
+	) {}
+
+	async cancelSubscriptionAtPeriodEnd(userId: UserID): Promise<void> {
+		if (!this.stripe) {
+			throw new StripePaymentNotAvailableError();
+		}
+
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new UnknownUserError();
+		}
+
+		if (!user.stripeSubscriptionId) {
+			throw new StripeNoActiveSubscriptionError();
+		}
+
+		if (user.premiumWillCancel) {
+			throw new StripeSubscriptionAlreadyCancelingError();
+		}
+
+		try {
+			await this.stripe.subscriptions.update(user.stripeSubscriptionId, {
+				cancel_at_period_end: true,
+			});
+
+			const updatedUser = await this.userRepository.patchUpsert(
+				userId,
+				{
+					premium_will_cancel: true,
+				},
+				user.toRow(),
+			);
+
+			await this.dispatchUser(updatedUser);
+
+			Logger.debug({userId, subscriptionId: user.stripeSubscriptionId}, 'Subscription set to cancel at period end');
+		} catch (error: unknown) {
+			Logger.error(
+				{error, userId, subscriptionId: user.stripeSubscriptionId},
+				'Failed to cancel subscription at period end',
+			);
+			const message = error instanceof Error ? error.message : 'Failed to cancel subscription';
+			throw new StripeError(message);
+		}
+	}
+
+	async reactivateSubscription(userId: UserID): Promise<void> {
+		if (!this.stripe) {
+			throw new StripePaymentNotAvailableError();
+		}
+
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new UnknownUserError();
+		}
+
+		if (!user.stripeSubscriptionId) {
+			throw new StripeNoSubscriptionError();
+		}
+
+		if (!user.premiumWillCancel) {
+			throw new StripeSubscriptionNotCancelingError();
+		}
+
+		try {
+			await this.stripe.subscriptions.update(user.stripeSubscriptionId, {
+				cancel_at_period_end: false,
+			});
+
+			const updatedUser = await this.userRepository.patchUpsert(
+				userId,
+				{
+					premium_will_cancel: false,
+				},
+				user.toRow(),
+			);
+
+			await this.dispatchUser(updatedUser);
+
+			Logger.debug({userId, subscriptionId: user.stripeSubscriptionId}, 'Subscription reactivated');
+		} catch (error: unknown) {
+			Logger.error({error, userId, subscriptionId: user.stripeSubscriptionId}, 'Failed to reactivate subscription');
+			const message = error instanceof Error ? error.message : 'Failed to reactivate subscription';
+			throw new StripeError(message);
+		}
+	}
+
+	async extendSubscriptionWithGiftTrial(user: User, durationMonths: number, idempotencyKey: string): Promise<void> {
+		if (!this.stripe || !user.stripeSubscriptionId) {
+			throw new NoActiveSubscriptionError();
+		}
+
+		const appliedKey = `gift_trial_applied:${user.id}:${idempotencyKey}`;
+		const inflightKey = `gift_trial_inflight:${user.id}:${idempotencyKey}`;
+
+		if (await this.cacheService.get<boolean>(appliedKey)) {
+			Logger.debug({userId: user.id, idempotencyKey}, 'Gift trial extension already applied (idempotent hit)');
+			return;
+		}
+		if (await this.cacheService.get<boolean>(inflightKey)) {
+			Logger.debug({userId: user.id, idempotencyKey}, 'Gift trial extension in-flight; skipping duplicate');
+			return;
+		}
+		await this.cacheService.set(inflightKey, seconds('1 minute'));
+
+		try {
+			const subscription = await this.stripe.subscriptions.retrieve(user.stripeSubscriptionId);
+
+			const currentTrialEnd = subscription.trial_end;
+			const item = getPrimarySubscriptionItem(subscription);
+			const currentPeriodEnd = getSubscriptionItemPeriodEndUnix(item);
+			const baseUnix = currentTrialEnd ?? currentPeriodEnd;
+
+			if (!baseUnix) {
+				throw new StripeError('Subscription has no trial_end or current_period_end');
+			}
+
+			const baseDate = new Date(baseUnix * 1000);
+			const newTrialEnd = addMonthsClamp(baseDate, durationMonths);
+			const newTrialEndUnix = Math.floor(newTrialEnd.getTime() / 1000);
+
+			await this.stripe.subscriptions.update(user.stripeSubscriptionId, {
+				trial_end: newTrialEndUnix,
+				proration_behavior: 'none',
+			});
+
+			await this.cacheService.set(appliedKey, seconds('365 days'));
+
+			Logger.debug(
+				{
+					userId: user.id,
+					subscriptionId: user.stripeSubscriptionId,
+					baseDate,
+					newTrialEnd,
+					durationMonths,
+					idempotencyKey,
+				},
+				'Extended subscription with gift trial period',
+			);
+		} catch (error: unknown) {
+			Logger.error(
+				{error, userId: user.id, subscriptionId: user.stripeSubscriptionId, idempotencyKey},
+				'Failed to extend subscription with gift trial',
+			);
+			const message = error instanceof Error ? error.message : 'Failed to extend subscription with gift';
+			throw new StripeError(message);
+		} finally {
+			await this.cacheService.delete(inflightKey);
+		}
+	}
+
+	private async dispatchUser(user: User): Promise<void> {
+		await this.gatewayService.dispatchPresence({
+			userId: user.id,
+			event: 'USER_UPDATE',
+			data: mapUserToPrivateResponse(user),
+		});
+	}
+}

packages/api/src/stripe/services/StripeWebhookService.tsx

@@ -0,0 +1,895 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {AuthService} from '@fluxer/api/src/auth/AuthService';
+import type {UserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {nextVersion} from '@fluxer/api/src/database/Cassandra';
+import type {UserRow} from '@fluxer/api/src/database/types/UserTypes';
+import type {IDonationRepository} from '@fluxer/api/src/donation/IDonationRepository';
+import {Donor} from '@fluxer/api/src/donation/models/Donor';
+import type {IGatewayService} from '@fluxer/api/src/infrastructure/IGatewayService';
+import type {UserCacheService} from '@fluxer/api/src/infrastructure/UserCacheService';
+import {Logger} from '@fluxer/api/src/Logger';
+import type {GiftCode} from '@fluxer/api/src/models/GiftCode';
+import type {User} from '@fluxer/api/src/models/User';
+import type {ProductRegistry} from '@fluxer/api/src/stripe/ProductRegistry';
+import {
+	getPrimarySubscriptionItem,
+	getSubscriptionCurrentPeriodEnd,
+	getSubscriptionItemPeriodEnd,
+} from '@fluxer/api/src/stripe/StripeSubscriptionPeriod';
+import {extractId} from '@fluxer/api/src/stripe/StripeUtils';
+import type {StripeGiftService} from '@fluxer/api/src/stripe/services/StripeGiftService';
+import type {StripePremiumService} from '@fluxer/api/src/stripe/services/StripePremiumService';
+import type {IUserRepository} from '@fluxer/api/src/user/IUserRepository';
+import {mapUserToPrivateResponse} from '@fluxer/api/src/user/UserMappers';
+import {DeletionReasons} from '@fluxer/constants/src/Core';
+import {UserFlags, UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import type {IEmailService} from '@fluxer/email/src/IEmailService';
+import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
+import {StripeWebhookNotAvailableError} from '@fluxer/errors/src/domains/payment/StripeWebhookNotAvailableError';
+import {StripeWebhookSignatureInvalidError} from '@fluxer/errors/src/domains/payment/StripeWebhookSignatureInvalidError';
+import {ms} from 'itty-time';
+import type Stripe from 'stripe';
+
+export interface HandleWebhookParams {
+	body: string;
+	signature: string;
+}
+
+interface DonationCustomerDetails {
+	businessName: string | null;
+	taxId: string | null;
+	taxIdType: string | null;
+}
+
+interface DonationSubscriptionDetails {
+	amountCents: number | null;
+	currency: string | null;
+	interval: string | null;
+	currentPeriodEnd: Date | null;
+	cancelAt: Date | null;
+}
+
+export class StripeWebhookService {
+	constructor(
+		private stripe: Stripe | null,
+		private userRepository: IUserRepository,
+		private userCacheService: UserCacheService,
+		private authService: AuthService,
+		private emailService: IEmailService,
+		private gatewayService: IGatewayService,
+		private productRegistry: ProductRegistry,
+		private giftService: StripeGiftService,
+		private premiumService: StripePremiumService,
+		private donationRepository: IDonationRepository,
+	) {}
+
+	async handleWebhook({body, signature}: HandleWebhookParams): Promise<void> {
+		if (!this.stripe || !Config.stripe.webhookSecret) {
+			throw new StripeWebhookNotAvailableError();
+		}
+
+		let event: Stripe.Event;
+
+		try {
+			event = this.stripe.webhooks.constructEvent(body, signature, Config.stripe.webhookSecret);
+		} catch (error: unknown) {
+			Logger.error({error}, 'Invalid webhook signature');
+			throw new StripeWebhookSignatureInvalidError();
+		}
+
+		Logger.debug({eventType: event.type, eventId: event.id}, 'Processing Stripe webhook');
+
+		try {
+			switch (event.type) {
+				case 'checkout.session.completed':
+					await this.handleCheckoutSessionCompleted(event.data.object as Stripe.Checkout.Session);
+					break;
+
+				case 'invoice.payment_succeeded':
+					await this.handleInvoicePaymentSucceeded(event.data.object as Stripe.Invoice);
+					break;
+
+				case 'customer.subscription.updated':
+					await this.handleSubscriptionUpdated(event.data.object as Stripe.Subscription);
+					break;
+
+				case 'customer.subscription.deleted':
+					await this.handleSubscriptionDeleted(event.data.object as Stripe.Subscription);
+					break;
+
+				case 'charge.dispute.created':
+					await this.handleChargebackCreated(event.data.object as Stripe.Dispute);
+					break;
+
+				case 'charge.dispute.closed':
+					await this.handleChargebackClosed(event.data.object as Stripe.Dispute);
+					break;
+
+				case 'charge.refunded':
+					await this.handleRefund(event.data.object as Stripe.Charge);
+					break;
+
+				default:
+					Logger.debug({eventType: event.type}, 'Unhandled webhook event type');
+			}
+		} catch (error: unknown) {
+			Logger.error({error, eventType: event.type, eventId: event.id}, 'Failed to process webhook event');
+			throw error;
+		}
+	}
+
+	private async handleCheckoutSessionCompleted(session: Stripe.Checkout.Session): Promise<void> {
+		if (session.metadata?.is_donation === 'true') {
+			await this.handleDonationCheckoutCompleted(session);
+			return;
+		}
+
+		const payment = await this.userRepository.getPaymentByCheckoutSession(session.id);
+		if (!payment) {
+			Logger.warn(
+				{
+					sessionId: session.id,
+					paymentLinkId: extractId(session.payment_link),
+					mode: session.mode,
+					submitType: session.submit_type,
+					paymentStatus: session.payment_status,
+				},
+				'No payment record found for checkout session, skipping event',
+			);
+			return;
+		}
+
+		if (payment.status === 'completed' && payment.isGift && !payment.giftCode) {
+			Logger.warn(
+				{sessionId: session.id, userId: payment.userId},
+				'Legacy completed gift payment with no gift code — skipping (no longer recoverable via webhook)',
+			);
+			return;
+		}
+
+		if (payment.status !== 'pending') {
+			Logger.debug({sessionId: session.id, status: payment.status}, 'Payment already processed');
+			return;
+		}
+
+		const productInfo = this.productRegistry.getProduct(payment.priceId!);
+		if (!productInfo) {
+			Logger.error({sessionId: session.id, priceId: payment.priceId}, 'Unknown price ID');
+			throw new StripeError('Unknown price ID for checkout session');
+		}
+
+		const user = await this.userRepository.findUnique(payment.userId);
+		if (!user) {
+			Logger.error({userId: payment.userId, sessionId: session.id}, 'User not found');
+			throw new StripeError('User not found for checkout session');
+		}
+
+		if (session.amount_total == null || !session.currency) {
+			Logger.error(
+				{sessionId: session.id, amountTotal: session.amount_total, currency: session.currency},
+				'Checkout session missing amount or currency',
+			);
+			throw new StripeError('Checkout session missing amount or currency');
+		}
+
+		let giftCode: string | null = null;
+		if (payment.isGift) {
+			const paymentIntentId = extractId(session.payment_intent);
+			giftCode = await this.giftService.prepareGiftCode(session.id, user, productInfo, paymentIntentId);
+		}
+
+		const updateResult = await this.userRepository.updatePayment({
+			...payment.toRow(),
+			stripe_customer_id: extractId(session.customer),
+			payment_intent_id: extractId(session.payment_intent),
+			subscription_id: extractId(session.subscription),
+			invoice_id: typeof session.invoice === 'string' ? session.invoice : null,
+			amount_cents: session.amount_total,
+			currency: session.currency,
+			status: 'completed',
+			completed_at: payment.completedAt ?? new Date(),
+			gift_code: giftCode,
+		});
+
+		if (!updateResult.applied) {
+			Logger.debug({sessionId: session.id}, 'Payment update failed - already processed by concurrent webhook');
+			return;
+		}
+
+		const customerId = extractId(session.customer);
+		const subscriptionId = extractId(session.subscription);
+		const isRecurring = this.productRegistry.isRecurringSubscription(productInfo);
+
+		const userUpdates: Partial<UserRow> = {};
+
+		if (customerId && !user.stripeCustomerId) {
+			userUpdates.stripe_customer_id = customerId;
+		}
+
+		if (subscriptionId && isRecurring) {
+			userUpdates.stripe_subscription_id = subscriptionId;
+			userUpdates.premium_billing_cycle = productInfo.billingCycle || null;
+		}
+
+		if (payment.isGift) {
+			userUpdates.has_ever_purchased = true;
+		}
+
+		if (Object.keys(userUpdates).length > 0) {
+			await this.userRepository.patchUpsert(payment.userId, userUpdates, user.toRow());
+		}
+
+		if (payment.isGift) {
+			await this.giftService.finaliseGiftCode(payment.userId);
+		} else {
+			if (productInfo.premiumType === UserPremiumTypes.LIFETIME && user.stripeSubscriptionId && this.stripe) {
+				await this.cancelStripeSubscriptionImmediately(user);
+			}
+			await this.premiumService.grantPremium(
+				payment.userId,
+				productInfo.premiumType,
+				productInfo.durationMonths,
+				productInfo.billingCycle || null,
+				true,
+			);
+		}
+
+		Logger.debug(
+			{
+				userId: payment.userId,
+				sessionId: session.id,
+				productType: productInfo.type,
+				isGift: payment.isGift,
+			},
+			'Checkout session completed and processed',
+		);
+	}
+
+	private async handleDonationCheckoutCompleted(session: Stripe.Checkout.Session): Promise<void> {
+		const email = session.metadata?.donation_email;
+		if (!email) {
+			Logger.error({sessionId: session.id}, 'Donation checkout missing email in metadata');
+			throw new StripeError('Donation checkout missing email');
+		}
+
+		const customerId = extractId(session.customer);
+		if (!customerId) {
+			Logger.error({sessionId: session.id}, 'Donation checkout missing customer');
+			throw new StripeError('Donation checkout missing customer id');
+		}
+
+		const isRecurring = session.mode === 'subscription';
+		const subscriptionId = extractId(session.subscription);
+
+		if (isRecurring && !subscriptionId) {
+			Logger.error({sessionId: session.id}, 'Donation checkout missing subscription id');
+			throw new StripeError('Donation checkout missing subscription id');
+		}
+
+		const customerDetails = await this.loadDonationCustomerDetails(customerId);
+		const subscriptionDetails = isRecurring
+			? await this.loadDonationSubscriptionDetails(subscriptionId)
+			: {amountCents: null, currency: null, interval: null, currentPeriodEnd: null, cancelAt: null};
+
+		const existingDonor = await this.donationRepository.findDonorByEmail(email);
+
+		let updateResult: {applied: boolean; donor: Donor | null};
+		if (existingDonor) {
+			updateResult = await this.donationRepository.updateDonorSubscription(email, {
+				stripeCustomerId: customerId,
+				businessName: customerDetails.businessName,
+				taxId: customerDetails.taxId,
+				taxIdType: customerDetails.taxIdType,
+				stripeSubscriptionId: subscriptionId,
+				subscriptionAmountCents: subscriptionDetails.amountCents,
+				subscriptionCurrency: subscriptionDetails.currency,
+				subscriptionInterval: subscriptionDetails.interval,
+				subscriptionCurrentPeriodEnd: subscriptionDetails.currentPeriodEnd,
+				subscriptionCancelAt: subscriptionDetails.cancelAt,
+			});
+		} else {
+			const newDonor = await this.donationRepository.createDonor({
+				email,
+				stripeCustomerId: customerId,
+				businessName: customerDetails.businessName,
+				taxId: customerDetails.taxId,
+				taxIdType: customerDetails.taxIdType,
+				stripeSubscriptionId: subscriptionId,
+				subscriptionAmountCents: subscriptionDetails.amountCents,
+				subscriptionCurrency: subscriptionDetails.currency,
+				subscriptionInterval: subscriptionDetails.interval,
+				subscriptionCurrentPeriodEnd: subscriptionDetails.currentPeriodEnd,
+				subscriptionCancelAt: subscriptionDetails.cancelAt,
+			});
+			updateResult = {applied: true, donor: newDonor};
+		}
+
+		if (!updateResult.applied) {
+			Logger.debug({sessionId: session.id, email}, 'Donation update failed - already processed by concurrent webhook');
+			return;
+		}
+
+		const encodedEmail = encodeURIComponent(email);
+		const manageUrl = `${Config.endpoints.marketing}/donate/manage?email=${encodedEmail}`;
+
+		if (isRecurring) {
+			const recurringAmountCents = subscriptionDetails.amountCents;
+			const recurringCurrency = subscriptionDetails.currency;
+			const recurringInterval = subscriptionDetails.interval;
+			if (recurringAmountCents == null || !recurringCurrency || !recurringInterval) {
+				Logger.error({sessionId: session.id, subscriptionId}, 'Donation subscription details incomplete');
+				throw new StripeError('Donation subscription details incomplete');
+			}
+			await this.emailService.sendDonationConfirmation(
+				email,
+				recurringAmountCents,
+				recurringCurrency,
+				recurringInterval,
+				manageUrl,
+				null,
+			);
+		} else {
+			const oneTimeAmountCents = session.amount_total;
+			const oneTimeCurrency = session.currency;
+			if (oneTimeAmountCents == null || !oneTimeCurrency) {
+				Logger.error(
+					{sessionId: session.id, amountTotal: session.amount_total, currency: session.currency},
+					'Donation checkout missing amount or currency',
+				);
+				throw new StripeError('Donation checkout missing amount or currency');
+			}
+			await this.emailService.sendDonationConfirmation(
+				email,
+				oneTimeAmountCents,
+				oneTimeCurrency,
+				'once',
+				manageUrl,
+				null,
+			);
+		}
+
+		Logger.info(
+			{
+				email,
+				customerId,
+				subscriptionId,
+				businessName: customerDetails.businessName,
+				taxId: customerDetails.taxId,
+				taxIdType: customerDetails.taxIdType,
+				isRecurring,
+				amountCents: isRecurring ? subscriptionDetails.amountCents : session.amount_total,
+				currency: isRecurring ? subscriptionDetails.currency : session.currency,
+				interval: subscriptionDetails.interval,
+			},
+			'Donation checkout completed',
+		);
+	}
+
+	private async handleInvoicePaymentSucceeded(invoice: Stripe.Invoice): Promise<void> {
+		if (invoice.billing_reason === 'subscription_create') {
+			Logger.debug({invoiceId: invoice.id}, 'Skipping first invoice - handled by checkout.session.completed');
+			return;
+		}
+
+		const subscriptionId = this.getSubscriptionIdFromInvoice(invoice);
+		if (!subscriptionId) {
+			const billingReason = invoice.billing_reason ?? null;
+			const isSubscriptionInvoice = typeof billingReason === 'string' && billingReason.startsWith('subscription');
+			if (!isSubscriptionInvoice) {
+				Logger.debug({invoiceId: invoice.id, billingReason}, 'Skipping invoice payment without subscription context');
+				return;
+			}
+
+			Logger.error({invoiceId: invoice.id, billingReason}, 'No subscription ID found in subscription invoice');
+			throw new StripeError('Invoice missing subscription id');
+		}
+
+		const subscriptionInfo = await this.userRepository.getSubscriptionInfo(subscriptionId);
+		if (!subscriptionInfo) {
+			Logger.error({invoiceId: invoice.id, subscriptionId}, 'No subscription info found');
+			throw new StripeError('No subscription info found for invoice');
+		}
+
+		const productInfo = this.productRegistry.getProduct(subscriptionInfo.price_id);
+		if (!productInfo) {
+			Logger.error({invoiceId: invoice.id, priceId: subscriptionInfo.price_id}, 'Unknown product for renewal');
+			throw new StripeError('Unknown product for invoice renewal');
+		}
+
+		await this.premiumService.grantPremium(
+			subscriptionInfo.user_id,
+			productInfo.premiumType,
+			productInfo.durationMonths,
+			productInfo.billingCycle || null,
+			true,
+		);
+
+		Logger.debug(
+			{
+				userId: subscriptionInfo.user_id,
+				invoiceId: invoice.id,
+				subscriptionId,
+				durationMonths: productInfo.durationMonths,
+			},
+			'Subscription renewed from invoice payment',
+		);
+	}
+
+	private async handleSubscriptionUpdated(subscription: Stripe.Subscription): Promise<void> {
+		const donor = await this.donationRepository.findDonorByStripeSubscriptionId(subscription.id);
+		if (donor) {
+			await this.handleDonationSubscriptionUpdated(subscription, donor);
+			return;
+		}
+
+		const subscriptionInfo = await this.userRepository.getSubscriptionInfo(subscription.id);
+		if (!subscriptionInfo) {
+			Logger.error({subscriptionId: subscription.id}, 'No subscription info found');
+			throw new StripeError('No subscription info found for subscription update');
+		}
+
+		const computedBase = getSubscriptionCurrentPeriodEnd(subscription);
+		const willCancel = subscription.cancel_at_period_end || subscription.cancel_at != null;
+		const computedPremiumUntil = subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : computedBase;
+
+		if (!computedPremiumUntil) {
+			Logger.error({subscriptionId: subscription.id}, 'Subscription update missing period end');
+			throw new StripeError('Subscription update missing period end');
+		}
+
+		const result = await this.userRepository.updateSubscriptionStatus(subscriptionInfo.user_id, {
+			premiumWillCancel: willCancel,
+			computedPremiumUntil,
+		});
+
+		if (result.finalVersion === null) {
+			Logger.error(
+				{subscriptionId: subscription.id, userId: subscriptionInfo.user_id},
+				'Failed to update subscription status after retries',
+			);
+			throw new StripeError('Failed to update subscription status');
+		}
+
+		const updatedUser = await this.userRepository.findUnique(subscriptionInfo.user_id);
+		if (!updatedUser) {
+			Logger.error({subscriptionId: subscription.id, userId: subscriptionInfo.user_id}, 'Updated user not found');
+			throw new StripeError('Updated user not found for subscription update');
+		}
+		await this.dispatchUser(updatedUser);
+
+		Logger.debug(
+			{
+				userId: subscriptionInfo.user_id,
+				subscriptionId: subscription.id,
+				willCancel,
+				computedPremiumUntil,
+				status: subscription.status,
+			},
+			'Subscription updated (preserved gifted extension)',
+		);
+	}
+
+	private async handleDonationSubscriptionUpdated(subscription: Stripe.Subscription, donor: Donor): Promise<void> {
+		const item = getPrimarySubscriptionItem(subscription);
+		if (!item?.price?.recurring || item.price.unit_amount == null || !item.price.currency) {
+			Logger.error({subscriptionId: subscription.id}, 'Donation subscription update missing pricing details');
+			throw new StripeError('Donation subscription update missing pricing details');
+		}
+		const currentPeriodEnd = getSubscriptionItemPeriodEnd(item);
+		if (!currentPeriodEnd) {
+			Logger.error({subscriptionId: subscription.id}, 'Donation subscription update missing period end');
+			throw new StripeError('Donation subscription update missing period end');
+		}
+		const amountCents = item.price.unit_amount;
+		const currency = item.price.currency;
+		const interval = item.price.recurring.interval;
+		const cancelAt = subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null;
+
+		const updateResult = await this.donationRepository.updateDonorSubscription(donor.email, {
+			stripeCustomerId: donor.stripeCustomerId,
+			stripeSubscriptionId: subscription.id,
+			subscriptionAmountCents: amountCents,
+			subscriptionCurrency: currency,
+			subscriptionInterval: interval,
+			subscriptionCurrentPeriodEnd: currentPeriodEnd,
+			subscriptionCancelAt: cancelAt,
+		});
+
+		if (!updateResult.applied) {
+			Logger.debug(
+				{subscriptionId: subscription.id, email: donor.email},
+				'Donation subscription update failed - already processed by concurrent webhook',
+			);
+			return;
+		}
+
+		Logger.debug(
+			{
+				email: donor.email,
+				subscriptionId: subscription.id,
+				currentPeriodEnd,
+				status: subscription.status,
+			},
+			'Donation subscription updated',
+		);
+	}
+
+	private async handleSubscriptionDeleted(subscription: Stripe.Subscription): Promise<void> {
+		const donor = await this.donationRepository.findDonorByStripeSubscriptionId(subscription.id);
+		if (donor) {
+			const updatedDonor = new Donor({
+				...donor.toRow(),
+				stripe_subscription_id: null,
+				subscription_amount_cents: null,
+				subscription_currency: null,
+				subscription_interval: null,
+				subscription_current_period_end: null,
+				subscription_cancel_at: null,
+				updated_at: new Date(),
+				version: nextVersion(donor.version),
+			});
+			await this.donationRepository.upsertDonor(updatedDonor);
+			Logger.info({email: donor.email, subscriptionId: subscription.id}, 'Donation subscription deleted');
+			return;
+		}
+
+		const info = await this.userRepository.getSubscriptionInfo(subscription.id);
+		if (!info) {
+			Logger.error({subscriptionId: subscription.id}, 'Subscription delete missing subscription info');
+			throw new StripeError('Subscription delete missing subscription info');
+		}
+
+		const user = await this.userRepository.findUnique(info.user_id);
+		if (!user) {
+			Logger.error({subscriptionId: subscription.id, userId: info.user_id}, 'User not found for subscription delete');
+			throw new StripeError('User not found for subscription delete');
+		}
+
+		const updates: Partial<UserRow> = {
+			premium_will_cancel: false,
+			stripe_subscription_id: null,
+			premium_billing_cycle: null,
+		};
+
+		if (user.premiumType !== UserPremiumTypes.LIFETIME) {
+			Object.assign(updates, {premium_type: UserPremiumTypes.NONE, premium_until: null});
+		}
+
+		const updatedUser = await this.userRepository.patchUpsert(info.user_id, updates, user.toRow());
+		await this.dispatchUser(updatedUser);
+	}
+
+	private async handleChargebackCreated(dispute: Stripe.Dispute): Promise<void> {
+		const paymentIntentId = extractId(dispute.payment_intent);
+		if (!paymentIntentId) {
+			Logger.error({dispute}, 'Chargeback missing payment intent');
+			throw new StripeError('Chargeback missing payment intent');
+		}
+
+		const giftCode = await this.userRepository.findGiftCodeByPaymentIntent(paymentIntentId);
+		if (giftCode) {
+			await this.handleGiftChargeback(giftCode);
+			return;
+		}
+
+		const payment = await this.userRepository.getPaymentByPaymentIntent(paymentIntentId);
+		if (!payment) {
+			Logger.error({paymentIntentId}, 'No payment found for chargeback');
+			throw new StripeError('No payment found for chargeback');
+		}
+
+		await this.scheduleAccountDeletionForFraud(payment.userId);
+	}
+
+	private async handleGiftChargeback(giftCode: GiftCode): Promise<void> {
+		if (giftCode.redeemedByUserId) {
+			await this.premiumService.revokePremium(giftCode.redeemedByUserId);
+
+			const redeemer = await this.userRepository.findUnique(giftCode.redeemedByUserId);
+			if (redeemer?.email) {
+				await this.emailService.sendGiftChargebackNotification(redeemer.email, redeemer.username, redeemer.locale);
+			}
+
+			Logger.debug(
+				{giftCode: giftCode.code, redeemerId: giftCode.redeemedByUserId},
+				'Premium revoked due to gift chargeback',
+			);
+		}
+
+		await this.scheduleAccountDeletionForFraud(giftCode.createdByUserId);
+	}
+
+	private async handleChargebackClosed(dispute: Stripe.Dispute): Promise<void> {
+		if (dispute.status !== 'won') {
+			return;
+		}
+
+		const paymentIntentId = extractId(dispute.payment_intent);
+		if (!paymentIntentId) {
+			throw new StripeError('Chargeback withdrawal missing payment intent');
+		}
+
+		const payment = await this.userRepository.getPaymentByPaymentIntent(paymentIntentId);
+		if (!payment) {
+			throw new StripeError('No payment found for chargeback withdrawal');
+		}
+
+		const user = await this.userRepository.findUnique(payment.userId);
+		if (!user) {
+			throw new StripeError('User not found for chargeback withdrawal');
+		}
+
+		if (user.flags & UserFlags.DELETED && user.deletionReasonCode === DeletionReasons.BILLING_DISPUTE_OR_ABUSE) {
+			if (user.pendingDeletionAt) {
+				await this.userRepository.removePendingDeletion(payment.userId, user.pendingDeletionAt);
+			}
+
+			const updatedUser = await this.userRepository.patchUpsert(
+				payment.userId,
+				{
+					flags: user.flags & ~UserFlags.DELETED,
+					pending_deletion_at: null,
+					deletion_reason_code: null,
+					deletion_public_reason: null,
+					deletion_audit_log_reason: null,
+					first_refund_at: user.firstRefundAt || new Date(),
+				},
+				user.toRow(),
+			);
+			await this.userCacheService.setUserPartialResponseFromUser(updatedUser);
+
+			if (updatedUser.email) {
+				await this.emailService.sendUnbanNotification(
+					updatedUser.email,
+					updatedUser.username,
+					'chargeback withdrawal',
+					updatedUser.locale,
+				);
+			}
+
+			Logger.debug(
+				{userId: payment.userId},
+				'User unsuspended after chargeback withdrawal - 30 day purchase block applied',
+			);
+		}
+	}
+
+	private async handleRefund(charge: Stripe.Charge): Promise<void> {
+		const paymentIntentId = extractId(charge.payment_intent);
+		if (!paymentIntentId) {
+			Logger.error({chargeId: charge.id}, 'Refund missing payment intent');
+			throw new StripeError('Refund missing payment intent');
+		}
+
+		const payment = await this.userRepository.getPaymentByPaymentIntent(paymentIntentId);
+		if (!payment) {
+			Logger.error({paymentIntentId, chargeId: charge.id}, 'No payment found for refund');
+			throw new StripeError('No payment found for refund');
+		}
+
+		const user = await this.userRepository.findUnique(payment.userId);
+		if (!user) {
+			Logger.error({userId: payment.userId, chargeId: charge.id}, 'User not found for refund');
+			throw new StripeError('User not found for refund');
+		}
+
+		await this.userRepository.updatePayment({
+			...payment.toRow(),
+			status: 'refunded',
+		});
+
+		const updates: Partial<UserRow> = {
+			premium_type: UserPremiumTypes.NONE,
+			premium_until: null,
+		};
+
+		if (!user.firstRefundAt) {
+			updates.first_refund_at = new Date();
+			const updatedUser = await this.userRepository.patchUpsert(payment.userId, updates, user.toRow());
+			await this.dispatchUser(updatedUser);
+			Logger.debug(
+				{userId: payment.userId, chargeId: charge.id, paymentIntentId},
+				'First refund recorded - 30 day purchase block applied',
+			);
+		} else {
+			updates.flags = user.flags | UserFlags.PREMIUM_PURCHASE_DISABLED;
+			const updatedUser = await this.userRepository.patchUpsert(payment.userId, updates, user.toRow());
+			await this.dispatchUser(updatedUser);
+			Logger.debug(
+				{userId: payment.userId, chargeId: charge.id, paymentIntentId},
+				'Second refund recorded - permanent purchase block applied',
+			);
+		}
+	}
+
+	private getSubscriptionIdFromInvoice(invoice: Stripe.Invoice): string | null {
+		type InvoiceWithSubscription = Stripe.Invoice & {
+			subscription?: string | Stripe.Subscription;
+		};
+		const invoiceWithSubscription = invoice as InvoiceWithSubscription;
+		const directSubscription = invoiceWithSubscription.subscription;
+		if (directSubscription) {
+			return extractId(directSubscription);
+		}
+		type InvoiceWithParent = Stripe.Invoice & {
+			parent?: {
+				subscription_details?: {
+					subscription?: string;
+				};
+			};
+		};
+		type InvoiceLineWithParent = Stripe.InvoiceLineItem & {
+			parent?: {
+				subscription_item_details?: {
+					subscription?: string;
+				};
+			};
+		};
+
+		const invoiceWithParent = invoice as InvoiceWithParent;
+		const parentSubscription = invoiceWithParent.parent?.subscription_details?.subscription;
+		if (parentSubscription) {
+			return extractId(parentSubscription);
+		}
+
+		if (invoice.lines?.data?.length) {
+			for (const line of invoice.lines.data) {
+				const lineWithParent = line as InvoiceLineWithParent;
+				const subscriptionId = lineWithParent.parent?.subscription_item_details?.subscription;
+				if (subscriptionId) {
+					return extractId(subscriptionId);
+				}
+			}
+		}
+
+		return null;
+	}
+
+	private async scheduleAccountDeletionForFraud(userId: UserID): Promise<void> {
+		const user = await this.userRepository.findUnique(userId);
+		if (!user) {
+			throw new StripeError('User not found for fraud deletion');
+		}
+
+		const pendingDeletionAt = new Date(Date.now() + ms('30 days'));
+
+		const updatedUser = await this.userRepository.patchUpsert(
+			userId,
+			{
+				flags: user.flags | UserFlags.DELETED,
+				pending_deletion_at: pendingDeletionAt,
+				deletion_reason_code: DeletionReasons.BILLING_DISPUTE_OR_ABUSE,
+				deletion_public_reason: 'Payment dispute',
+				deletion_audit_log_reason: 'Chargeback filed',
+			},
+			user.toRow(),
+		);
+		await this.userCacheService.setUserPartialResponseFromUser(updatedUser);
+
+		await this.userRepository.addPendingDeletion(userId, pendingDeletionAt, DeletionReasons.BILLING_DISPUTE_OR_ABUSE);
+
+		await this.authService.terminateAllUserSessions(userId);
+
+		if (updatedUser.email) {
+			await this.emailService.sendScheduledDeletionNotification(
+				updatedUser.email,
+				updatedUser.username,
+				pendingDeletionAt,
+				'Payment dispute - chargeback filed',
+				updatedUser.locale,
+			);
+		}
+
+		Logger.debug({userId, pendingDeletionAt}, 'Account scheduled for deletion due to chargeback');
+	}
+
+	private async cancelStripeSubscriptionImmediately(user: User): Promise<void> {
+		if (!this.stripe) {
+			throw new StripeError('Stripe client not available for immediate cancellation');
+		}
+		if (!user.stripeSubscriptionId) {
+			throw new StripeError('User missing subscription id for immediate cancellation');
+		}
+		await this.stripe.subscriptions.cancel(user.stripeSubscriptionId, {invoice_now: false, prorate: false});
+		const updatedUser = await this.userRepository.patchUpsert(user.id, {
+			stripe_subscription_id: null,
+			premium_billing_cycle: null,
+			premium_will_cancel: false,
+		});
+		await this.dispatchUser(updatedUser);
+		Logger.debug({userId: user.id}, 'Canceled active subscription due to lifetime grant');
+	}
+
+	private async dispatchUser(user: User): Promise<void> {
+		await this.gatewayService.dispatchPresence({
+			userId: user.id,
+			event: 'USER_UPDATE',
+			data: mapUserToPrivateResponse(user),
+		});
+	}
+
+	private async loadDonationCustomerDetails(customerId: string): Promise<DonationCustomerDetails> {
+		if (!this.stripe) {
+			throw new StripeError('Stripe client not available for donation customer lookup');
+		}
+
+		try {
+			const customer = await this.stripe.customers.retrieve(customerId);
+			if (customer && !customer.deleted) {
+				const businessName = customer.name ?? null;
+				const primaryTaxId = customer.tax_ids?.data?.[0] ?? null;
+				return {
+					businessName,
+					taxId: primaryTaxId?.value ?? null,
+					taxIdType: primaryTaxId?.type ?? null,
+				};
+			}
+		} catch (error) {
+			Logger.error({error, customerId}, 'Failed to retrieve customer details');
+			throw error;
+		}
+
+		throw new StripeError('Donation customer not found');
+	}
+
+	private async loadDonationSubscriptionDetails(subscriptionId: string | null): Promise<DonationSubscriptionDetails> {
+		if (!subscriptionId) {
+			throw new StripeError('Donation subscription id missing for lookup');
+		}
+		if (!this.stripe) {
+			throw new StripeError('Stripe client not available for donation subscription lookup');
+		}
+
+		try {
+			const subscription = await this.stripe.subscriptions.retrieve(subscriptionId);
+			const item = getPrimarySubscriptionItem(subscription);
+			if (!item) {
+				Logger.error({subscriptionId}, 'Subscription has no items for donation checkout');
+				throw new StripeError('Donation subscription has no items');
+			}
+
+			if (!item.price?.recurring || item.price.unit_amount == null || !item.price.currency) {
+				Logger.error({subscriptionId}, 'Donation subscription missing pricing details');
+				throw new StripeError('Donation subscription missing pricing details');
+			}
+
+			const currentPeriodEnd = getSubscriptionItemPeriodEnd(item);
+			if (!currentPeriodEnd) {
+				Logger.error({subscriptionId}, 'Donation subscription missing period end');
+				throw new StripeError('Donation subscription missing period end');
+			}
+
+			const cancelAt = subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null;
+
+			return {
+				amountCents: item.price.unit_amount,
+				currency: item.price.currency,
+				interval: item.price.recurring.interval,
+				currentPeriodEnd,
+				cancelAt,
+			};
+		} catch (error) {
+			Logger.error({error, subscriptionId}, 'Failed to retrieve subscription details');
+			throw error;
+		}
+	}
+}

packages/api/src/stripe/tests/StripeCheckoutService.test.tsx

@@ -0,0 +1,425 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {Config} from '@fluxer/api/src/Config';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createStripeApiHandlers} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {server} from '@fluxer/api/src/test/msw/server';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserFlags, UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+const MOCK_CUSTOMER_ID = 'cus_test_existing';
+
+const MOCK_PRICES = {
+	monthlyUsd: 'price_monthly_usd',
+	monthlyEur: 'price_monthly_eur',
+	yearlyUsd: 'price_yearly_usd',
+	yearlyEur: 'price_yearly_eur',
+	gift1MonthUsd: 'price_gift_1_month_usd',
+	gift1MonthEur: 'price_gift_1_month_eur',
+	gift1YearUsd: 'price_gift_1_year_usd',
+	gift1YearEur: 'price_gift_1_year_eur',
+};
+
+interface UrlResponse {
+	url: string;
+}
+
+interface PriceIdsResponse {
+	currency: string;
+	monthly: string | null;
+	yearly: string | null;
+	gift_1_month: string | null;
+	gift_1_year: string | null;
+}
+
+describe('StripeCheckoutService', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let stripeHandlers: ReturnType<typeof createStripeApiHandlers>;
+	let originalPrices: typeof Config.stripe.prices | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalPrices = Config.stripe.prices;
+		Config.stripe.prices = MOCK_PRICES;
+
+		stripeHandlers = createStripeApiHandlers();
+	});
+
+	beforeEach(async () => {
+		await harness.reset();
+		stripeHandlers.reset();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.prices = originalPrices;
+	});
+
+	describe('POST /stripe/checkout/subscription', () => {
+		test('creates monthly subscription checkout session', async () => {
+			const account = await createTestAccount(harness);
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+
+			expect(stripeHandlers.spies.createdCheckoutSessions).toHaveLength(1);
+			const session = stripeHandlers.spies.createdCheckoutSessions[0];
+			expect(session?.mode).toBe('subscription');
+			expect(session?.line_items).toHaveLength(1);
+			expect(session?.line_items?.[0]?.price).toBe(MOCK_PRICES.monthlyUsd);
+		});
+
+		test('creates yearly subscription checkout session', async () => {
+			const account = await createTestAccount(harness);
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.yearlyUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+
+			const session = stripeHandlers.spies.createdCheckoutSessions[0];
+			expect(session?.mode).toBe('subscription');
+		});
+
+		test('creates stripe customer if user does not have one', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			expect(stripeHandlers.spies.createdCustomers).toHaveLength(1);
+			expect(stripeHandlers.spies.createdCustomers[0]?.id).toMatch(/^cus_test_new_/);
+		});
+
+		test('uses existing stripe customer if user has one', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({stripe_customer_id: MOCK_CUSTOMER_ID})
+				.execute();
+
+			await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			const session = stripeHandlers.spies.createdCheckoutSessions[0];
+			expect(session?.customer).toBe(MOCK_CUSTOMER_ID);
+		});
+
+		test('includes correct success and cancel URLs', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			const session = stripeHandlers.spies.createdCheckoutSessions[0];
+			expect(session?.success_url).toBe(`${Config.endpoints.webApp}/premium-callback?status=success`);
+			expect(session?.cancel_url).toBe(`${Config.endpoints.webApp}/premium-callback?status=cancel`);
+		});
+
+		test('rejects unknown price ID', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: 'price_unknown'})
+				.expect(400, APIErrorCodes.STRIPE_INVALID_PRODUCT)
+				.execute();
+		});
+
+		test('rejects when lifetime user tries to buy recurring subscription', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 1,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(403, APIErrorCodes.PREMIUM_PURCHASE_BLOCKED)
+				.execute();
+		});
+
+		test('rejects unauthenticated requests', async () => {
+			await createBuilder(harness, '')
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(401)
+				.execute();
+		});
+	});
+
+	describe('POST /stripe/checkout/gift', () => {
+		test('creates gift 1 month checkout session', async () => {
+			const account = await createTestAccount(harness);
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/gift')
+				.body({price_id: MOCK_PRICES.gift1MonthUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+
+			const session = stripeHandlers.spies.createdCheckoutSessions[0];
+			expect(session?.mode).toBe('payment');
+		});
+
+		test('creates gift 1 year checkout session', async () => {
+			const account = await createTestAccount(harness);
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/gift')
+				.body({price_id: MOCK_PRICES.gift1YearUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+		});
+
+		test('allows lifetime user to buy gift subscriptions', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 1,
+				})
+				.execute();
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/gift')
+				.body({price_id: MOCK_PRICES.gift1MonthUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+		});
+
+		test('rejects non-gift price ID via gift endpoint', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/gift')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(400, APIErrorCodes.STRIPE_INVALID_PRODUCT_CONFIGURATION)
+				.execute();
+		});
+	});
+
+	describe('POST /premium/customer-portal', () => {
+		test('creates customer portal session for user with stripe customer ID', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({stripe_customer_id: MOCK_CUSTOMER_ID})
+				.execute();
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/premium/customer-portal')
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/billing\.stripe\.com/);
+			expect(stripeHandlers.spies.createdPortalSessions).toHaveLength(1);
+			expect(stripeHandlers.spies.createdPortalSessions[0]?.customer).toBe(MOCK_CUSTOMER_ID);
+		});
+
+		test('includes correct return URL', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({stripe_customer_id: MOCK_CUSTOMER_ID})
+				.execute();
+
+			await createBuilder<UrlResponse>(harness, account.token).post('/premium/customer-portal').execute();
+
+			const session = stripeHandlers.spies.createdPortalSessions[0];
+			expect(session?.return_url).toBe(`${Config.endpoints.webApp}/premium-callback?status=closed-billing-portal`);
+		});
+
+		test('rejects when user has no stripe customer ID', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/premium/customer-portal')
+				.expect(400, APIErrorCodes.STRIPE_NO_PURCHASE_HISTORY)
+				.execute();
+		});
+
+		test('rejects unauthenticated requests', async () => {
+			await createBuilder(harness, '').post('/premium/customer-portal').expect(401).execute();
+		});
+	});
+
+	describe('GET /premium/price-ids', () => {
+		test('returns USD prices for non-EEA country', async () => {
+			const response = await createBuilder<PriceIdsResponse>(harness, '')
+				.get('/premium/price-ids?country_code=US')
+				.execute();
+
+			expect(response.currency).toBe('USD');
+			expect(response.monthly).toBe(MOCK_PRICES.monthlyUsd);
+			expect(response.yearly).toBe(MOCK_PRICES.yearlyUsd);
+			expect(response.gift_1_month).toBe(MOCK_PRICES.gift1MonthUsd);
+			expect(response.gift_1_year).toBe(MOCK_PRICES.gift1YearUsd);
+		});
+
+		test('returns EUR prices for EEA country', async () => {
+			const response = await createBuilder<PriceIdsResponse>(harness, '')
+				.get('/premium/price-ids?country_code=DE')
+				.execute();
+
+			expect(response.currency).toBe('EUR');
+			expect(response.monthly).toBe(MOCK_PRICES.monthlyEur);
+			expect(response.yearly).toBe(MOCK_PRICES.yearlyEur);
+			expect(response.gift_1_month).toBe(MOCK_PRICES.gift1MonthEur);
+			expect(response.gift_1_year).toBe(MOCK_PRICES.gift1YearEur);
+		});
+
+		test('returns USD prices when country code is not provided', async () => {
+			const response = await createBuilder<PriceIdsResponse>(harness, '').get('/premium/price-ids').execute();
+
+			expect(response.currency).toBe('USD');
+			expect(response.monthly).toBe(MOCK_PRICES.monthlyUsd);
+		});
+
+		test('handles various EEA countries correctly', async () => {
+			const eeaCountries = ['FR', 'IT', 'ES', 'NL', 'PL', 'NO', 'SE'];
+
+			for (const country of eeaCountries) {
+				const response = await createBuilder<PriceIdsResponse>(harness, '')
+					.get(`/premium/price-ids?country_code=${country}`)
+					.execute();
+				expect(response.currency).toBe('EUR');
+			}
+		});
+	});
+
+	describe('validateUserCanPurchase', () => {
+		test('allows normal user to purchase', async () => {
+			const account = await createTestAccount(harness);
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+		});
+
+		test('rejects unclaimed accounts', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token).post(`/test/users/${account.userId}/unclaim`).body(null).execute();
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(400, APIErrorCodes.UNCLAIMED_ACCOUNT_CANNOT_MAKE_PURCHASES)
+				.execute();
+		});
+
+		test('rejects when PREMIUM_PURCHASE_DISABLED flag is set', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.patch(`/test/users/${account.userId}/flags`)
+				.body({flags: UserFlags.PREMIUM_PURCHASE_DISABLED.toString()})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(403, APIErrorCodes.PREMIUM_PURCHASE_BLOCKED)
+				.execute();
+		});
+
+		test('rejects within 30 days of first refund', async () => {
+			const account = await createTestAccount(harness);
+			const twentyDaysAgo = new Date(Date.now() - 20 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({first_refund_at: twentyDaysAgo.toISOString()})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.expect(403, APIErrorCodes.PREMIUM_PURCHASE_BLOCKED)
+				.execute();
+		});
+
+		test('allows purchase exactly 30 days after first refund', async () => {
+			const account = await createTestAccount(harness);
+			const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({first_refund_at: thirtyDaysAgo.toISOString()})
+				.execute();
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+		});
+
+		test('allows purchase more than 30 days after first refund', async () => {
+			const account = await createTestAccount(harness);
+			const fortyDaysAgo = new Date(Date.now() - 40 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({first_refund_at: fortyDaysAgo.toISOString()})
+				.execute();
+
+			const response = await createBuilder<UrlResponse>(harness, account.token)
+				.post('/stripe/checkout/subscription')
+				.body({price_id: MOCK_PRICES.monthlyUsd})
+				.execute();
+
+			expect(response.url).toMatch(/^https:\/\/checkout\.stripe\.com/);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeGiftService.test.tsx

@@ -0,0 +1,86 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {Config} from '@fluxer/api/src/Config';
+import {createGuild} from '@fluxer/api/src/guild/tests/GuildTestUtils';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('StripeGiftService', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalVisionariesGuildId: string | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalVisionariesGuildId = Config.instance.visionariesGuildId ?? undefined;
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.instance.visionariesGuildId = originalVisionariesGuildId;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		const owner = await createTestAccount(harness);
+		const visionariesGuild = await createGuild(harness, owner.token, 'Visionaries Gift Test Guild');
+		Config.instance.visionariesGuildId = visionariesGuild.id;
+	});
+
+	describe('GET /gifts/:code', () => {
+		test('returns error for unknown gift code', async () => {
+			await createBuilder(harness, '')
+				.get('/gifts/invalid_code')
+				.expect(404, APIErrorCodes.UNKNOWN_GIFT_CODE)
+				.execute();
+		});
+	});
+
+	describe('POST /gifts/:code/redeem', () => {
+		test('requires authentication', async () => {
+			await createBuilder(harness, 'invalid-token').post('/gifts/test_code/redeem').expect(401).execute();
+		});
+
+		test('returns error for unknown gift code', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/gifts/invalid_code/redeem')
+				.expect(404, APIErrorCodes.UNKNOWN_GIFT_CODE)
+				.execute();
+		});
+	});
+
+	describe('GET /users/@me/gifts', () => {
+		test('returns empty array when user has no gifts', async () => {
+			const account = await createTestAccount(harness);
+
+			const gifts = await createBuilder<Array<unknown>>(harness, account.token).get('/users/@me/gifts').execute();
+
+			expect(gifts).toEqual([]);
+		});
+
+		test('requires authentication', async () => {
+			await createBuilder(harness, 'invalid-token').get('/users/@me/gifts').expect(401).execute();
+		});
+	});
+});

packages/api/src/stripe/tests/StripePremiumService.test.tsx

@@ -0,0 +1,205 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {Config} from '@fluxer/api/src/Config';
+import {createGuild} from '@fluxer/api/src/guild/tests/GuildTestUtils';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('StripePremiumService', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalVisionariesGuildId: string | undefined;
+	let originalOperatorsGuildId: string | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalVisionariesGuildId = Config.instance.visionariesGuildId ?? undefined;
+		originalOperatorsGuildId = Config.instance.operatorsGuildId ?? undefined;
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.instance.visionariesGuildId = originalVisionariesGuildId;
+		Config.instance.operatorsGuildId = originalOperatorsGuildId;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		const owner = await createTestAccount(harness);
+		const visionariesGuild = await createGuild(harness, owner.token, 'Visionaries Test Guild');
+		const operatorsGuild = await createGuild(harness, owner.token, 'Operators Test Guild');
+		Config.instance.visionariesGuildId = visionariesGuild.id;
+		Config.instance.operatorsGuildId = operatorsGuild.id;
+	});
+
+	describe('POST /premium/visionary/rejoin', () => {
+		test('allows visionary users to rejoin guild', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 0,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token).post('/premium/visionary/rejoin').expect(204).execute();
+		});
+
+		test('rejects users without visionary access', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/premium/visionary/rejoin')
+				.expect(403, APIErrorCodes.MISSING_ACCESS)
+				.execute();
+		});
+
+		test('requires authentication', async () => {
+			await createBuilder(harness, 'invalid-token').post('/premium/visionary/rejoin').expect(401).execute();
+		});
+	});
+
+	describe('POST /premium/operator/rejoin', () => {
+		test('allows visionary users to rejoin operator guild', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 1,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token).post('/premium/operator/rejoin').expect(204).execute();
+		});
+
+		test('rejects users without visionary access', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/premium/operator/rejoin')
+				.expect(403, APIErrorCodes.MISSING_ACCESS)
+				.execute();
+		});
+
+		test('requires authentication', async () => {
+			await createBuilder(harness, 'invalid-token').post('/premium/operator/rejoin').expect(401).execute();
+		});
+	});
+
+	describe('premium duration and stacking', () => {
+		test('sets premium_since on first grant', async () => {
+			const account = await createTestAccount(harness);
+			const before = new Date();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			const me = await createBuilder<{premium_since: string | null; premium_type: number}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(me.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(me.premium_since).toBeDefined();
+			const premiumSince = new Date(me.premium_since!);
+			expect(premiumSince.getTime()).toBeGreaterThanOrEqual(before.getTime() - 1000);
+			expect(premiumSince.getTime()).toBeLessThanOrEqual(Date.now() + 1000);
+		});
+
+		test('preserves premium_since on renewal', async () => {
+			const account = await createTestAccount(harness);
+			const originalSince = new Date('2024-01-01T00:00:00Z');
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_since: originalSince.toISOString(),
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_since: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(me1.premium_since).toBe(originalSince.toISOString());
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			const me2 = await createBuilder<{premium_since: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(me2.premium_since).toBe(originalSince.toISOString());
+		});
+
+		test('supports lifetime premium type', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 5,
+				})
+				.execute();
+
+			const me = await createBuilder<{premium_type: number; premium_lifetime_sequence: number | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+
+			expect(me.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(me.premium_lifetime_sequence).toBe(5);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeSubscriptionService.test.tsx

@@ -0,0 +1,346 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createPwnedPasswordsRangeHandler} from '@fluxer/api/src/test/msw/handlers/PwnedPasswordsHandlers';
+import {createStripeApiHandlers} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {server} from '@fluxer/api/src/test/msw/server';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('StripeSubscriptionService', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let stripeHandlers: ReturnType<typeof createStripeApiHandlers>;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		stripeHandlers = createStripeApiHandlers();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		stripeHandlers.resetAll();
+		server.use(...stripeHandlers.handlers, createPwnedPasswordsRangeHandler());
+	});
+
+	describe('POST /premium/cancel-subscription', () => {
+		test('cancels subscription at period end', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: false,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token).post('/premium/cancel-subscription').expect(204).execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(1);
+			const update = stripeHandlers.spies.updatedSubscriptions[0];
+			expect(update?.id).toBe('sub_test_1');
+			expect(update?.params.cancel_at_period_end).toBe('true');
+
+			const me = await createBuilder<{premium_will_cancel: boolean}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(me.premium_will_cancel).toBe(true);
+		});
+
+		test('rejects when no active subscription', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/premium/cancel-subscription')
+				.expect(400, APIErrorCodes.STRIPE_NO_ACTIVE_SUBSCRIPTION)
+				.execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(0);
+		});
+
+		test('rejects when subscription already canceling', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: true,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/premium/cancel-subscription')
+				.expect(400, APIErrorCodes.STRIPE_SUBSCRIPTION_ALREADY_CANCELING)
+				.execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(0);
+		});
+
+		test('rejects when user does not exist', async () => {
+			await createBuilder(harness, 'invalid-token').post('/premium/cancel-subscription').expect(401).execute();
+		});
+
+		test('handles stripe api errors gracefully', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: false,
+				})
+				.execute();
+
+			stripeHandlers.reset();
+			server.use(...createStripeApiHandlers({subscriptionShouldFail: true}).handlers);
+
+			await createBuilder(harness, account.token)
+				.post('/premium/cancel-subscription')
+				.expect(400, APIErrorCodes.STRIPE_ERROR)
+				.execute();
+		});
+	});
+
+	describe('POST /premium/reactivate-subscription', () => {
+		test('reactivates subscription', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: true,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token).post('/premium/reactivate-subscription').expect(204).execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(1);
+			const update = stripeHandlers.spies.updatedSubscriptions[0];
+			expect(update?.id).toBe('sub_test_1');
+			expect(update?.params.cancel_at_period_end).toBe('false');
+
+			const me = await createBuilder<{premium_will_cancel: boolean}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(me.premium_will_cancel).toBe(false);
+		});
+
+		test('rejects when no subscription id', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post('/premium/reactivate-subscription')
+				.expect(400, APIErrorCodes.STRIPE_NO_SUBSCRIPTION)
+				.execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(0);
+		});
+
+		test('rejects when subscription not canceling', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: false,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/premium/reactivate-subscription')
+				.expect(400, APIErrorCodes.STRIPE_SUBSCRIPTION_NOT_CANCELING)
+				.execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(0);
+		});
+
+		test('rejects when user does not exist', async () => {
+			await createBuilder(harness, 'invalid-token').post('/premium/reactivate-subscription').expect(401).execute();
+		});
+
+		test('handles stripe api errors gracefully', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+					premium_will_cancel: true,
+				})
+				.execute();
+
+			stripeHandlers.reset();
+			server.use(...createStripeApiHandlers({subscriptionShouldFail: true}).handlers);
+
+			await createBuilder(harness, account.token)
+				.post('/premium/reactivate-subscription')
+				.expect(400, APIErrorCodes.STRIPE_ERROR)
+				.execute();
+		});
+	});
+
+	describe('extendSubscriptionWithGiftTrial', () => {
+		test('updates subscription trial_end to extend by gift duration', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: 'gift_code_123',
+				})
+				.expect(204)
+				.execute();
+
+			expect(stripeHandlers.spies.retrievedSubscriptions).toContain('sub_test_1');
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(1);
+			const update = stripeHandlers.spies.updatedSubscriptions[0];
+			expect(update?.id).toBe('sub_test_1');
+			expect(update?.params.trial_end).toBeDefined();
+			expect(update?.params.proration_behavior).toBe('none');
+		});
+
+		test('stacks multiple gifts by reading current trial_end', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: 'gift_1',
+				})
+				.expect(204)
+				.execute();
+
+			stripeHandlers.reset();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 6,
+					idempotency_key: 'gift_2',
+				})
+				.expect(204)
+				.execute();
+
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(1);
+			const update = stripeHandlers.spies.updatedSubscriptions[0];
+			expect(update?.params.trial_end).toBeDefined();
+		});
+
+		test('enforces idempotency with cache (gift already applied)', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+				})
+				.execute();
+
+			const idempotencyKey = 'gift_code_unique_123';
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: idempotencyKey,
+				})
+				.expect(204)
+				.execute();
+
+			stripeHandlers.reset();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: idempotencyKey,
+				})
+				.expect(204)
+				.execute();
+
+			expect(stripeHandlers.spies.retrievedSubscriptions).toHaveLength(0);
+			expect(stripeHandlers.spies.updatedSubscriptions).toHaveLength(0);
+		});
+
+		test('rejects when user has no active subscription', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: 'gift_no_sub',
+				})
+				.expect(400, APIErrorCodes.NO_ACTIVE_SUBSCRIPTION)
+				.execute();
+
+			expect(stripeHandlers.spies.retrievedSubscriptions).toHaveLength(0);
+		});
+
+		test('handles stripe api errors gracefully', async () => {
+			const account = await createTestAccount(harness);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_test_1',
+					premium_type: 1,
+				})
+				.execute();
+
+			stripeHandlers.reset();
+			server.use(...createStripeApiHandlers({subscriptionShouldFail: true}).handlers);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/extend-subscription-trial`)
+				.body({
+					duration_months: 3,
+					idempotency_key: 'gift_fail',
+				})
+				.expect(400, APIErrorCodes.STRIPE_ERROR)
+				.execute();
+		});
+	});
+});

packages/api/src/stripe/tests/StripeUtils.test.tsx

@@ -0,0 +1,156 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {addMonthsClamp} from '@fluxer/api/src/stripe/StripeUtils';
+import {describe, expect, it} from 'vitest';
+
+describe('addMonthsClamp', () => {
+	it('adds months normally when no overflow occurs', () => {
+		const result = addMonthsClamp(new Date('2024-01-15'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(15);
+	});
+
+	it('clamps Jan 31 + 1 month to Feb 29 (leap year)', () => {
+		const result = addMonthsClamp(new Date('2024-01-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(29);
+	});
+
+	it('clamps Jan 31 + 1 month to Feb 28 (non-leap year)', () => {
+		const result = addMonthsClamp(new Date('2023-01-31'), 1);
+		expect(result.getFullYear()).toBe(2023);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(28);
+	});
+
+	it('clamps Jan 30 + 1 month to Feb 28 (non-leap year)', () => {
+		const result = addMonthsClamp(new Date('2023-01-30'), 1);
+		expect(result.getFullYear()).toBe(2023);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(28);
+	});
+
+	it('clamps Jan 29 + 1 month to Feb 28 (non-leap year)', () => {
+		const result = addMonthsClamp(new Date('2023-01-29'), 1);
+		expect(result.getFullYear()).toBe(2023);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(28);
+	});
+
+	it('clamps Mar 31 + 1 month to Apr 30', () => {
+		const result = addMonthsClamp(new Date('2024-03-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(3);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('clamps May 31 + 1 month to Jun 30', () => {
+		const result = addMonthsClamp(new Date('2024-05-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(5);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('clamps Jul 31 + 1 month to Aug 31 (no clamping needed)', () => {
+		const result = addMonthsClamp(new Date('2024-07-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(7);
+		expect(result.getDate()).toBe(31);
+	});
+
+	it('clamps Aug 31 + 1 month to Sep 30', () => {
+		const result = addMonthsClamp(new Date('2024-08-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(8);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('clamps Oct 31 + 1 month to Nov 30', () => {
+		const result = addMonthsClamp(new Date('2024-10-31'), 1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(10);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('clamps Dec 31 + 1 month to Jan 31 of next year (no clamping needed)', () => {
+		const result = addMonthsClamp(new Date('2024-12-31'), 1);
+		expect(result.getFullYear()).toBe(2025);
+		expect(result.getMonth()).toBe(0);
+		expect(result.getDate()).toBe(31);
+	});
+
+	it('handles year boundary: Feb 29 (leap) + 12 months = Feb 28 (non-leap)', () => {
+		const result = addMonthsClamp(new Date('2024-02-29'), 12);
+		expect(result.getFullYear()).toBe(2025);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(28);
+	});
+
+	it('handles multiple months: Jan 31 + 2 months = Mar 31', () => {
+		const result = addMonthsClamp(new Date('2024-01-31'), 2);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(2);
+		expect(result.getDate()).toBe(31);
+	});
+
+	it('handles multiple months with clamping: Jan 31 + 3 months = Apr 30', () => {
+		const result = addMonthsClamp(new Date('2024-01-31'), 3);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(3);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('handles negative months: Mar 31 - 1 month = Feb 29 (leap year)', () => {
+		const result = addMonthsClamp(new Date('2024-03-31'), -1);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(29);
+	});
+
+	it('handles negative months: Mar 31 - 1 month = Feb 28 (non-leap year)', () => {
+		const result = addMonthsClamp(new Date('2023-03-31'), -1);
+		expect(result.getFullYear()).toBe(2023);
+		expect(result.getMonth()).toBe(1);
+		expect(result.getDate()).toBe(28);
+	});
+
+	it('handles year boundary with negative months: Jan 31 - 2 months = Nov 30', () => {
+		const result = addMonthsClamp(new Date('2024-01-31'), -2);
+		expect(result.getFullYear()).toBe(2023);
+		expect(result.getMonth()).toBe(10);
+		expect(result.getDate()).toBe(30);
+	});
+
+	it('handles zero months (returns same date)', () => {
+		const result = addMonthsClamp(new Date('2024-01-31'), 0);
+		expect(result.getFullYear()).toBe(2024);
+		expect(result.getMonth()).toBe(0);
+		expect(result.getDate()).toBe(31);
+	});
+
+	it('does not mutate the input date', () => {
+		const input = new Date('2024-01-31');
+		const inputTime = input.getTime();
+		addMonthsClamp(input, 1);
+		expect(input.getTime()).toBe(inputTime);
+	});
+});

packages/api/src/stripe/tests/StripeWebhookCheckout.test.tsx

@@ -0,0 +1,330 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {clearDonationTestEmails, listDonationTestEmails} from '@fluxer/api/src/donation/tests/DonationTestUtils';
+import {ProductType} from '@fluxer/api/src/stripe/ProductRegistry';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createCheckoutCompletedEvent,
+	createMockWebhookPayload,
+	createStripeApiHandlers,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {server} from '@fluxer/api/src/test/msw/server';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, afterEach, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+const MOCK_PRICES = {
+	monthlyUsd: 'price_monthly_usd',
+	monthlyEur: 'price_monthly_eur',
+	yearlyUsd: 'price_yearly_usd',
+	yearlyEur: 'price_yearly_eur',
+	visionaryUsd: 'price_visionary_usd',
+	visionaryEur: 'price_visionary_eur',
+	giftVisionaryUsd: 'price_gift_visionary_usd',
+	giftVisionaryEur: 'price_gift_visionary_eur',
+	gift1MonthUsd: 'price_gift_1_month_usd',
+	gift1MonthEur: 'price_gift_1_month_eur',
+	gift1YearUsd: 'price_gift_1_year_usd',
+	gift1YearEur: 'price_gift_1_year_eur',
+};
+
+describe('StripeWebhookService - checkout.session.completed', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let stripeHandlers: ReturnType<typeof createStripeApiHandlers>;
+	let originalWebhookSecret: string | undefined;
+	let originalPrices: typeof Config.stripe.prices | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		originalPrices = Config.stripe.prices;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+		Config.stripe.prices = MOCK_PRICES;
+
+		stripeHandlers = createStripeApiHandlers();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		stripeHandlers.reset();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	afterEach(() => {
+		server.resetHandlers();
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+		Config.stripe.prices = originalPrices;
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	async function sendWebhookExpectStripeError(eventData: StripeWebhookEventData): Promise<void> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		await createBuilder(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.expect(400, APIErrorCodes.STRIPE_ERROR)
+			.execute();
+	}
+
+	describe('premium checkout', () => {
+		test('processes completed premium checkout session successfully', async () => {
+			const account = await createTestAccount(harness);
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const {UserRepository} = await import('@fluxer/api/src/user/repositories/UserRepository');
+			const paymentRepository = new PaymentRepository();
+			const userRepository = new UserRepository();
+
+			await paymentRepository.createPayment({
+				checkout_session_id: 'cs_test_123',
+				user_id: createUserID(BigInt(account.userId)),
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'pending',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			const eventData = createCheckoutCompletedEvent({
+				sessionId: 'cs_test_123',
+				customerId: 'cus_test_1',
+				subscriptionId: 'sub_test_1',
+				metadata: {},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const updatedPayment = await userRepository.getPaymentByCheckoutSession('cs_test_123');
+			expect(updatedPayment?.status).toBe('completed');
+			expect(updatedPayment?.stripeCustomerId).toBe('cus_test_1');
+			expect(updatedPayment?.subscriptionId).toBe('sub_test_1');
+
+			const user = await createBuilder<{premium_type: number}>(harness, account.token).get('/users/@me').execute();
+			expect(user.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+		});
+
+		test('updates user with Stripe customer ID on first purchase', async () => {
+			const account = await createTestAccount(harness);
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const {UserRepository} = await import('@fluxer/api/src/user/repositories/UserRepository');
+			const paymentRepository = new PaymentRepository();
+			const userRepository = new UserRepository();
+
+			await paymentRepository.createPayment({
+				checkout_session_id: 'cs_test_123',
+				user_id: createUserID(BigInt(account.userId)),
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'pending',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			const eventData = createCheckoutCompletedEvent({
+				sessionId: 'cs_test_123',
+				customerId: 'cus_new_123',
+				metadata: {},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const user = await userRepository.findUnique(createUserID(BigInt(account.userId)));
+			expect(user?.stripeCustomerId).toBe('cus_new_123');
+		});
+
+		test('skips already processed payment', async () => {
+			const account = await createTestAccount(harness);
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const paymentRepository = new PaymentRepository();
+
+			await paymentRepository.createPayment({
+				checkout_session_id: 'cs_test_123',
+				user_id: createUserID(BigInt(account.userId)),
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			const beforeUser = await createBuilder<{premium_type: number}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			const eventData = createCheckoutCompletedEvent({
+				sessionId: 'cs_test_123',
+				metadata: {},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const afterUser = await createBuilder<{premium_type: number}>(harness, account.token).get('/users/@me').execute();
+			expect(afterUser.premium_type).toBe(beforeUser.premium_type);
+		});
+
+		test('handles missing payment record gracefully', async () => {
+			const eventData = createCheckoutCompletedEvent({
+				sessionId: 'cs_nonexistent_123',
+				metadata: {},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+		});
+
+		test('handles external donate checkout sessions without internal payment records', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'checkout.session.completed',
+				data: {
+					object: {
+						id: 'cs_external_donate_123',
+						object: 'checkout.session',
+						mode: 'payment',
+						status: 'complete',
+						payment_status: 'paid',
+						submit_type: 'donate',
+						payment_link: 'plink_external_123',
+						payment_intent: 'pi_external_123',
+						amount_total: 1000,
+						currency: 'usd',
+						customer: null,
+						customer_email: null,
+						customer_details: {
+							email: 'external-donor@example.com',
+							name: 'External Donor',
+						},
+						metadata: {},
+					},
+				},
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+		});
+
+		test('handles gift purchase correctly', async () => {
+			const account = await createTestAccount(harness);
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const {UserRepository} = await import('@fluxer/api/src/user/repositories/UserRepository');
+			const paymentRepository = new PaymentRepository();
+			const userRepository = new UserRepository();
+
+			await paymentRepository.createPayment({
+				checkout_session_id: 'cs_test_123',
+				user_id: createUserID(BigInt(account.userId)),
+				price_id: MOCK_PRICES.gift1MonthUsd,
+				product_type: ProductType.GIFT_1_MONTH,
+				status: 'pending',
+				is_gift: true,
+				created_at: new Date(),
+			});
+
+			const eventData = createCheckoutCompletedEvent({
+				sessionId: 'cs_test_123',
+				metadata: {},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const updatedPayment = await userRepository.getPaymentByCheckoutSession('cs_test_123');
+			expect(updatedPayment?.status).toBe('completed');
+			expect(updatedPayment?.giftCode).not.toBeNull();
+
+			const user = await createBuilder<{premium_type: number}>(harness, account.token).get('/users/@me').execute();
+			expect(user.premium_type).toBe(UserPremiumTypes.NONE);
+		});
+	});
+
+	describe('donation checkout', () => {
+		test('handles donation without email gracefully', async () => {
+			const eventData = createCheckoutCompletedEvent({
+				metadata: {is_donation: 'true'},
+			});
+
+			await sendWebhookExpectStripeError(eventData);
+		});
+
+		test('records donation with valid email and subscription', async () => {
+			await clearDonationTestEmails(harness);
+
+			const donationEmail = 'donor@example.com';
+			const eventData = createCheckoutCompletedEvent({
+				customerId: 'cus_donation_1',
+				subscriptionId: 'sub_donation_1',
+				metadata: {is_donation: 'true', donation_email: donationEmail},
+			});
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const {DonationRepository} = await import('@fluxer/api/src/donation/DonationRepository');
+			const donationRepository = new DonationRepository();
+
+			const donor = await donationRepository.findDonorByEmail(donationEmail);
+			expect(donor).not.toBeNull();
+			expect(donor?.stripeCustomerId).toBe('cus_donation_1');
+			expect(donor?.stripeSubscriptionId).toBe('sub_donation_1');
+
+			const emails = await listDonationTestEmails(harness, {recipient: donationEmail});
+			const confirmationEmail = emails.find((e) => e.type === 'donation_confirmation');
+			expect(confirmationEmail).toBeDefined();
+			expect(confirmationEmail?.to).toBe(donationEmail);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookCore.test.tsx

@@ -0,0 +1,158 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {Config} from '@fluxer/api/src/Config';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('Stripe Webhook - Core Handling', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalWebhookSecret: string | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(
+		eventData: StripeWebhookEventData,
+		options?: {signature?: string; expectStatus?: number},
+	): Promise<{response: Response; text: string}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = options?.signature ?? createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		const result = await createBuilder(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.executeRaw();
+
+		return result;
+	}
+
+	describe('handleWebhook', () => {
+		test('rejects webhook with invalid signature', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'checkout.session.completed',
+				data: {object: {id: 'cs_test_123'}},
+			};
+
+			const {response} = await sendWebhook(eventData, {signature: 'invalid_signature'});
+
+			expect(response.status).toBe(401);
+		});
+
+		test('accepts webhook with valid signature', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'customer.created',
+				data: {object: {id: 'cus_test_123'}},
+			};
+
+			const {response} = await sendWebhook(eventData);
+
+			expect(response.status).toBe(200);
+		});
+
+		test('handles unhandled webhook event types gracefully', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'customer.created',
+				data: {object: {id: 'cus_test_unhandled'}},
+			};
+
+			const {response} = await sendWebhook(eventData);
+
+			expect(response.status).toBe(200);
+		});
+
+		test('handles unknown webhook event types gracefully', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'some.unknown.event',
+				data: {object: {id: 'unknown_123'}},
+			};
+
+			const {response} = await sendWebhook(eventData);
+
+			expect(response.status).toBe(200);
+		});
+
+		test('rejects webhook with tampered payload', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'checkout.session.completed',
+				data: {object: {id: 'cs_test_123'}},
+			};
+
+			const {payload, timestamp} = createMockWebhookPayload(eventData);
+			const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+			const tamperedPayload = payload.replace('cs_test_123', 'cs_test_tampered');
+
+			const result = await createBuilder(harness, '')
+				.post('/stripe/webhook')
+				.header('stripe-signature', signature)
+				.header('content-type', 'application/json')
+				.body(tamperedPayload)
+				.executeRaw();
+
+			expect(result.response.status).toBe(401);
+		});
+
+		test('rejects webhook with expired timestamp', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'checkout.session.completed',
+				data: {object: {id: 'cs_test_123'}},
+			};
+
+			const {payload} = createMockWebhookPayload(eventData);
+			const oldTimestamp = Math.floor(Date.now() / 1000) - 600;
+			const signature = createWebhookSignature(payload, oldTimestamp, Config.stripe.webhookSecret!);
+
+			const result = await createBuilder(harness, '')
+				.post('/stripe/webhook')
+				.header('stripe-signature', signature)
+				.header('content-type', 'application/json')
+				.body(payload)
+				.executeRaw();
+
+			expect(result.response.status).toBe(401);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookDispute.test.tsx

@@ -0,0 +1,377 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {mockStripeWebhookSecret, restoreStripeWebhookSecret} from '@fluxer/api/src/stripe/tests/StripeWebhookTestUtils';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {createBuilder, createBuilderWithoutAuth} from '@fluxer/api/src/test/TestRequestBuilder';
+import {PaymentRepository} from '@fluxer/api/src/user/repositories/PaymentRepository';
+import {UserRepository} from '@fluxer/api/src/user/repositories/UserRepository';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {DeletionReasons} from '@fluxer/constants/src/Core';
+import {UserFlags, UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+interface UserDataExistsResponse {
+	user_exists: boolean;
+	has_deleted_flag: boolean;
+	has_self_deleted_flag: boolean;
+	pending_deletion_at: string | null;
+	deletion_reason_code: string | null;
+	flags: string;
+}
+
+describe('Stripe Webhook Dispute Events', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		mockStripeWebhookSecret('whsec_test_dispute');
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		restoreStripeWebhookSecret();
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	async function sendWebhookExpectStripeError(eventData: StripeWebhookEventData): Promise<void> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		await createBuilder(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.expect(400, APIErrorCodes.STRIPE_ERROR)
+			.execute();
+	}
+
+	describe('charge.dispute.created', () => {
+		test('schedules account deletion on chargeback for direct purchase', async () => {
+			const purchaser = await createTestAccount(harness);
+			const paymentIntentId = 'pi_test_chargeback_123';
+			const paymentRepo = new PaymentRepository();
+
+			await paymentRepo.createPayment({
+				checkout_session_id: 'cs_test_chargeback',
+				user_id: createUserID(BigInt(purchaser.userId)),
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepo.updatePayment({
+				checkout_session_id: 'cs_test_chargeback',
+				payment_intent_id: paymentIntentId,
+			});
+
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.created',
+				data: {
+					object: {
+						id: 'dp_test_123',
+						payment_intent: paymentIntentId,
+						status: 'needs_response',
+					},
+				},
+			};
+
+			await sendWebhook(eventData);
+
+			const updatedUser = await createBuilderWithoutAuth<UserDataExistsResponse>(harness)
+				.get(`/test/users/${purchaser.userId}/data-exists`)
+				.execute();
+
+			expect(updatedUser.has_deleted_flag).toBe(true);
+			expect(updatedUser.deletion_reason_code).toBe(DeletionReasons.BILLING_DISPUTE_OR_ABUSE);
+			expect(updatedUser.pending_deletion_at).not.toBeNull();
+
+			const deletionDate = new Date(updatedUser.pending_deletion_at!);
+			const now = new Date();
+			const daysDifference = (deletionDate.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDifference).toBeGreaterThan(28);
+			expect(daysDifference).toBeLessThan(32);
+		});
+
+		test('revokes premium and schedules deletion for gift chargeback', async () => {
+			const purchaser = await createTestAccount(harness);
+			const redeemer = await createTestAccount(harness);
+			const paymentIntentId = 'pi_test_gift_chargeback_123';
+			const giftCode = 'GIFT_CHARGEBACK_TEST';
+			const userRepository = new UserRepository();
+			const paymentRepo = new PaymentRepository();
+
+			await userRepository.createGiftCode({
+				code: giftCode,
+				duration_months: 1,
+				created_at: new Date(),
+				created_by_user_id: createUserID(BigInt(purchaser.userId)),
+				redeemed_at: new Date(),
+				redeemed_by_user_id: createUserID(BigInt(redeemer.userId)),
+				stripe_payment_intent_id: paymentIntentId,
+				visionary_sequence_number: null,
+				checkout_session_id: null,
+				version: 1,
+			});
+
+			await paymentRepo.createPayment({
+				checkout_session_id: 'cs_test_gift_chargeback',
+				user_id: createUserID(BigInt(purchaser.userId)),
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: true,
+				created_at: new Date(),
+			});
+
+			await paymentRepo.updatePayment({
+				checkout_session_id: 'cs_test_gift_chargeback',
+				payment_intent_id: paymentIntentId,
+				gift_code: giftCode,
+			});
+
+			await createBuilder(harness, redeemer.token)
+				.post(`/test/users/${redeemer.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			const redeemerBeforeDispute = await createBuilder<{premium_type: number}>(harness, redeemer.token)
+				.get('/users/@me')
+				.execute();
+			expect(redeemerBeforeDispute.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.created',
+				data: {
+					object: {
+						id: 'dp_test_gift_123',
+						payment_intent: paymentIntentId,
+						status: 'needs_response',
+					},
+				},
+			};
+
+			await sendWebhook(eventData);
+
+			const redeemerAfterDispute = await createBuilder<{premium_type: number}>(harness, redeemer.token)
+				.get('/users/@me')
+				.execute();
+			expect(redeemerAfterDispute.premium_type).toBe(UserPremiumTypes.NONE);
+
+			const purchaserAfterDispute = await createBuilderWithoutAuth<UserDataExistsResponse>(harness)
+				.get(`/test/users/${purchaser.userId}/data-exists`)
+				.execute();
+
+			expect(purchaserAfterDispute.has_deleted_flag).toBe(true);
+			expect(purchaserAfterDispute.deletion_reason_code).toBe(DeletionReasons.BILLING_DISPUTE_OR_ABUSE);
+			expect(purchaserAfterDispute.pending_deletion_at).not.toBeNull();
+		});
+
+		test('handles dispute for payment intent not found gracefully', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.created',
+				data: {
+					object: {
+						id: 'dp_test_unknown',
+						payment_intent: 'pi_test_does_not_exist',
+						status: 'needs_response',
+					},
+				},
+			};
+
+			await sendWebhookExpectStripeError(eventData);
+		});
+	});
+
+	describe('charge.dispute.closed', () => {
+		test('unsuspends account when chargeback is won', async () => {
+			const purchaser = await createTestAccount(harness);
+			const paymentIntentId = 'pi_test_dispute_won_123';
+			const paymentRepo = new PaymentRepository();
+
+			await paymentRepo.createPayment({
+				checkout_session_id: 'cs_test_dispute_won',
+				user_id: createUserID(BigInt(purchaser.userId)),
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepo.updatePayment({
+				checkout_session_id: 'cs_test_dispute_won',
+				payment_intent_id: paymentIntentId,
+			});
+
+			await createBuilderWithoutAuth(harness)
+				.patch(`/test/users/${purchaser.userId}/flags`)
+				.body({flags: Number(UserFlags.DELETED)})
+				.execute();
+
+			const userRepository = new UserRepository();
+			const userId = createUserID(BigInt(purchaser.userId));
+			const user = await userRepository.findUnique(userId);
+			await userRepository.patchUpsert(
+				userId,
+				{
+					deletion_reason_code: DeletionReasons.BILLING_DISPUTE_OR_ABUSE,
+					pending_deletion_at: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+				},
+				user!.toRow(),
+			);
+
+			const userBeforeWin = await createBuilderWithoutAuth<UserDataExistsResponse>(harness)
+				.get(`/test/users/${purchaser.userId}/data-exists`)
+				.execute();
+			expect(userBeforeWin.has_deleted_flag).toBe(true);
+			expect(userBeforeWin.deletion_reason_code).toBe(DeletionReasons.BILLING_DISPUTE_OR_ABUSE);
+
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.closed',
+				data: {
+					object: {
+						id: 'dp_test_won',
+						payment_intent: paymentIntentId,
+						status: 'won',
+					},
+				},
+			};
+
+			await sendWebhook(eventData);
+
+			const userAfterWin = await createBuilderWithoutAuth<UserDataExistsResponse>(harness)
+				.get(`/test/users/${purchaser.userId}/data-exists`)
+				.execute();
+
+			expect(userAfterWin.has_deleted_flag).toBe(false);
+			expect(userAfterWin.deletion_reason_code).toBeNull();
+			expect(userAfterWin.pending_deletion_at).toBeNull();
+		});
+
+		test('does not unsuspend when chargeback is lost', async () => {
+			const purchaser = await createTestAccount(harness);
+			const paymentIntentId = 'pi_test_dispute_lost_123';
+			const paymentRepo = new PaymentRepository();
+
+			await paymentRepo.createPayment({
+				checkout_session_id: 'cs_test_dispute_lost',
+				user_id: createUserID(BigInt(purchaser.userId)),
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepo.updatePayment({
+				checkout_session_id: 'cs_test_dispute_lost',
+				payment_intent_id: paymentIntentId,
+			});
+
+			await createBuilderWithoutAuth(harness)
+				.patch(`/test/users/${purchaser.userId}/flags`)
+				.body({flags: Number(UserFlags.DELETED)})
+				.execute();
+
+			const userRepository = new UserRepository();
+			const userId = createUserID(BigInt(purchaser.userId));
+			const user = await userRepository.findUnique(userId);
+			await userRepository.patchUpsert(
+				userId,
+				{
+					deletion_reason_code: DeletionReasons.BILLING_DISPUTE_OR_ABUSE,
+					pending_deletion_at: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+				},
+				user!.toRow(),
+			);
+
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.closed',
+				data: {
+					object: {
+						id: 'dp_test_lost',
+						payment_intent: paymentIntentId,
+						status: 'lost',
+					},
+				},
+			};
+
+			await sendWebhook(eventData);
+
+			const userAfterLoss = await createBuilderWithoutAuth<UserDataExistsResponse>(harness)
+				.get(`/test/users/${purchaser.userId}/data-exists`)
+				.execute();
+
+			expect(userAfterLoss.has_deleted_flag).toBe(true);
+			expect(userAfterLoss.deletion_reason_code).toBe(DeletionReasons.BILLING_DISPUTE_OR_ABUSE);
+			expect(userAfterLoss.pending_deletion_at).not.toBeNull();
+		});
+
+		test('handles dispute closed for payment intent not found gracefully', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'charge.dispute.closed',
+				data: {
+					object: {
+						id: 'dp_test_unknown_closed',
+						payment_intent: 'pi_test_does_not_exist',
+						status: 'won',
+					},
+				},
+			};
+
+			await sendWebhookExpectStripeError(eventData);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookEdgeCases.test.tsx

@@ -0,0 +1,547 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {Config} from '@fluxer/api/src/Config';
+import {createGuild} from '@fluxer/api/src/guild/tests/GuildTestUtils';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('Stripe Webhook Edge Cases', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalVisionariesGuildId: string | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalVisionariesGuildId = Config.instance.visionariesGuildId ?? undefined;
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.instance.visionariesGuildId = originalVisionariesGuildId;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		const owner = await createTestAccount(harness);
+		const visionariesGuild = await createGuild(harness, owner.token, 'Visionaries Webhook Test Guild');
+		Config.instance.visionariesGuildId = visionariesGuild.id;
+	});
+
+	describe('Premium stacking - consecutive grants extending duration', () => {
+		test('stacks multiple monthly subscriptions end-to-end', async () => {
+			const account = await createTestAccount(harness);
+			const now = new Date();
+			const oneMonthLater = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: oneMonthLater.toISOString(),
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const firstExpiry = new Date(me1.premium_until!);
+
+			const twoMonthsLater = new Date(oneMonthLater.getTime() + 30 * 24 * 60 * 60 * 1000);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: twoMonthsLater.toISOString(),
+				})
+				.execute();
+
+			const me2 = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const secondExpiry = new Date(me2.premium_until!);
+
+			const daysDifference = (secondExpiry.getTime() - firstExpiry.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDifference).toBeGreaterThanOrEqual(28);
+			expect(daysDifference).toBeLessThanOrEqual(31);
+		});
+
+		test('stacks yearly subscription on top of monthly', async () => {
+			const account = await createTestAccount(harness);
+			const now = new Date();
+			const oneMonthLater = new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: oneMonthLater.toISOString(),
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const firstExpiry = new Date(me1.premium_until!);
+
+			const oneYearAfterFirst = new Date(firstExpiry.getTime() + 365 * 24 * 60 * 60 * 1000);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: oneYearAfterFirst.toISOString(),
+				})
+				.execute();
+
+			const me2 = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const secondExpiry = new Date(me2.premium_until!);
+
+			const daysDifference = (secondExpiry.getTime() - firstExpiry.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDifference).toBeGreaterThanOrEqual(360);
+			expect(daysDifference).toBeLessThanOrEqual(370);
+		});
+
+		test('stacks premium when current premium has already expired', async () => {
+			const account = await createTestAccount(harness);
+			const past = new Date(Date.now() - 10 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: past.toISOString(),
+				})
+				.execute();
+
+			const future = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: future.toISOString(),
+				})
+				.execute();
+
+			const me = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const expiry = new Date(me.premium_until!);
+			const now = new Date();
+
+			const daysDifference = (expiry.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDifference).toBeGreaterThanOrEqual(28);
+			expect(daysDifference).toBeLessThanOrEqual(31);
+		});
+
+		test('preserves premium_since on stacking', async () => {
+			const account = await createTestAccount(harness);
+			const originalSince = new Date('2024-01-01T00:00:00Z');
+			const oneMonthLater = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_since: originalSince.toISOString(),
+					premium_until: oneMonthLater.toISOString(),
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_since: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(me1.premium_since).toBe(originalSince.toISOString());
+
+			const twoMonthsLater = new Date(oneMonthLater.getTime() + 30 * 24 * 60 * 60 * 1000);
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: twoMonthsLater.toISOString(),
+				})
+				.execute();
+
+			const me2 = await createBuilder<{premium_since: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(me2.premium_since).toBe(originalSince.toISOString());
+		});
+	});
+
+	describe('Visionary slot management', () => {
+		test('multiple users can get consecutive visionary slots', async () => {
+			const account1 = await createTestAccount(harness);
+			const account2 = await createTestAccount(harness);
+			const account3 = await createTestAccount(harness);
+
+			await createBuilder(harness, account1.token)
+				.post(`/test/users/${account1.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 0,
+				})
+				.execute();
+
+			await createBuilder(harness, account2.token)
+				.post(`/test/users/${account2.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 1,
+				})
+				.execute();
+
+			await createBuilder(harness, account3.token)
+				.post(`/test/users/${account3.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 2,
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_lifetime_sequence: number | null}>(harness, account1.token)
+				.get('/users/@me')
+				.execute();
+			const me2 = await createBuilder<{premium_lifetime_sequence: number | null}>(harness, account2.token)
+				.get('/users/@me')
+				.execute();
+			const me3 = await createBuilder<{premium_lifetime_sequence: number | null}>(harness, account3.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(me1.premium_lifetime_sequence).toBe(0);
+			expect(me2.premium_lifetime_sequence).toBe(1);
+			expect(me3.premium_lifetime_sequence).toBe(2);
+		});
+	});
+
+	describe('Lifetime + subscription conflicts', () => {
+		test('purchasing lifetime when already have subscription clears subscription', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					stripe_subscription_id: 'sub_lifetime_cancel',
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(),
+					premium_billing_cycle: 'monthly',
+				})
+				.execute();
+
+			const meBefore = await createBuilder<{premium_type: number; premium_billing_cycle: string | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(meBefore.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(meBefore.premium_billing_cycle).toBe('monthly');
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 0,
+					stripe_subscription_id: null,
+					premium_billing_cycle: null,
+				})
+				.execute();
+
+			const meAfter = await createBuilder<{
+				premium_type: number;
+				premium_billing_cycle: string | null;
+				premium_lifetime_sequence: number | null;
+			}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(meAfter.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(meAfter.premium_billing_cycle).toBeNull();
+			expect(meAfter.premium_lifetime_sequence).toBe(0);
+		});
+
+		test('cannot redeem plutonium gift when already have visionary', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 5,
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/gifts/PLUTONIUMGIFT`)
+				.body({
+					duration_months: 1,
+					created_by_user_id: account.userId.toString(),
+				})
+				.execute();
+
+			await createBuilder(harness, account.token)
+				.post('/gifts/PLUTONIUMGIFT/redeem')
+				.expect(400, APIErrorCodes.CANNOT_REDEEM_PLUTONIUM_WITH_VISIONARY)
+				.execute();
+		});
+
+		test('visionary users retain lifetime status', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 10,
+				})
+				.execute();
+
+			const me1 = await createBuilder<{premium_type: number; premium_lifetime_sequence: number | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(me1.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(me1.premium_lifetime_sequence).toBe(10);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 10,
+				})
+				.execute();
+
+			const me2 = await createBuilder<{premium_type: number; premium_lifetime_sequence: number | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(me2.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(me2.premium_lifetime_sequence).toBe(10);
+		});
+
+		test('upgrading from subscription to lifetime changes premium type', async () => {
+			const account = await createTestAccount(harness);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+				})
+				.execute();
+
+			const meBefore = await createBuilder<{premium_type: number; premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(meBefore.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(meBefore.premium_until).not.toBeNull();
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.LIFETIME,
+					premium_lifetime_sequence: 15,
+					premium_until: null,
+				})
+				.execute();
+
+			const meAfter = await createBuilder<{
+				premium_type: number;
+				premium_until: string | null;
+				premium_lifetime_sequence: number | null;
+			}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			expect(meAfter.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(meAfter.premium_until).toBeNull();
+			expect(meAfter.premium_lifetime_sequence).toBe(15);
+		});
+	});
+
+	describe('Gift code redemption behavior', () => {
+		test('redeeming lifetime gift code grants visionary', async () => {
+			const gifter = await createTestAccount(harness);
+			const receiver = await createTestAccount(harness);
+
+			await createBuilder(harness, gifter.token)
+				.post('/test/gifts/LIFETIMEGIFT123')
+				.body({
+					duration_months: 0,
+					created_by_user_id: gifter.userId.toString(),
+					visionary_sequence_number: 0,
+				})
+				.execute();
+
+			const receiverBefore = await createBuilder<{premium_type: number}>(harness, receiver.token)
+				.get('/users/@me')
+				.execute();
+			expect(receiverBefore.premium_type).toBe(UserPremiumTypes.NONE);
+
+			await createBuilder(harness, receiver.token).post('/gifts/LIFETIMEGIFT123/redeem').expect(204).execute();
+
+			const receiverAfter = await createBuilder<{premium_type: number; premium_lifetime_sequence: number | null}>(
+				harness,
+				receiver.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(receiverAfter.premium_type).toBe(UserPremiumTypes.LIFETIME);
+			expect(receiverAfter.premium_lifetime_sequence).toBe(0);
+		});
+
+		test('redeeming 1-month gift code grants subscription premium', async () => {
+			const gifter = await createTestAccount(harness);
+			const receiver = await createTestAccount(harness);
+
+			await createBuilder(harness, gifter.token)
+				.post('/test/gifts/MONTHGIFT456')
+				.body({
+					duration_months: 1,
+					created_by_user_id: gifter.userId.toString(),
+				})
+				.execute();
+
+			await createBuilder(harness, receiver.token).post('/gifts/MONTHGIFT456/redeem').expect(204).execute();
+
+			const receiverAfter = await createBuilder<{premium_type: number; premium_until: string | null}>(
+				harness,
+				receiver.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(receiverAfter.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(receiverAfter.premium_until).not.toBeNull();
+
+			const premiumUntil = new Date(receiverAfter.premium_until!);
+			const now = new Date();
+			const daysDiff = (premiumUntil.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDiff).toBeGreaterThanOrEqual(27);
+			expect(daysDiff).toBeLessThanOrEqual(32);
+		});
+
+		test('redeeming 12-month gift code grants full year', async () => {
+			const gifter = await createTestAccount(harness);
+			const receiver = await createTestAccount(harness);
+
+			await createBuilder(harness, gifter.token)
+				.post('/test/gifts/YEARGIFT789')
+				.body({
+					duration_months: 12,
+					created_by_user_id: gifter.userId.toString(),
+				})
+				.execute();
+
+			await createBuilder(harness, receiver.token).post('/gifts/YEARGIFT789/redeem').expect(204).execute();
+
+			const receiverAfter = await createBuilder<{premium_type: number; premium_until: string | null}>(
+				harness,
+				receiver.token,
+			)
+				.get('/users/@me')
+				.execute();
+			expect(receiverAfter.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+
+			const premiumUntil = new Date(receiverAfter.premium_until!);
+			const now = new Date();
+			const daysDiff = (premiumUntil.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
+			expect(daysDiff).toBeGreaterThanOrEqual(360);
+			expect(daysDiff).toBeLessThanOrEqual(370);
+		});
+
+		test('gift codes can only be redeemed once', async () => {
+			const gifter = await createTestAccount(harness);
+			const receiver1 = await createTestAccount(harness);
+			const receiver2 = await createTestAccount(harness);
+
+			await createBuilder(harness, gifter.token)
+				.post('/test/gifts/ONCECODE')
+				.body({
+					duration_months: 1,
+					created_by_user_id: gifter.userId.toString(),
+				})
+				.execute();
+
+			await createBuilder(harness, receiver1.token).post('/gifts/ONCECODE/redeem').expect(204).execute();
+
+			await createBuilder(harness, receiver2.token)
+				.post('/gifts/ONCECODE/redeem')
+				.expect(400, APIErrorCodes.GIFT_CODE_ALREADY_REDEEMED)
+				.execute();
+		});
+	});
+
+	describe('Premium duration edge cases', () => {
+		test('premium_until clamped to maximum date', async () => {
+			const account = await createTestAccount(harness);
+			const farFuture = new Date('2099-12-31T23:59:59.999Z');
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: farFuture.toISOString(),
+				})
+				.execute();
+
+			const me = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			const premiumUntil = new Date(me.premium_until!);
+			expect(premiumUntil.getTime()).toBeLessThanOrEqual(farFuture.getTime());
+		});
+
+		test('stacking near maximum date stays clamped', async () => {
+			const account = await createTestAccount(harness);
+			const nearMax = new Date('2098-01-01T00:00:00.000Z');
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: nearMax.toISOString(),
+				})
+				.execute();
+
+			const farFuture = new Date('2099-12-31T23:59:59.999Z');
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: farFuture.toISOString(),
+				})
+				.execute();
+
+			const me = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			const premiumUntil = new Date(me.premium_until!);
+			expect(premiumUntil.toISOString()).toBe(farFuture.toISOString());
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookIdempotency.test.tsx

@@ -0,0 +1,356 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createHmac} from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {ProductType} from '@fluxer/api/src/stripe/ProductRegistry';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createCheckoutCompletedEvent,
+	createMockWebhookPayload,
+	createStripeApiHandlers,
+	createSubscriptionUpdatedEvent,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {server} from '@fluxer/api/src/test/msw/server';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {PaymentRepository} from '@fluxer/api/src/user/repositories/PaymentRepository';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, afterEach, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+const MOCK_PRICES = {
+	monthlyUsd: 'price_monthly_usd',
+};
+
+describe('Stripe Webhook Idempotency and Race Conditions', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let stripeHandlers: ReturnType<typeof createStripeApiHandlers>;
+	let originalWebhookSecret: string | undefined;
+	let originalPrices: typeof Config.stripe.prices | undefined;
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		originalPrices = Config.stripe.prices;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+		Config.stripe.prices = MOCK_PRICES;
+
+		stripeHandlers = createStripeApiHandlers();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		stripeHandlers.reset();
+	});
+
+	afterEach(() => {
+		server.resetHandlers();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+		Config.stripe.prices = originalPrices;
+	});
+
+	async function createSubscriptionPayment(params: {
+		checkoutSessionId: string;
+		userId: string;
+		subscriptionId: string;
+		customerId: string;
+		status: 'pending' | 'completed';
+	}): Promise<void> {
+		const paymentRepository = new PaymentRepository();
+
+		await paymentRepository.createPayment({
+			checkout_session_id: params.checkoutSessionId,
+			user_id: createUserID(BigInt(params.userId)),
+			price_id: MOCK_PRICES.monthlyUsd,
+			product_type: ProductType.MONTHLY_SUBSCRIPTION,
+			status: params.status,
+			is_gift: false,
+			created_at: new Date(),
+		});
+
+		if (params.status === 'completed') {
+			await paymentRepository.updatePayment({
+				checkout_session_id: params.checkoutSessionId,
+				subscription_id: params.subscriptionId,
+				stripe_customer_id: params.customerId,
+				status: 'completed',
+			});
+		}
+	}
+
+	describe('idempotency', () => {
+		test('handles duplicate webhook events idempotently', async () => {
+			const account = await createTestAccount(harness);
+
+			const subscriptionId = `sub_test_${Date.now()}`;
+			const customerId = `cus_test_${Date.now()}`;
+			const checkoutSessionId = `cs_test_${Date.now()}`;
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+					stripe_subscription_id: subscriptionId,
+				})
+				.execute();
+
+			await createSubscriptionPayment({
+				checkoutSessionId,
+				userId: account.userId,
+				subscriptionId,
+				customerId,
+				status: 'completed',
+			});
+
+			const eventData1 = {
+				...createSubscriptionUpdatedEvent({
+					subscriptionId,
+					customerId,
+					status: 'active',
+				}),
+				id: 'evt_same_123',
+			};
+
+			const response1 = await sendWebhook(eventData1);
+			expect(response1.received).toBe(true);
+
+			const userAfterFirst = await createBuilder<{premium_type: number; premium_until: string | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+
+			expect(userAfterFirst.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+
+			const response2 = await sendWebhook(eventData1);
+			expect(response2.received).toBe(true);
+
+			const userAfterSecond = await createBuilder<{premium_type: number; premium_until: string | null}>(
+				harness,
+				account.token,
+			)
+				.get('/users/@me')
+				.execute();
+
+			expect(userAfterSecond.premium_type).toBe(userAfterFirst.premium_type);
+			expect(userAfterSecond.premium_until).toBe(userAfterFirst.premium_until);
+		});
+
+		test('prevents concurrent webhooks from processing same subscription update', async () => {
+			const account = await createTestAccount(harness);
+
+			const subscriptionId = `sub_test_${Date.now()}`;
+			const customerId = `cus_test_${Date.now()}`;
+			const checkoutSessionId = `cs_test_${Date.now()}`;
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+					stripe_subscription_id: subscriptionId,
+				})
+				.execute();
+
+			await createSubscriptionPayment({
+				checkoutSessionId,
+				userId: account.userId,
+				subscriptionId,
+				customerId,
+				status: 'completed',
+			});
+
+			const eventData = {
+				...createSubscriptionUpdatedEvent({
+					subscriptionId,
+					customerId,
+					status: 'active',
+				}),
+				id: 'evt_concurrent_123',
+			};
+
+			const [response1, response2] = await Promise.all([sendWebhook(eventData), sendWebhook(eventData)]);
+
+			expect(response1.received).toBe(true);
+			expect(response2.received).toBe(true);
+
+			const userAfter = await createBuilder<{premium_type: number}>(harness, account.token).get('/users/@me').execute();
+
+			expect(userAfter.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+		});
+	});
+
+	describe('race condition fixes', () => {
+		test('preserves higher premiumUntil in concurrent subscription updates', async () => {
+			const account = await createTestAccount(harness);
+
+			const subscriptionId = `sub_test_${Date.now()}`;
+			const checkoutSessionId = `cs_test_${Date.now()}`;
+			const customerId = `cus_test_${Date.now()}`;
+
+			const futureDate = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000);
+			const nearerTimestamp = Math.floor((Date.now() + 30 * 24 * 60 * 60 * 1000) / 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: futureDate.toISOString(),
+					stripe_subscription_id: subscriptionId,
+				})
+				.execute();
+
+			await createSubscriptionPayment({
+				checkoutSessionId,
+				userId: account.userId,
+				subscriptionId,
+				customerId,
+				status: 'pending',
+			});
+
+			const checkoutEvent = {
+				...createCheckoutCompletedEvent({
+					sessionId: checkoutSessionId,
+					subscriptionId,
+					customerId,
+					metadata: {},
+				}),
+				id: 'evt_checkout_123',
+			};
+
+			await sendWebhook(checkoutEvent);
+
+			const eventData = createSubscriptionUpdatedEvent({
+				subscriptionId,
+				customerId,
+			});
+			eventData.data.object.items = {
+				data: [{current_period_end: nearerTimestamp}],
+			};
+
+			const subscriptionEvent = {
+				...eventData,
+				id: 'evt_preserve_123',
+			};
+
+			const response = await sendWebhook(subscriptionEvent);
+			expect(response.received).toBe(true);
+
+			const userAfter = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			if (userAfter.premium_until) {
+				const premiumUntilAfter = new Date(userAfter.premium_until);
+				expect(premiumUntilAfter.getTime()).toBeGreaterThanOrEqual(futureDate.getTime() - 1000);
+			}
+		});
+
+		test('handles concurrent subscription update webhooks', async () => {
+			const account = await createTestAccount(harness);
+
+			const subscriptionId = `sub_test_${Date.now()}`;
+			const checkoutSessionId = `cs_test_${Date.now()}`;
+			const customerId = `cus_test_${Date.now()}`;
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+					stripe_subscription_id: subscriptionId,
+				})
+				.execute();
+
+			await createSubscriptionPayment({
+				checkoutSessionId,
+				userId: account.userId,
+				subscriptionId,
+				customerId,
+				status: 'pending',
+			});
+
+			const checkoutEvent = {
+				...createCheckoutCompletedEvent({
+					sessionId: checkoutSessionId,
+					subscriptionId,
+					customerId,
+					metadata: {},
+				}),
+				id: 'evt_checkout_concurrent',
+			};
+
+			await sendWebhook(checkoutEvent);
+
+			const eventData1 = {
+				...createSubscriptionUpdatedEvent({
+					subscriptionId,
+					customerId,
+					status: 'active',
+				}),
+				id: 'evt_race_1',
+			};
+			const eventData2 = {
+				...createSubscriptionUpdatedEvent({
+					subscriptionId,
+					customerId,
+					status: 'active',
+				}),
+				id: 'evt_race_2',
+			};
+
+			const [response1, response2] = await Promise.all([sendWebhook(eventData1), sendWebhook(eventData2)]);
+
+			expect(response1.received).toBe(true);
+			expect(response2.received).toBe(true);
+
+			const userAfter = await createBuilder<{premium_type: number}>(harness, account.token).get('/users/@me').execute();
+
+			expect(userAfter.premium_type).toBeGreaterThan(UserPremiumTypes.NONE);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookInvoice.test.tsx

@@ -0,0 +1,344 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {ProductType} from '@fluxer/api/src/stripe/ProductRegistry';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+const MOCK_PRICES = {
+	monthlyUsd: 'price_monthly_usd',
+	monthlyEur: 'price_monthly_eur',
+	yearlyUsd: 'price_yearly_usd',
+	yearlyEur: 'price_yearly_eur',
+	visionaryUsd: 'price_visionary_usd',
+	visionaryEur: 'price_visionary_eur',
+	giftVisionaryUsd: 'price_gift_visionary_usd',
+	giftVisionaryEur: 'price_gift_visionary_eur',
+	gift1MonthUsd: 'price_gift_1_month_usd',
+	gift1MonthEur: 'price_gift_1_month_eur',
+	gift1YearUsd: 'price_gift_1_year_usd',
+	gift1YearEur: 'price_gift_1_year_eur',
+};
+
+describe('Stripe Webhook - Invoice Events', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalWebhookSecret: string | undefined;
+	let originalPrices: typeof Config.stripe.prices | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		originalPrices = Config.stripe.prices;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+		Config.stripe.prices = MOCK_PRICES;
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+		Config.stripe.prices = originalPrices;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	async function sendWebhookExpectStripeError(eventData: StripeWebhookEventData): Promise<void> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		await createBuilder(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.expect(400, APIErrorCodes.STRIPE_ERROR)
+			.execute();
+	}
+
+	async function createPaymentRecord(params: {
+		userId: string;
+		subscriptionId: string;
+		priceId: string;
+		productType: string;
+	}): Promise<void> {
+		const {userId, subscriptionId, priceId, productType} = params;
+		const checkoutSessionId = `cs_test_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+
+		const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+		const paymentRepo = new PaymentRepository();
+
+		await paymentRepo.createPayment({
+			checkout_session_id: checkoutSessionId,
+			user_id: createUserID(BigInt(userId)),
+			price_id: priceId,
+			product_type: productType,
+			status: 'complete',
+			is_gift: false,
+			created_at: new Date(),
+		});
+
+		await paymentRepo.updatePayment({
+			checkout_session_id: checkoutSessionId,
+			subscription_id: subscriptionId,
+			stripe_customer_id: `cus_test_${Date.now()}`,
+			payment_intent_id: `pi_test_${Date.now()}`,
+			amount_cents: 2500,
+			currency: 'usd',
+			completed_at: new Date(),
+		});
+	}
+
+	describe('invoice.payment_succeeded', () => {
+		test('processes recurring subscription payment successfully', async () => {
+			const account = await createTestAccount(harness);
+			const subscriptionId = `sub_test_${Date.now()}`;
+
+			await createPaymentRecord({
+				userId: account.userId,
+				subscriptionId,
+				priceId: MOCK_PRICES.monthlyUsd,
+				productType: ProductType.MONTHLY_SUBSCRIPTION,
+			});
+
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'subscription_cycle',
+						subscription: subscriptionId,
+					},
+				},
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const user = await createBuilder<{
+				premium_type: number | null;
+				premium_until: string | null;
+			}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(user.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(user.premium_until).not.toBeNull();
+
+			const premiumUntil = new Date(user.premium_until!);
+			const now = new Date();
+			const daysDiff = (premiumUntil.getTime() - now.getTime()) / (1000 * 60 * 60 * 24);
+
+			expect(daysDiff).toBeGreaterThanOrEqual(27);
+			expect(daysDiff).toBeLessThanOrEqual(31);
+		});
+
+		test('skips first invoice for new subscription', async () => {
+			const account = await createTestAccount(harness);
+			const subscriptionId = `sub_test_${Date.now()}`;
+
+			await createPaymentRecord({
+				userId: account.userId,
+				subscriptionId,
+				priceId: MOCK_PRICES.monthlyUsd,
+				productType: ProductType.MONTHLY_SUBSCRIPTION,
+			});
+
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'subscription_create',
+						subscription: subscriptionId,
+					},
+				},
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const user = await createBuilder<{
+				premium_type: number;
+				premium_until: string | null;
+			}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(user.premium_type).toBe(0);
+			expect(user.premium_until).toBeNull();
+		});
+
+		test('skips manual invoice payments with no subscription context', async () => {
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'manual',
+						collection_method: 'send_invoice',
+					},
+				},
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+		});
+
+		test('handles missing subscription info gracefully', async () => {
+			const subscriptionId = `sub_test_nonexistent_${Date.now()}`;
+
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'subscription_cycle',
+						subscription: subscriptionId,
+					},
+				},
+			};
+
+			await sendWebhookExpectStripeError(eventData);
+		});
+
+		test('processes yearly subscription renewal correctly', async () => {
+			const account = await createTestAccount(harness);
+			const subscriptionId = `sub_test_${Date.now()}`;
+
+			await createPaymentRecord({
+				userId: account.userId,
+				subscriptionId,
+				priceId: MOCK_PRICES.yearlyUsd,
+				productType: ProductType.YEARLY_SUBSCRIPTION,
+			});
+
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'subscription_cycle',
+						subscription: subscriptionId,
+					},
+				},
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const user = await createBuilder<{
+				premium_type: number | null;
+				premium_until: string | null;
+			}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+
+			expect(user.premium_type).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(user.premium_until).not.toBeNull();
+
+			const premiumUntil = new Date(user.premium_until!);
+			const now = new Date();
+			const daysDiff = (premiumUntil.getTime() - now.getTime()) / (1000 * 60 * 60 * 24);
+
+			expect(daysDiff).toBeGreaterThanOrEqual(358);
+			expect(daysDiff).toBeLessThanOrEqual(370);
+		});
+
+		test('stacks renewal on top of existing premium time', async () => {
+			const account = await createTestAccount(harness);
+			const subscriptionId = `sub_test_${Date.now()}`;
+
+			const oneMonthLater = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+
+			await createBuilder(harness, account.token)
+				.post(`/test/users/${account.userId}/premium`)
+				.body({
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: oneMonthLater.toISOString(),
+					stripe_subscription_id: subscriptionId,
+				})
+				.execute();
+
+			await createPaymentRecord({
+				userId: account.userId,
+				subscriptionId,
+				priceId: MOCK_PRICES.monthlyUsd,
+				productType: ProductType.MONTHLY_SUBSCRIPTION,
+			});
+
+			const userBefore = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const beforeExpiry = new Date(userBefore.premium_until!);
+
+			const eventData: StripeWebhookEventData = {
+				type: 'invoice.payment_succeeded',
+				data: {
+					object: {
+						id: `in_test_${Date.now()}`,
+						billing_reason: 'subscription_cycle',
+						subscription: subscriptionId,
+					},
+				},
+			};
+
+			await sendWebhook(eventData);
+
+			const userAfter = await createBuilder<{premium_until: string | null}>(harness, account.token)
+				.get('/users/@me')
+				.execute();
+			const afterExpiry = new Date(userAfter.premium_until!);
+
+			const daysDifference = (afterExpiry.getTime() - beforeExpiry.getTime()) / (1000 * 60 * 60 * 24);
+
+			expect(daysDifference).toBeGreaterThanOrEqual(27);
+			expect(daysDifference).toBeLessThanOrEqual(31);
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookRefund.test.tsx

@@ -0,0 +1,178 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {UserFlags} from '@fluxer/constants/src/UserConstants';
+import {afterAll, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+describe('Stripe Webhook Refund', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let originalWebhookSecret: string | undefined;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	describe('charge.refunded', () => {
+		test('revokes premium and records first refund', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const {UserRepository} = await import('@fluxer/api/src/user/repositories/UserRepository');
+			const paymentRepository = new PaymentRepository();
+			const userRepository = new UserRepository();
+
+			const paymentIntentId = 'pi_test_refund_first_123';
+			const checkoutSessionId = 'cs_test_refund_first_123';
+			await paymentRepository.createPayment({
+				checkout_session_id: checkoutSessionId,
+				user_id: userId,
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: checkoutSessionId,
+				payment_intent_id: paymentIntentId,
+				completed_at: new Date(),
+			});
+
+			await sendWebhook({
+				type: 'charge.refunded',
+				data: {
+					object: {
+						id: 'ch_test_refund_123',
+						payment_intent: paymentIntentId,
+						amount_refunded: 2500,
+					},
+				},
+			});
+
+			const updatedUser = await userRepository.findUnique(userId);
+			expect(updatedUser).not.toBeNull();
+			expect(updatedUser!.firstRefundAt).not.toBeNull();
+
+			const updatedPayment = await userRepository.getPaymentByPaymentIntent(paymentIntentId);
+			expect(updatedPayment).not.toBeNull();
+			expect(updatedPayment!.status).toBe('refunded');
+		});
+
+		test('applies permanent purchase block on second refund', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+
+			const {UserRepository} = await import('@fluxer/api/src/user/repositories/UserRepository');
+			const userRepository = new UserRepository();
+
+			const firstRefundDate = new Date('2024-01-01');
+			await userRepository.patchUpsert(
+				userId,
+				{
+					first_refund_at: firstRefundDate,
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const {PaymentRepository} = await import('@fluxer/api/src/user/repositories/PaymentRepository');
+			const paymentRepository = new PaymentRepository();
+
+			const paymentIntentId = 'pi_test_refund_second_456';
+			const checkoutSessionId = 'cs_test_refund_second_456';
+			await paymentRepository.createPayment({
+				checkout_session_id: checkoutSessionId,
+				user_id: userId,
+				price_id: 'price_test_monthly',
+				product_type: 'monthly_subscription',
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: checkoutSessionId,
+				payment_intent_id: paymentIntentId,
+				completed_at: new Date(),
+			});
+
+			await sendWebhook({
+				type: 'charge.refunded',
+				data: {
+					object: {
+						id: 'ch_test_refund_456',
+						payment_intent: paymentIntentId,
+						amount_refunded: 2500,
+					},
+				},
+			});
+
+			const updatedUser = await userRepository.findUnique(userId);
+			expect(updatedUser).not.toBeNull();
+			expect(updatedUser!.firstRefundAt).toEqual(firstRefundDate);
+			expect(updatedUser!.flags & UserFlags.PREMIUM_PURCHASE_DISABLED).toBe(
+				BigInt(UserFlags.PREMIUM_PURCHASE_DISABLED),
+			);
+
+			const updatedPayment = await userRepository.getPaymentByPaymentIntent(paymentIntentId);
+			expect(updatedPayment).not.toBeNull();
+			expect(updatedPayment!.status).toBe('refunded');
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookSubscription.test.tsx

@@ -0,0 +1,418 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import crypto from 'node:crypto';
+import {createTestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import {ProductType} from '@fluxer/api/src/stripe/ProductRegistry';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	createStripeApiHandlers,
+	createSubscriptionDeletedEvent,
+	createSubscriptionUpdatedEvent,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {server} from '@fluxer/api/src/test/msw/server';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {PaymentRepository} from '@fluxer/api/src/user/repositories/PaymentRepository';
+import {UserRepository} from '@fluxer/api/src/user/repositories/UserRepository';
+import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
+import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
+import {afterAll, afterEach, beforeAll, beforeEach, describe, expect, test} from 'vitest';
+
+const MOCK_PRICES = {
+	monthlyUsd: 'price_monthly_usd',
+};
+
+describe('Stripe Webhook Subscription Lifecycle', () => {
+	let harness: Awaited<ReturnType<typeof createApiTestHarness>>;
+	let stripeHandlers: ReturnType<typeof createStripeApiHandlers>;
+	let originalWebhookSecret: string | undefined;
+	let originalPrices: typeof Config.stripe.prices | undefined;
+	let paymentRepository: PaymentRepository;
+	let userRepository: UserRepository;
+
+	beforeAll(async () => {
+		harness = await createApiTestHarness();
+		originalWebhookSecret = Config.stripe.webhookSecret;
+		originalPrices = Config.stripe.prices;
+		Config.stripe.webhookSecret = 'whsec_test_secret';
+		Config.stripe.prices = MOCK_PRICES;
+
+		stripeHandlers = createStripeApiHandlers();
+		server.use(...stripeHandlers.handlers);
+
+		paymentRepository = new PaymentRepository();
+		userRepository = new UserRepository();
+	});
+
+	afterAll(async () => {
+		await harness.shutdown();
+		Config.stripe.webhookSecret = originalWebhookSecret;
+		Config.stripe.prices = originalPrices;
+	});
+
+	beforeEach(async () => {
+		await harness.resetData();
+		stripeHandlers.reset();
+	});
+
+	afterEach(() => {
+		server.resetHandlers();
+		server.use(...stripeHandlers.handlers);
+	});
+
+	function createWebhookSignature(payload: string, timestamp: number, secret: string): string {
+		const signedPayload = `${timestamp}.${payload}`;
+		const signature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
+		return `t=${timestamp},v1=${signature}`;
+	}
+
+	async function sendWebhook(eventData: StripeWebhookEventData): Promise<{received: boolean}> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		return createBuilder<{received: boolean}>(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.execute();
+	}
+
+	async function sendWebhookExpectStripeError(eventData: StripeWebhookEventData): Promise<void> {
+		const {payload, timestamp} = createMockWebhookPayload(eventData);
+		const signature = createWebhookSignature(payload, timestamp, Config.stripe.webhookSecret!);
+
+		await createBuilder(harness, '')
+			.post('/stripe/webhook')
+			.header('stripe-signature', signature)
+			.header('content-type', 'application/json')
+			.body(payload)
+			.expect(400, APIErrorCodes.STRIPE_ERROR)
+			.execute();
+	}
+
+	describe('customer.subscription.updated', () => {
+		test('updates subscription cancellation status when cancel_at_period_end is true', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+			const subscriptionId = 'sub_test_monthly';
+			const sessionId = `cs_test_cancel_${Date.now()}`;
+			const cancelAt = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
+
+			await paymentRepository.createPayment({
+				checkout_session_id: sessionId,
+				user_id: userId,
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: sessionId,
+				subscription_id: subscriptionId,
+				stripe_customer_id: 'cus_test_1',
+				status: 'completed',
+			});
+
+			await userRepository.patchUpsert(
+				userId,
+				{
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					stripe_subscription_id: subscriptionId,
+					stripe_customer_id: 'cus_test_1',
+					premium_since: new Date(),
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const eventData = createSubscriptionUpdatedEvent({
+				subscriptionId,
+				cancelAtPeriodEnd: true,
+			});
+			eventData.data.object.cancel_at = cancelAt;
+			eventData.data.object.items = {
+				data: [{current_period_end: cancelAt}],
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const response = await harness.requestJson({
+				path: '/users/@me',
+				method: 'GET',
+				headers: {authorization: account.token},
+			});
+			const user = (await response.json()) as {premium_will_cancel: boolean; premium_until: string | null};
+
+			expect(user.premium_will_cancel).toBe(true);
+			expect(user.premium_until).not.toBeNull();
+		});
+
+		test('preserves gifted extension when updating subscription', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+			const subscriptionId = 'sub_test_gifted';
+			const sessionId = `cs_test_gifted_${Date.now()}`;
+			const futureDate = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000);
+			const currentPeriodEnd = Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60;
+
+			await paymentRepository.createPayment({
+				checkout_session_id: sessionId,
+				user_id: userId,
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: sessionId,
+				subscription_id: subscriptionId,
+				stripe_customer_id: 'cus_test_1',
+				status: 'completed',
+			});
+
+			await userRepository.patchUpsert(
+				userId,
+				{
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: futureDate,
+					stripe_subscription_id: subscriptionId,
+					stripe_customer_id: 'cus_test_1',
+					premium_since: new Date(),
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const eventData = createSubscriptionUpdatedEvent({
+				subscriptionId,
+				cancelAtPeriodEnd: false,
+			});
+			eventData.data.object.cancel_at = null;
+			eventData.data.object.items = {
+				data: [{current_period_end: currentPeriodEnd}],
+			};
+
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const response = await harness.requestJson({
+				path: '/users/@me',
+				method: 'GET',
+				headers: {authorization: account.token},
+			});
+			const user = (await response.json()) as {premium_will_cancel: boolean; premium_until: string | null};
+
+			expect(user.premium_will_cancel).toBe(false);
+			expect(user.premium_until).not.toBeNull();
+			const premiumUntil = new Date(user.premium_until!);
+			expect(premiumUntil.getTime()).toBeGreaterThan(new Date(currentPeriodEnd * 1000).getTime());
+		});
+
+		test('does not clear premium when period end is missing', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+			const subscriptionId = 'sub_test_missing_period';
+			const sessionId = `cs_test_missing_period_${Date.now()}`;
+			const futureDate = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000);
+
+			await paymentRepository.createPayment({
+				checkout_session_id: sessionId,
+				user_id: userId,
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: sessionId,
+				subscription_id: subscriptionId,
+				stripe_customer_id: 'cus_test_1',
+				status: 'completed',
+			});
+
+			await userRepository.patchUpsert(
+				userId,
+				{
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					premium_until: futureDate,
+					stripe_subscription_id: subscriptionId,
+					stripe_customer_id: 'cus_test_1',
+					premium_since: new Date(),
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const eventData = createSubscriptionUpdatedEvent({
+				subscriptionId,
+				cancelAtPeriodEnd: false,
+			});
+			eventData.data.object.items = {data: []};
+
+			await sendWebhookExpectStripeError(eventData);
+
+			const response = await harness.requestJson({
+				path: '/users/@me',
+				method: 'GET',
+				headers: {authorization: account.token},
+			});
+			const user = (await response.json()) as {premium_until: string | null};
+
+			expect(user.premium_until).not.toBeNull();
+			const premiumUntil = new Date(user.premium_until!);
+			expect(premiumUntil.getTime()).toBeGreaterThanOrEqual(futureDate.getTime() - 1000);
+		});
+	});
+
+	describe('customer.subscription.deleted', () => {
+		test('removes premium for non-lifetime users on subscription deletion', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+			const subscriptionId = 'sub_test_to_delete';
+			const sessionId = `cs_test_delete_${Date.now()}`;
+
+			await paymentRepository.createPayment({
+				checkout_session_id: sessionId,
+				user_id: userId,
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: sessionId,
+				subscription_id: subscriptionId,
+				stripe_customer_id: 'cus_test_1',
+				status: 'completed',
+			});
+
+			await userRepository.patchUpsert(
+				userId,
+				{
+					premium_type: UserPremiumTypes.SUBSCRIPTION,
+					stripe_subscription_id: subscriptionId,
+					stripe_customer_id: 'cus_test_1',
+					premium_since: new Date(),
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const beforeUser = await userRepository.findUnique(userId);
+			expect(beforeUser?.premiumType).toBe(UserPremiumTypes.SUBSCRIPTION);
+			expect(beforeUser?.stripeSubscriptionId).toBe(subscriptionId);
+
+			const eventData = createSubscriptionDeletedEvent({subscriptionId});
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const afterUser = await userRepository.findUnique(userId);
+			expect(afterUser?.premiumType).toBe(UserPremiumTypes.NONE);
+			expect(afterUser?.premiumUntil).toBeNull();
+			expect(afterUser?.stripeSubscriptionId).toBeNull();
+		});
+
+		test('preserves lifetime premium on subscription deletion', async () => {
+			const account = await createTestAccount(harness);
+			const userId = createUserID(BigInt(account.userId));
+			const subscriptionId = 'sub_test_lifetime_user';
+			const sessionId = `cs_test_lifetime_${Date.now()}`;
+
+			await paymentRepository.createPayment({
+				checkout_session_id: sessionId,
+				user_id: userId,
+				price_id: MOCK_PRICES.monthlyUsd,
+				product_type: ProductType.MONTHLY_SUBSCRIPTION,
+				status: 'completed',
+				is_gift: false,
+				created_at: new Date(),
+			});
+
+			await paymentRepository.updatePayment({
+				checkout_session_id: sessionId,
+				subscription_id: subscriptionId,
+				stripe_customer_id: 'cus_test_1',
+				status: 'completed',
+			});
+
+			await userRepository.patchUpsert(
+				userId,
+				{
+					premium_type: UserPremiumTypes.LIFETIME,
+					stripe_subscription_id: subscriptionId,
+					stripe_customer_id: 'cus_test_1',
+					premium_since: new Date(),
+				},
+				(await userRepository.findUnique(userId))!.toRow(),
+			);
+
+			const beforeUser = await userRepository.findUnique(userId);
+			expect(beforeUser?.premiumType).toBe(UserPremiumTypes.LIFETIME);
+
+			const eventData = createSubscriptionDeletedEvent({subscriptionId});
+			const result = await sendWebhook(eventData);
+			expect(result.received).toBe(true);
+
+			const afterUser = await userRepository.findUnique(userId);
+			expect(afterUser?.premiumType).toBe(UserPremiumTypes.LIFETIME);
+			expect(afterUser?.stripeSubscriptionId).toBeNull();
+		});
+
+		test('processes donation subscription deletion', async () => {
+			const subscriptionId = 'sub_donor_delete_test';
+			const donorEmail = 'donor-delete@example.com';
+			const {DonationRepository} = await import('@fluxer/api/src/donation/DonationRepository');
+			const donationRepository = new DonationRepository();
+
+			await donationRepository.createDonor({
+				email: donorEmail,
+				stripeCustomerId: 'cus_donor_delete_123',
+				businessName: null,
+				taxId: null,
+				taxIdType: null,
+				stripeSubscriptionId: subscriptionId,
+				subscriptionAmountCents: 2500,
+				subscriptionCurrency: 'usd',
+				subscriptionInterval: 'month',
+				subscriptionCurrentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+			});
+
+			const donorBefore = await donationRepository.findDonorByEmail(donorEmail);
+			expect(donorBefore).not.toBeNull();
+			expect(donorBefore?.stripeSubscriptionId).toBe(subscriptionId);
+
+			const deleteEvent = createSubscriptionDeletedEvent({subscriptionId});
+			const deleteResult = await sendWebhook(deleteEvent);
+			expect(deleteResult.received).toBe(true);
+
+			const donorAfter = await donationRepository.findDonorByEmail(donorEmail);
+			expect(donorAfter?.stripeSubscriptionId).toBeNull();
+		});
+	});
+});

packages/api/src/stripe/tests/StripeWebhookTestUtils.tsx

@@ -0,0 +1,252 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {createTestAccount, type TestAccount} from '@fluxer/api/src/auth/tests/AuthTestUtils';
+import {createUserID, type UserID} from '@fluxer/api/src/BrandedTypes';
+import {Config} from '@fluxer/api/src/Config';
+import type {StripeWebhookService} from '@fluxer/api/src/stripe/services/StripeWebhookService';
+import type {ApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {createApiTestHarness} from '@fluxer/api/src/test/ApiTestHarness';
+import {
+	createMockWebhookPayload,
+	createStripeApiHandlers,
+	type StripeApiMockConfig,
+	type StripeApiMockSpies,
+	type StripeWebhookEventData,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';
+import {createBuilder} from '@fluxer/api/src/test/TestRequestBuilder';
+import {setupServer} from 'msw/node';
+import {afterAll, afterEach, beforeAll} from 'vitest';
+
+export interface WebhookTestHarness {
+	harness: ApiTestHarness;
+	stripeHandlers: {
+		spies: StripeApiMockSpies;
+		reset: () => void;
+	};
+	mswServer: ReturnType<typeof setupServer>;
+}
+
+export async function createWebhookTestHarness(config?: StripeApiMockConfig): Promise<WebhookTestHarness> {
+	const harness = await createApiTestHarness();
+
+	const stripeHandlers = createStripeApiHandlers(config);
+	const mswServer = setupServer(...stripeHandlers.handlers);
+
+	return {
+		harness,
+		stripeHandlers: {
+			spies: stripeHandlers.spies,
+			reset: stripeHandlers.reset,
+		},
+		mswServer,
+	};
+}
+
+export function setupWebhookTestServer(testHarness: WebhookTestHarness): void {
+	beforeAll(() => {
+		testHarness.mswServer.listen({onUnhandledRequest: 'bypass'});
+	});
+
+	afterEach(() => {
+		testHarness.stripeHandlers.reset();
+		testHarness.mswServer.resetHandlers();
+	});
+
+	afterAll(() => {
+		testHarness.mswServer.close();
+	});
+}
+
+export async function sendWebhook(service: StripeWebhookService, eventData: StripeWebhookEventData): Promise<void> {
+	const {payload, timestamp} = createMockWebhookPayload(eventData);
+
+	const signature = `t=${timestamp},v1=test_signature_${Date.now()}`;
+
+	await service.handleWebhook({
+		body: payload,
+		signature,
+	});
+}
+
+export async function createTestUserWithPremium(
+	harness: ApiTestHarness,
+	premiumType: number,
+	options?: {
+		email?: string;
+		username?: string;
+		premiumUntil?: Date;
+		stripeCustomerId?: string;
+		stripeSubscriptionId?: string;
+	},
+): Promise<TestAccount> {
+	const account = await createTestAccount(harness, {
+		email: options?.email,
+		username: options?.username,
+	});
+
+	await createBuilder(harness, account.token)
+		.patch(`/test/users/${account.userId}/premium`)
+		.body({
+			premium_type: premiumType,
+			premium_until: options?.premiumUntil?.toISOString() || null,
+			stripe_customer_id: options?.stripeCustomerId || null,
+			stripe_subscription_id: options?.stripeSubscriptionId || null,
+		})
+		.execute();
+
+	return account;
+}
+
+export async function createTestPayment(
+	harness: ApiTestHarness,
+	userId: UserID,
+	sessionId: string,
+	options?: {
+		priceId?: string;
+		productType?: string;
+		status?: string;
+		isGift?: boolean;
+		giftCode?: string;
+		stripeCustomerId?: string;
+		paymentIntentId?: string;
+		subscriptionId?: string;
+	},
+): Promise<void> {
+	await createBuilder(harness, '')
+		.post('/test/payments')
+		.body({
+			checkout_session_id: sessionId,
+			user_id: userId,
+			price_id: options?.priceId || 'price_test_monthly',
+			product_type: options?.productType || 'monthly_subscription',
+			status: options?.status || 'pending',
+			is_gift: options?.isGift || false,
+			gift_code: options?.giftCode || null,
+			stripe_customer_id: options?.stripeCustomerId || null,
+			payment_intent_id: options?.paymentIntentId || null,
+			subscription_id: options?.subscriptionId || null,
+		})
+		.execute();
+}
+
+export interface CreateTestAccountWithPaymentOptions {
+	email?: string;
+	username?: string;
+	sessionId?: string;
+	priceId?: string;
+	productType?: string;
+	status?: string;
+	isGift?: boolean;
+}
+
+export async function createTestAccountWithPayment(
+	harness: ApiTestHarness,
+	options?: CreateTestAccountWithPaymentOptions,
+): Promise<{account: TestAccount; sessionId: string}> {
+	const account = await createTestAccount(harness, {
+		email: options?.email,
+		username: options?.username,
+	});
+
+	const sessionId = options?.sessionId || `cs_test_${Date.now()}`;
+
+	const userId = typeof account.userId === 'string' ? createUserID(BigInt(account.userId)) : account.userId;
+
+	await createTestPayment(harness, userId, sessionId, {
+		priceId: options?.priceId,
+		productType: options?.productType,
+		status: options?.status,
+		isGift: options?.isGift,
+	});
+
+	return {account, sessionId};
+}
+
+export async function setUserPremium(
+	harness: ApiTestHarness,
+	userId: UserID,
+	premiumType: number,
+	options?: {
+		premiumUntil?: Date | null;
+		premiumSince?: Date | null;
+		stripeCustomerId?: string | null;
+		stripeSubscriptionId?: string | null;
+		premiumBillingCycle?: string | null;
+		premiumWillCancel?: boolean;
+	},
+): Promise<void> {
+	await createBuilder(harness, '')
+		.patch(`/test/users/${userId}/premium`)
+		.body({
+			premium_type: premiumType,
+			premium_until: options?.premiumUntil?.toISOString() || null,
+			premium_since: options?.premiumSince?.toISOString() || null,
+			stripe_customer_id: options?.stripeCustomerId || null,
+			stripe_subscription_id: options?.stripeSubscriptionId || null,
+			premium_billing_cycle: options?.premiumBillingCycle || null,
+			premium_will_cancel: options?.premiumWillCancel || false,
+		})
+		.execute();
+}
+
+export async function createTestGiftCode(
+	harness: ApiTestHarness,
+	code: string,
+	createdByUserId: UserID,
+	options?: {
+		durationMonths?: number;
+		redeemedByUserId?: UserID | null;
+		redeemedAt?: Date | null;
+		paymentIntentId?: string | null;
+		checkoutSessionId?: string | null;
+	},
+): Promise<void> {
+	await createBuilder(harness, '')
+		.post('/test/gift-codes')
+		.body({
+			code,
+			created_by_user_id: createdByUserId,
+			duration_months: options?.durationMonths || 1,
+			redeemed_by_user_id: options?.redeemedByUserId || null,
+			redeemed_at: options?.redeemedAt?.toISOString() || null,
+			stripe_payment_intent_id: options?.paymentIntentId || null,
+			checkout_session_id: options?.checkoutSessionId || null,
+		})
+		.execute();
+}
+
+export function mockStripeWebhookSecret(secret = 'whsec_test'): void {
+	Object.defineProperty(Config.stripe, 'webhookSecret', {
+		get: () => secret,
+		configurable: true,
+	});
+}
+
+export function restoreStripeWebhookSecret(): void {
+	delete (Config.stripe as {webhookSecret?: string}).webhookSecret;
+}
+
+export {
+	createCheckoutCompletedEvent,
+	createInvoicePaidEvent,
+	createInvoicePaymentFailedEvent,
+	createSubscriptionDeletedEvent,
+	createSubscriptionUpdatedEvent,
+} from '@fluxer/api/src/test/msw/handlers/StripeApiHandlers';