refactor progress

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';