A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
// SPDX-License-Identifier: AGPL-3.0-or-later
import type {UserID} from '@app/api/BrandedTypes';
import type {BillingRepository} from '@app/api/billing/repositories/BillingRepository';
import type {UserRow} from '@app/api/database/types/UserTypes';
import type {DonationRepository} from '@app/api/donation/DonationRepository';
import type {Donor} from '@app/api/donation/models/Donor';
import type {IGatewayService} from '@app/api/infrastructure/IGatewayService';
import type {PremiumStateReconciliationQueueService} from '@app/api/infrastructure/PremiumStateReconciliationQueueService';
import {Logger} from '@app/api/Logger';
import type {User} from '@app/api/models/User';
import type {StoreEntitlementService} from '@app/api/store_billing/StoreEntitlementService';
import type {ProductInfo} from '@app/api/stripe/ProductRegistry';
import {
canProvisionPremiumFromSubscriptionStatus,
getPremiumWillCancelFromSubscription,
shouldTreatInvoicePaymentFailureAsAccessChange,
shouldTreatInvoiceUpdatedAsCollectionIssue,
} from '@app/api/stripe/StripeSubscriptionAccessPolicy';
import {
getInvoiceLatestLinePeriodEnd,
getInvoiceLatestLinePeriodStart,
getPrimarySubscriptionItem,
getSubscriptionBillingCycle,
getSubscriptionCurrentPeriodStart,
getSubscriptionItemPeriodEnd,
getSubscriptionPremiumPeriodEnd,
getSubscriptionStartDate,
} from '@app/api/stripe/StripeSubscriptionPeriod';
import {extractId} from '@app/api/stripe/StripeUtils';
import {isDonationInvoice, isDonationSubscription} from '@app/api/stripe/services/BillingInvoiceDetails';
import type {StripePremiumService} from '@app/api/stripe/services/StripePremiumService';
import type {StripeSubscriptionReconciler} from '@app/api/stripe/services/StripeSubscriptionReconciler';
import {shiftGiftExtensionPastPremiumUntil} from '@app/api/user/GiftExtensionShift';
import {PaymentRepository} from '@app/api/user/repositories/PaymentRepository';
import type {UserRepository} from '@app/api/user/repositories/UserRepository';
import {getPremiumPaymentRecoveryGraceMs} from '@app/api/user/UserHelpers';
import {dispatchUserUpdate} from '@app/api/user/UserMappers';
import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
import type Stripe from 'stripe';
const TERMINAL_SUBSCRIPTION_STATUSES: ReadonlySet<Stripe.Subscription.Status> = new Set([
'canceled',
'incomplete_expired',
]);
export class StripeSubscriptionWebhookHandler {
private readonly paymentRepository = new PaymentRepository();
constructor(
private userRepository: UserRepository,
private gatewayService: IGatewayService,
private premiumService: StripePremiumService,
private donationRepository: DonationRepository,
private premiumStateReconciliationQueueService: PremiumStateReconciliationQueueService,
private reconciler: StripeSubscriptionReconciler,
private billingRepository: BillingRepository,
private storeEntitlementService: StoreEntitlementService | null = null,
) {}
async handleInvoicePaymentSucceeded(eventId: string, invoice: Stripe.Invoice): Promise<void> {
if (invoice.billing_reason === 'subscription_create') {
Logger.debug({invoiceId: invoice.id}, 'Skipping first invoice - handled by checkout.session.completed');
return;
}
const subscriptionId = this.reconciler.getSubscriptionIdFromInvoice(invoice);
if (!subscriptionId) {
const billingReason = invoice.billing_reason ?? null;
const isSubscriptionInvoice = typeof billingReason === 'string' && billingReason.startsWith('subscription');
if (!isSubscriptionInvoice) {
Logger.debug({invoiceId: invoice.id, billingReason}, 'Skipping invoice payment without subscription context');
return;
}
Logger.error({invoiceId: invoice.id, billingReason}, 'No subscription ID found in subscription invoice');
throw new StripeError('Invoice missing subscription id');
}
const donor = await this.donationRepository.findDonorByStripeSubscriptionId(subscriptionId);
if (donor) {
Logger.debug(
{invoiceId: invoice.id, eventId, subscriptionId, donorEmail: donor.email},
'Skipping invoice payment for donation subscription',
);
return;
}
if (isDonationInvoice(invoice)) {
Logger.debug(
{invoiceId: invoice.id, eventId, subscriptionId},
'Skipping invoice payment for donation subscription that has no donor mapping',
);
return;
}
if (this.isSubscriptionUpdateInvoice(invoice)) {
Logger.debug(
{
invoiceId: invoice.id,
eventId,
subscriptionId,
billingReason: invoice.billing_reason,
amountPaid: invoice.amount_paid,
amountDue: invoice.amount_due,
total: invoice.total,
},
'Skipping subscription_update invoice; premium_until is managed by customer.subscription.updated webhook',
);
return;
}
const renewalContext = await this.reconciler.resolveInvoiceRenewalContext(subscriptionId, invoice);
const renewalUserBeforeGrant = await this.userRepository.findUnique(renewalContext.userId);
if (!renewalUserBeforeGrant) {
Logger.error(
{invoiceId: invoice.id, eventId, subscriptionId, userId: renewalContext.userId},
'User not found for invoice renewal',
);
throw new StripeError('User not found for invoice renewal');
}
const subscriptionPayment = await this.paymentRepository.getSubscriptionInfo(subscriptionId);
const checkoutSessionId = subscriptionPayment?.checkout_session_id ?? null;
const existingPayment = checkoutSessionId
? await this.paymentRepository.getPaymentByCheckoutSession(checkoutSessionId)
: null;
if (invoice.id && existingPayment?.invoiceId === invoice.id) {
Logger.debug(
{invoiceId: invoice.id, eventId, subscriptionId, userId: renewalContext.userId},
'Skipping already-applied invoice renewal',
);
return;
}
const subscriptionSnapshot = await this.reconciler.getSubscriptionSnapshotById(subscriptionId);
const premiumSinceAnchor = subscriptionSnapshot ? getSubscriptionStartDate(subscriptionSnapshot) : null;
const renewalPeriodEnd =
(subscriptionSnapshot ? getSubscriptionPremiumPeriodEnd(subscriptionSnapshot) : null) ??
getInvoiceLatestLinePeriodEnd(invoice);
if (!renewalPeriodEnd) {
Logger.error(
{invoiceId: invoice.id, eventId, subscriptionId, userId: renewalContext.userId},
'Invoice renewal missing both subscription snapshot and invoice period_end',
);
throw new StripeError('Invoice renewal missing period end');
}
let recoveredFromPartialFailure = false;
try {
await this.premiumService.setPremiumFromSubscriptionPeriod(
renewalContext.userId,
renewalPeriodEnd,
renewalContext.productInfo.billingCycle || null,
true,
premiumSinceAnchor,
(subscriptionSnapshot ? getSubscriptionCurrentPeriodStart(subscriptionSnapshot) : null) ??
getInvoiceLatestLinePeriodStart(invoice),
);
} catch (error) {
const latestUser = await this.userRepository.findUnique(renewalContext.userId);
if (!this.didRenewalApply(renewalUserBeforeGrant, latestUser, renewalPeriodEnd)) {
throw error;
}
recoveredFromPartialFailure = true;
Logger.warn(
{invoiceId: invoice.id, eventId, subscriptionId, userId: renewalContext.userId},
'Invoice renewal grant threw after state update; treating as already applied for idempotency',
);
}
if (invoice.id && checkoutSessionId) {
await this.paymentRepository.updatePayment({
checkout_session_id: checkoutSessionId,
invoice_id: invoice.id,
});
}
if (subscriptionSnapshot) {
await this.mirrorSubscriptionSnapshot(subscriptionSnapshot, renewalContext.userId, 'invoice_payment_succeeded');
await this.reconcilePaidSubscriptionState(
renewalContext.userId,
subscriptionSnapshot,
renewalContext.productInfo,
);
}
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(renewalContext.userId, {
reason: 'invoice_payment_succeeded',
subscriptionId,
});
Logger.debug(
{
userId: renewalContext.userId,
invoiceId: invoice.id,
eventId,
subscriptionId,
durationMonths: renewalContext.productInfo.durationMonths,
reconciledFromStripe: renewalContext.reconciledFromStripe,
recoveredFromPartialFailure,
},
'Subscription renewed from invoice payment',
);
}
private isSubscriptionUpdateInvoice(invoice: Stripe.Invoice): boolean {
return invoice.billing_reason === 'subscription_update';
}
private async reconcilePaidSubscriptionState(
userId: UserID,
subscription: Stripe.Subscription,
productInfo: ProductInfo,
): Promise<void> {
const user = await this.userRepository.findUnique(userId);
if (!user) {
Logger.error({userId, subscriptionId: subscription.id}, 'User not found for paid subscription reconciliation');
throw new StripeError('User not found for paid subscription reconciliation');
}
const premiumSince = getSubscriptionStartDate(subscription);
const premiumUntil = getSubscriptionPremiumPeriodEnd(subscription);
const willCancel = getPremiumWillCancelFromSubscription(subscription);
const customerId = extractId(subscription.customer);
const billingCycle = productInfo.billingCycle || getSubscriptionBillingCycle(subscription);
const patch: Partial<UserRow> = {};
if (user.premiumType !== UserPremiumTypes.SUBSCRIPTION) {
patch.premium_type = UserPremiumTypes.SUBSCRIPTION;
}
if (!user.premiumSince || user.premiumSince.getTime() > premiumSince.getTime()) {
patch.premium_since = premiumSince;
}
if (premiumUntil && user.premiumUntil?.getTime() !== premiumUntil.getTime()) {
patch.premium_until = premiumUntil;
const giftEnd = shiftGiftExtensionPastPremiumUntil(
{premiumUntil: user.premiumUntil, giftEnd: user.premiumGiftExtensionEndsAt},
premiumUntil,
new Date(),
getSubscriptionCurrentPeriodStart(subscription),
);
if (giftEnd !== user.premiumGiftExtensionEndsAt) {
patch.premium_gift_extension_ends_at = giftEnd;
}
}
if (user.premiumWillCancel !== willCancel) {
patch.premium_will_cancel = willCancel;
}
if (user.premiumGraceEndsAt) {
patch.premium_grace_ends_at = null;
}
if (billingCycle && user.premiumBillingCycle !== billingCycle) {
patch.premium_billing_cycle = billingCycle;
}
if (user.stripeSubscriptionId !== subscription.id) {
patch.stripe_subscription_id = subscription.id;
}
if (customerId && user.stripeCustomerId !== customerId) {
patch.stripe_customer_id = customerId;
}
if (Object.keys(patch).length === 0) {
return;
}
const updatedUser = await this.userRepository.patchUpsert(user.id, patch, user.toRow());
await dispatchUserUpdate(this.gatewayService, updatedUser);
}
async handleInvoicePaymentFailed(invoice: Stripe.Invoice): Promise<void> {
if (!shouldTreatInvoicePaymentFailureAsAccessChange(invoice)) {
Logger.debug(
{
invoiceId: invoice.id,
billingReason: invoice.billing_reason,
subscriptionId: this.reconciler.getSubscriptionIdFromInvoice(invoice),
},
'Ignoring invoice.payment_failed that does not change recurring access state',
);
return;
}
await this.handleInvoiceCollectionIssue(invoice, {
reason: 'invoice_payment_failed',
logMessage: 'Recorded recurring invoice payment failure and disabled subscription grace period',
});
}
async handleInvoicePaymentActionRequired(invoice: Stripe.Invoice): Promise<void> {
if (!shouldTreatInvoicePaymentFailureAsAccessChange(invoice)) {
Logger.debug(
{
invoiceId: invoice.id,
billingReason: invoice.billing_reason,
subscriptionId: this.reconciler.getSubscriptionIdFromInvoice(invoice),
},
'Ignoring invoice.payment_action_required that does not change recurring access state',
);
return;
}
await this.handleInvoiceCollectionIssue(invoice, {
reason: 'invoice_payment_action_required',
logMessage: 'Recorded recurring invoice payment action requirement and disabled subscription grace period',
});
}
async handleInvoiceFinalizationFailed(invoice: Stripe.Invoice): Promise<void> {
if (!shouldTreatInvoicePaymentFailureAsAccessChange(invoice)) {
Logger.debug(
{
invoiceId: invoice.id,
billingReason: invoice.billing_reason,
subscriptionId: this.reconciler.getSubscriptionIdFromInvoice(invoice),
},
'Ignoring invoice.finalization_failed that does not change recurring access state',
);
return;
}
await this.handleInvoiceCollectionIssue(invoice, {
reason: 'invoice_finalization_failed',
logMessage: 'Recorded recurring invoice finalization failure and disabled subscription grace period',
});
}
async handleInvoiceUpdated(invoice: Stripe.Invoice): Promise<void> {
if (!shouldTreatInvoiceUpdatedAsCollectionIssue(invoice)) {
Logger.debug(
{
invoiceId: invoice.id,
billingReason: invoice.billing_reason,
status: invoice.status,
attempted: invoice.attempted,
attemptCount: invoice.attempt_count,
nextPaymentAttempt: invoice.next_payment_attempt,
},
'Ignoring invoice.updated that does not indicate a recurring collection issue',
);
return;
}
await this.handleInvoiceCollectionIssue(invoice, {
reason: 'invoice_updated_collection_issue',
logMessage:
'Recorded recurring invoice collection issue from invoice.updated and disabled subscription grace period',
});
}
private async isDonationSubscriptionEvent(subscription: Stripe.Subscription): Promise<boolean> {
if (isDonationSubscription(subscription)) {
return true;
}
const customerId = extractId(subscription.customer);
if (!customerId) {
return false;
}
return (await this.donationRepository.findDonorByStripeCustomerId(customerId)) !== null;
}
private async handleInvoiceCollectionIssue(
invoice: Stripe.Invoice,
context: {
reason: string;
logMessage: string;
},
): Promise<void> {
const subscriptionId = this.reconciler.getSubscriptionIdFromInvoice(invoice);
if (isDonationInvoice(invoice)) {
Logger.debug({invoiceId: invoice.id, subscriptionId}, 'Skipping collection issue for donation invoice');
return;
}
if (subscriptionId && (await this.donationRepository.findDonorByStripeSubscriptionId(subscriptionId))) {
Logger.debug(
{invoiceId: invoice.id, subscriptionId},
'Skipping collection issue for donation subscription invoice',
);
return;
}
const targetUser = await this.reconciler.resolveUserForInvoiceReconciliation(invoice, {
subscriptionId,
reason: context.reason,
});
if (!targetUser) {
Logger.warn(
{
invoiceId: invoice.id,
subscriptionId,
customerId: this.reconciler.getCustomerIdFromInvoice(invoice),
billingReason: invoice.billing_reason,
reason: context.reason,
},
'Unable to resolve user for invoice collection issue access update',
);
return;
}
if (subscriptionId && targetUser.stripeSubscriptionId !== subscriptionId) {
const mirrored = await this.billingRepository.subscriptions.findById(subscriptionId);
const status = mirrored?.status ?? (await this.reconciler.getSubscriptionSnapshotById(subscriptionId))?.status;
if (status && TERMINAL_SUBSCRIPTION_STATUSES.has(status as Stripe.Subscription.Status)) {
Logger.info(
{userId: targetUser.id, invoiceId: invoice.id, subscriptionId, status, reason: context.reason},
'Ignoring a collection issue on a subscription that has already ended',
);
return;
}
}
const updatedUser = await this.markSubscriptionPaymentIssue(targetUser, {
subscriptionId,
customerId: this.reconciler.getCustomerIdFromInvoice(invoice),
failedInvoiceServicePeriod: this.getInvoiceServicePeriod(invoice),
});
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(updatedUser.id, {
reason: context.reason,
subscriptionId: subscriptionId ?? undefined,
});
Logger.info(
{
userId: updatedUser.id,
invoiceId: invoice.id,
subscriptionId,
billingReason: invoice.billing_reason,
attemptCount: invoice.attempt_count,
status: invoice.status,
nextPaymentAttempt: invoice.next_payment_attempt,
reason: context.reason,
},
context.logMessage,
);
}
async handleSubscriptionUpdated(subscription: Stripe.Subscription, snapshotCapturedAt?: Date): Promise<void> {
Logger.debug(
{
subscriptionId: subscription.id,
customerId: extractId(subscription.customer),
status: subscription.status,
cancelAt: subscription.cancel_at,
cancelAtPeriodEnd: subscription.cancel_at_period_end,
trialEnd: subscription.trial_end,
},
'Processing Stripe subscription.updated webhook',
);
const donor = await this.donationRepository.findDonorByStripeSubscriptionId(subscription.id);
if (donor) {
Logger.debug(
{subscriptionId: subscription.id, donorEmail: donor.email},
'Routing subscription update to donor flow',
);
await this.handleDonationSubscriptionUpdated(subscription, donor);
return;
}
if (await this.isDonationSubscriptionEvent(subscription)) {
Logger.debug(
{subscriptionId: subscription.id, status: subscription.status},
'Skipping donation subscription update that has no donor mapping yet',
);
return;
}
let canonicalSubscription = subscription;
const subscriptionInfo = await this.userRepository.getSubscriptionInfo(subscription.id);
Logger.debug(
{
subscriptionId: subscription.id,
hasSubscriptionInfo: Boolean(subscriptionInfo),
mappedUserId: subscriptionInfo?.user_id,
},
'Loaded subscription mapping for subscription update',
);
let targetUser: User | null = null;
if (subscriptionInfo) {
targetUser = await this.userRepository.findUnique(subscriptionInfo.user_id);
}
if (targetUser && this.reconciler.hasSubscriptionIdentityMismatch(targetUser, canonicalSubscription)) {
Logger.warn(
{
subscriptionId: subscription.id,
userId: targetUser.id,
userStripeSubscriptionId: targetUser.stripeSubscriptionId,
userStripeCustomerId: targetUser.stripeCustomerId,
webhookCustomerId: extractId(canonicalSubscription.customer),
},
'Subscription update mapping user does not match webhook identity; reconciling from Stripe',
);
targetUser = null;
}
if (!targetUser) {
canonicalSubscription = await this.reconciler.getLatestSubscriptionSnapshot(subscription);
Logger.debug(
{
subscriptionId: subscription.id,
reconciledSubscriptionId: canonicalSubscription.id,
reconciledCustomerId: extractId(canonicalSubscription.customer),
reconciledTrialEnd: canonicalSubscription.trial_end,
},
'Resolved canonical subscription snapshot for update reconciliation',
);
targetUser = await this.reconciler.resolveUserForSubscriptionReconciliation(canonicalSubscription, {
allowStripeFetch: false,
reason: subscriptionInfo ? 'subscription_update_identity_mismatch' : 'subscription_update_missing_mapping',
});
}
if (!targetUser) {
Logger.error({subscriptionId: subscription.id}, 'No user found for subscription update');
throw new StripeError('No subscription info found for subscription update');
}
targetUser = await this.reconciler.reconcileUserWithSubscriptionState(targetUser, canonicalSubscription);
await this.mirrorSubscriptionSnapshot(
canonicalSubscription,
targetUser.id,
'subscription_updated',
snapshotCapturedAt,
);
Logger.debug(
{
subscriptionId: canonicalSubscription.id,
userId: targetUser.id,
userStripeSubscriptionId: targetUser.stripeSubscriptionId,
userStripeCustomerId: targetUser.stripeCustomerId,
},
'Reconciled user Stripe identity from subscription update',
);
type SubscriptionWithPendingUpdate = Stripe.Subscription & {
pending_update?: {
expires_at?: number | null;
} | null;
};
const pendingUpdate = (canonicalSubscription as SubscriptionWithPendingUpdate).pending_update ?? null;
if (pendingUpdate) {
Logger.warn(
{
subscriptionId: canonicalSubscription.id,
userId: targetUser.id,
status: canonicalSubscription.status,
pendingUpdateExpiresAt: pendingUpdate.expires_at ?? null,
},
'Subscription update contains pending_update; keeping current subscription state and enqueuing reconciliation',
);
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(targetUser.id, {
reason: 'subscription_updated_pending_update',
subscriptionId: canonicalSubscription.id,
});
}
const willCancel = getPremiumWillCancelFromSubscription(canonicalSubscription);
if (!canProvisionPremiumFromSubscriptionStatus(canonicalSubscription.status)) {
const updatedUser = await this.markSubscriptionPaymentIssue(targetUser, {
subscriptionId: canonicalSubscription.id,
customerId: extractId(canonicalSubscription.customer),
failedInvoiceServicePeriod: this.getUnpaidRenewalPeriod(targetUser, canonicalSubscription),
});
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(updatedUser.id, {
reason: 'subscription_updated_non_provisionable',
subscriptionId: canonicalSubscription.id,
});
Logger.info(
{
userId: updatedUser.id,
subscriptionId: canonicalSubscription.id,
status: canonicalSubscription.status,
willCancel,
},
'Subscription updated in non-provisionable state; preserved local expiry',
);
return;
}
let computedPremiumUntil = getSubscriptionPremiumPeriodEnd(canonicalSubscription);
Logger.debug(
{
subscriptionId: canonicalSubscription.id,
userId: targetUser.id,
willCancel,
computedPremiumUntil,
},
'Computed premium_until from initial subscription snapshot',
);
if (!computedPremiumUntil) {
canonicalSubscription = await this.reconciler.getLatestSubscriptionSnapshot(canonicalSubscription);
computedPremiumUntil = getSubscriptionPremiumPeriodEnd(canonicalSubscription);
Logger.debug(
{
subscriptionId: canonicalSubscription.id,
userId: targetUser.id,
computedPremiumUntil,
},
'Recomputed premium_until after refreshing subscription snapshot',
);
}
if (!computedPremiumUntil) {
Logger.error({subscriptionId: subscription.id}, 'Subscription update missing period end');
throw new StripeError('Subscription update missing period end');
}
const result = await this.userRepository.updateSubscriptionStatus(targetUser.id, {
premiumWillCancel: willCancel,
computedPremiumUntil,
periodStart: getSubscriptionCurrentPeriodStart(canonicalSubscription),
});
if (result.finalVersion === null) {
Logger.error(
{subscriptionId: subscription.id, userId: targetUser.id},
'Failed to update subscription status after retries',
);
throw new StripeError('Failed to update subscription status');
}
const updatedUser = await this.userRepository.findUnique(targetUser.id);
if (!updatedUser) {
Logger.error({subscriptionId: subscription.id, userId: targetUser.id}, 'Updated user not found');
throw new StripeError('Updated user not found for subscription update');
}
await dispatchUserUpdate(this.gatewayService, updatedUser);
await this.restoreStoreEntitlement(updatedUser.id);
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(updatedUser.id, {
reason: 'subscription_updated',
subscriptionId: canonicalSubscription.id,
});
Logger.debug(
{
userId: targetUser.id,
subscriptionId: subscription.id,
willCancel,
computedPremiumUntil,
status: canonicalSubscription.status,
},
'Subscription updated (preserved gifted extension)',
);
}
private didRenewalApply(initialUser: User, latestUser: User | null, targetPremiumUntil: Date): boolean {
if (!latestUser) {
return false;
}
const latestUntil = latestUser.premiumUntil?.getTime() ?? 0;
const initialUntil = initialUser.premiumUntil?.getTime() ?? 0;
return latestUntil >= targetPremiumUntil.getTime() && latestUntil > initialUntil;
}
async handleSubscriptionDeleted(subscription: Stripe.Subscription): Promise<void> {
const donor = await this.donationRepository.findDonorByStripeSubscriptionId(subscription.id);
if (donor) {
if (donor.stripeSubscriptionId === subscription.id) {
await this.donationRepository.cancelDonorSubscription(donor.email);
Logger.info({email: donor.email, subscriptionId: subscription.id}, 'Donation subscription deleted');
return;
}
await this.donationRepository.deleteDonorSubscriptionMapping(subscription.id, donor.email);
Logger.info(
{
email: donor.email,
subscriptionId: subscription.id,
currentSubscriptionId: donor.stripeSubscriptionId,
},
'Removed stale donation subscription mapping without touching the current donation',
);
return;
}
if (await this.isDonationSubscriptionEvent(subscription)) {
Logger.debug(
{subscriptionId: subscription.id},
'Skipping donation subscription deletion that has no donor mapping',
);
return;
}
const info = await this.userRepository.getSubscriptionInfo(subscription.id);
let targetUser: User | null = null;
if (info) {
targetUser = await this.userRepository.findUnique(info.user_id);
}
if (targetUser && this.reconciler.hasSubscriptionIdentityMismatch(targetUser, subscription)) {
Logger.warn(
{
subscriptionId: subscription.id,
userId: targetUser.id,
userStripeSubscriptionId: targetUser.stripeSubscriptionId,
userStripeCustomerId: targetUser.stripeCustomerId,
webhookCustomerId: extractId(subscription.customer),
},
'Subscription delete mapping user does not match webhook identity; reconciling from Stripe',
);
targetUser = null;
}
if (!targetUser) {
targetUser = await this.reconciler.resolveUserForSubscriptionReconciliation(subscription, {
allowStripeFetch: true,
reason: info ? 'subscription_delete_identity_mismatch' : 'subscription_delete_missing_mapping',
});
}
if (!targetUser) {
Logger.error({subscriptionId: subscription.id}, 'Subscription delete missing subscription info');
throw new StripeError('Subscription delete missing subscription info');
}
const updates: Partial<UserRow> = {
premium_will_cancel: false,
stripe_subscription_id: null,
premium_billing_cycle: null,
};
if (targetUser.premiumType === UserPremiumTypes.SUBSCRIPTION) {
const subscriptionEndedAt = subscription.ended_at ? new Date(subscription.ended_at * 1000) : new Date();
const alreadyAppliedEarlyCancellation =
targetUser.premiumUntil?.getTime() === subscriptionEndedAt.getTime() &&
targetUser.premiumGraceEndsAt?.getTime() === subscriptionEndedAt.getTime();
if (!alreadyAppliedEarlyCancellation) {
const cancelledBeforePeriodEnd =
targetUser.premiumUntil != null && subscriptionEndedAt.getTime() < targetUser.premiumUntil.getTime();
if (subscription.cancellation_details?.reason === 'payment_failed') {
const lapseStart =
targetUser.premiumUntil && targetUser.premiumUntil.getTime() < subscriptionEndedAt.getTime()
? targetUser.premiumUntil
: subscriptionEndedAt;
const billingCycle = targetUser.premiumBillingCycle ?? getSubscriptionBillingCycle(subscription);
updates.premium_until = lapseStart;
updates.premium_grace_ends_at = new Date(
lapseStart.getTime() + getPremiumPaymentRecoveryGraceMs(billingCycle),
);
} else {
if (cancelledBeforePeriodEnd) {
updates.premium_until = subscriptionEndedAt;
}
updates.premium_grace_ends_at = subscriptionEndedAt;
}
}
}
const updatedUser = await this.userRepository.patchUpsert(targetUser.id, updates, targetUser.toRow());
await dispatchUserUpdate(this.gatewayService, updatedUser);
await this.restoreStoreEntitlement(updatedUser.id);
await this.premiumStateReconciliationQueueService.enqueueUserBestEffort(updatedUser.id, {
reason: 'subscription_deleted',
subscriptionId: subscription.id,
});
}
private async handleDonationSubscriptionUpdated(subscription: Stripe.Subscription, donor: Donor): Promise<void> {
const isTerminal = TERMINAL_SUBSCRIPTION_STATUSES.has(subscription.status);
if (donor.stripeSubscriptionId !== subscription.id) {
if (isTerminal) {
await this.donationRepository.deleteDonorSubscriptionMapping(subscription.id, donor.email);
}
Logger.info(
{
email: donor.email,
subscriptionId: subscription.id,
currentSubscriptionId: donor.stripeSubscriptionId,
status: subscription.status,
},
'Ignoring donation subscription update for a subscription the donor no longer tracks',
);
return;
}
if (isTerminal) {
await this.donationRepository.cancelDonorSubscription(donor.email);
Logger.info(
{email: donor.email, subscriptionId: subscription.id, status: subscription.status},
'Donation subscription reached a terminal status',
);
return;
}
const item = getPrimarySubscriptionItem(subscription);
if (!item?.price?.recurring || item.price.unit_amount == null || !item.price.currency) {
Logger.error({subscriptionId: subscription.id}, 'Donation subscription update missing pricing details');
throw new StripeError('Donation subscription update missing pricing details');
}
const currentPeriodEnd = getSubscriptionItemPeriodEnd(item);
if (!currentPeriodEnd) {
Logger.error({subscriptionId: subscription.id}, 'Donation subscription update missing period end');
throw new StripeError('Donation subscription update missing period end');
}
const amountCents = item.price.unit_amount;
const currency = item.price.currency;
const interval = item.price.recurring.interval;
const cancelAt = subscription.cancel_at ? new Date(subscription.cancel_at * 1000) : null;
await this.donationRepository.updateDonorSubscription(donor.email, {
stripeCustomerId: extractId(subscription.customer) ?? donor.stripeCustomerId,
stripeSubscriptionId: subscription.id,
subscriptionAmountCents: amountCents,
subscriptionCurrency: currency,
subscriptionInterval: interval,
subscriptionCurrentPeriodEnd: currentPeriodEnd,
subscriptionCancelAt: cancelAt,
subscriptionStatus: subscription.status,
});
Logger.debug(
{
email: donor.email,
subscriptionId: subscription.id,
currentPeriodEnd,
status: subscription.status,
},
'Donation subscription updated',
);
}
private async markSubscriptionPaymentIssue(
user: User,
context: {
subscriptionId: string | null;
customerId: string | null;
failedInvoiceServicePeriod: {
start: Date;
end: Date;
} | null;
},
): Promise<User> {
const patch: Partial<UserRow> = {};
if (context.subscriptionId && user.stripeSubscriptionId !== context.subscriptionId) {
patch.stripe_subscription_id = context.subscriptionId;
}
if (context.customerId && user.stripeCustomerId !== context.customerId) {
patch.stripe_customer_id = context.customerId;
}
if (user.premiumType === UserPremiumTypes.SUBSCRIPTION && user.premiumWillCancel !== true) {
patch.premium_will_cancel = true;
}
if (
user.premiumType === UserPremiumTypes.SUBSCRIPTION &&
user.premiumUntil &&
context.failedInvoiceServicePeriod &&
user.premiumUntil.getTime() > context.failedInvoiceServicePeriod.start.getTime() &&
user.premiumUntil.getTime() <= context.failedInvoiceServicePeriod.end.getTime()
) {
patch.premium_until = context.failedInvoiceServicePeriod.start;
}
const lapseStart = patch.premium_until ?? user.premiumUntil;
if (
user.premiumType === UserPremiumTypes.SUBSCRIPTION &&
context.failedInvoiceServicePeriod &&
lapseStart?.getTime() === context.failedInvoiceServicePeriod.start.getTime()
) {
const graceEndsAt = new Date(lapseStart.getTime() + getPremiumPaymentRecoveryGraceMs(user.premiumBillingCycle));
if (user.premiumGraceEndsAt?.getTime() !== graceEndsAt.getTime()) {
patch.premium_grace_ends_at = graceEndsAt;
}
}
if (Object.keys(patch).length === 0) {
return user;
}
const updatedUser = await this.userRepository.patchUpsert(user.id, patch, user.toRow());
await dispatchUserUpdate(this.gatewayService, updatedUser);
return (await this.restoreStoreEntitlement(updatedUser.id)) ?? updatedUser;
}
private getUnpaidRenewalPeriod(
user: User,
subscription: Stripe.Subscription,
): {
start: Date;
end: Date;
} | null {
if (subscription.status !== 'past_due' && subscription.status !== 'unpaid') {
return null;
}
const item = getPrimarySubscriptionItem(subscription);
if (!item?.current_period_start || !item.current_period_end || !user.premiumUntil) {
return null;
}
const start = new Date(item.current_period_start * 1000);
if (user.premiumUntil.getTime() !== start.getTime()) {
return null;
}
return {start, end: new Date(item.current_period_end * 1000)};
}
private getInvoiceServicePeriod(invoice: Stripe.Invoice): {
start: Date;
end: Date;
} | null {
if (!invoice.lines?.data?.length) {
return null;
}
let periodStart: number | null = null;
let periodEnd: number | null = null;
for (const line of invoice.lines.data) {
if (!line.period?.start || !line.period?.end) {
continue;
}
if (periodStart == null || line.period.start < periodStart) {
periodStart = line.period.start;
}
if (periodEnd == null || line.period.end > periodEnd) {
periodEnd = line.period.end;
}
}
if (periodStart == null || periodEnd == null) {
return null;
}
return {
start: new Date(periodStart * 1000),
end: new Date(periodEnd * 1000),
};
}
private async mirrorSubscriptionSnapshot(
subscription: Stripe.Subscription,
userId: UserID,
reason: string,
snapshotCapturedAt?: Date,
): Promise<void> {
try {
await this.billingRepository.subscriptions.upsertFromStripe(subscription, {
knownUserId: userId,
snapshotCapturedAt,
});
} catch (error) {
Logger.error(
{error, userId: userId.toString(), subscriptionId: subscription.id, reason},
'Failed to refresh billing subscription mirror from Stripe snapshot',
);
}
}
private async restoreStoreEntitlement(userId: UserID): Promise<User | null> {
if (!(await this.storeEntitlementService?.reapplyAfterStripeChange(userId))) {
return null;
}
return this.userRepository.findUnique(userId);
}
}