Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/web/app/utils/services/.server/billingDunningService.ts
T
2026-07-08 16:15:37 +02:00

248 lines
9.8 KiB
TypeScript

import type Stripe from "stripe";
import { createNotificationDelivery } from "@hivegrid/db/notifications.server";
import { db } from "~/utils/db.server";
import { clearTenantSubscriptionCache } from "./subscriptionService";
export const BILLING_DUNNING_DAY_MARKS = [1, 3, 7] as const;
const DAY_MS = 24 * 60 * 60 * 1000;
const UNKNOWN_STRIPE_WEBHOOK_ERROR_CODE = "billing.stripeWebhook.unknownError";
export type BillingDunningDecision =
| { kind: "noop" }
| { kind: "send_dunning"; attempt: 1 | 2 | 3; thresholdDays: 1 | 3 | 7 }
| { kind: "freeze"; thresholdDays: 7 };
export type BillingDunningSubscription = {
status: string | null;
pastDueSince: Date | string | null;
dunningAttemptCount: number | null;
};
type BillingDunningDeps = {
now?: Date;
sendDunningNotice?: (input: { tenantId: string; attempt: 1 | 2 | 3; thresholdDays: 1 | 3 | 7 }) => Promise<void>;
client?: Pick<typeof db, "tenantSubscription" | "tenantSubscriptionProduct" | "stripeWebhookLog">;
};
type StripeSubscriptionLike = {
id: string;
status?: string | null;
current_period_start?: number | null;
current_period_end?: number | null;
cancel_at?: number | null;
canceled_at?: number | null;
};
function asDate(value: Date | string | null | undefined): Date | null {
if (!value) return null;
const date = value instanceof Date ? value : new Date(value);
return Number.isNaN(date.getTime()) ? null : date;
}
function fromUnix(value: number | null | undefined): Date | null {
return typeof value === "number" && Number.isFinite(value) ? new Date(value * 1000) : null;
}
function daysSince(from: Date, now: Date): number {
return Math.floor((now.getTime() - from.getTime()) / DAY_MS);
}
export function evaluateBillingDunning(input: BillingDunningSubscription, now: Date = new Date()): BillingDunningDecision {
if (input.status !== "past_due") return { kind: "noop" };
const pastDueSince = asDate(input.pastDueSince);
if (!pastDueSince) return { kind: "noop" };
const elapsedDays = daysSince(pastDueSince, now);
const attempts = Math.max(0, input.dunningAttemptCount ?? 0);
if (attempts >= BILLING_DUNNING_DAY_MARKS.length) {
return elapsedDays >= 7 ? { kind: "freeze", thresholdDays: 7 } : { kind: "noop" };
}
const thresholdDays = BILLING_DUNNING_DAY_MARKS[attempts];
if (elapsedDays < thresholdDays) return { kind: "noop" };
return { kind: "send_dunning", attempt: (attempts + 1) as 1 | 2 | 3, thresholdDays };
}
export function billingStatusFromStripeSubscription(status: string | null | undefined): "trial" | "active" | "past_due" | "cancelled" {
if (status === "trialing") return "trial";
if (status === "active") return "active";
if (status === "canceled") return "cancelled";
if (status === "past_due" || status === "unpaid" || status === "incomplete" || status === "incomplete_expired") return "past_due";
return "active";
}
export async function createBillingDunningNotification(input: { tenantId: string; attempt: 1 | 2 | 3; thresholdDays: 1 | 3 | 7 }): Promise<void> {
await createNotificationDelivery({
tenantId: input.tenantId,
channel: "EMAIL",
category: "billing",
messageKey: `billing.notify.dunning.attempt${input.attempt}`,
sourceKey: `billing-dunning:${input.tenantId}:attempt:${input.attempt}`,
payloadMetadata: {
attempt: input.attempt,
thresholdDays: input.thresholdDays,
},
});
}
export async function applyBillingDunningCycle(deps: BillingDunningDeps = {}) {
const client = deps.client ?? db;
const now = deps.now ?? new Date();
const sendDunningNotice = deps.sendDunningNotice ?? createBillingDunningNotification;
const subscriptions = await client.tenantSubscription.findMany({
where: { status: "past_due", pastDueSince: { not: null } },
select: { tenantId: true, status: true, pastDueSince: true, dunningAttemptCount: true },
});
const results: { tenantId: string; decision: BillingDunningDecision }[] = [];
for (const subscription of subscriptions) {
const decision = evaluateBillingDunning(subscription, now);
if (decision.kind === "send_dunning") {
await sendDunningNotice({ tenantId: subscription.tenantId, attempt: decision.attempt, thresholdDays: decision.thresholdDays });
await client.tenantSubscription.update({
where: { tenantId: subscription.tenantId },
data: { dunningAttemptCount: { increment: 1 }, lastDunningSentAt: now },
});
clearTenantSubscriptionCache(subscription.tenantId);
} else if (decision.kind === "freeze") {
await client.tenantSubscription.update({
where: { tenantId: subscription.tenantId },
data: { status: "frozen", frozenAt: now },
});
clearTenantSubscriptionCache(subscription.tenantId);
}
results.push({ tenantId: subscription.tenantId, decision });
}
return results;
}
async function setBillingStatusForTenant(
tenantId: string,
status: "trial" | "active" | "past_due" | "cancelled" | "frozen",
now: Date,
client: BillingDunningDeps["client"] = db,
) {
if (status === "past_due") {
const existingSubscription = await client.tenantSubscription.findUnique({
where: { tenantId },
select: { pastDueSince: true },
});
await client.tenantSubscription.update({
where: { tenantId },
data: {
status,
pastDueSince: existingSubscription?.pastDueSince ?? now,
frozenAt: null,
},
});
clearTenantSubscriptionCache(tenantId);
return;
}
await client.tenantSubscription.update({
where: { tenantId },
data: {
status,
pastDueSince: null,
frozenAt: null,
cancelledAt: status === "cancelled" ? now : null,
dunningAttemptCount: 0,
lastDunningSentAt: null,
},
});
clearTenantSubscriptionCache(tenantId);
}
function subscriptionIdFromInvoice(invoice: Record<string, unknown>): string | null {
const direct = invoice.subscription;
if (typeof direct === "string") return direct;
if (direct && typeof direct === "object" && "id" in direct && typeof direct.id === "string") return direct.id;
const parent = invoice.parent as { subscription_details?: { subscription?: unknown } } | null | undefined;
const parentSubscription = parent?.subscription_details?.subscription;
if (typeof parentSubscription === "string") return parentSubscription;
if (parentSubscription && typeof parentSubscription === "object" && "id" in parentSubscription && typeof parentSubscription.id === "string") {
return parentSubscription.id;
}
return null;
}
async function syncSubscriptionStatusFromStripeSubscription(
subscription: StripeSubscriptionLike,
now: Date,
client: BillingDunningDeps["client"] = db,
): Promise<string | null> {
const tenantProduct = await client.tenantSubscriptionProduct.findFirst({
where: { billingProviderSubscriptionId: subscription.id },
select: { id: true, tenantSubscription: { select: { tenantId: true } } },
});
if (!tenantProduct) return null;
await client.tenantSubscriptionProduct.update({
where: { id: tenantProduct.id },
data: {
currentPeriodStart: fromUnix(subscription.current_period_start),
currentPeriodEnd: fromUnix(subscription.current_period_end),
endsAt: fromUnix(subscription.cancel_at),
cancelledAt: fromUnix(subscription.canceled_at),
},
});
await setBillingStatusForTenant(tenantProduct.tenantSubscription.tenantId, billingStatusFromStripeSubscription(subscription.status), now, client);
return tenantProduct.tenantSubscription.tenantId;
}
async function markInvoiceSubscriptionStatus(
invoice: Record<string, unknown>,
status: "active" | "past_due",
now: Date,
client: BillingDunningDeps["client"] = db,
): Promise<string | null> {
const subscriptionId = subscriptionIdFromInvoice(invoice);
if (!subscriptionId) return null;
const tenantProduct = await client.tenantSubscriptionProduct.findFirst({
where: { billingProviderSubscriptionId: subscriptionId },
select: { tenantSubscription: { select: { tenantId: true } } },
});
if (!tenantProduct) return null;
await setBillingStatusForTenant(tenantProduct.tenantSubscription.tenantId, status, now, client);
return tenantProduct.tenantSubscription.tenantId;
}
export async function processStripeBillingEvent(event: Stripe.Event, deps: BillingDunningDeps = {}) {
const client = deps.client ?? db;
const now = deps.now ?? new Date();
const existing = await client.stripeWebhookLog.findUnique({ where: { stripeEventId: event.id } });
if (existing?.processedAt) {
return { replayed: true, relatedTenantId: existing.relatedTenantId ?? null };
}
await client.stripeWebhookLog.upsert({
where: { stripeEventId: event.id },
create: { stripeEventId: event.id, eventType: event.type },
update: { eventType: event.type, error: null },
});
try {
let relatedTenantId: string | null = null;
if (event.type === "customer.subscription.updated" || event.type === "customer.subscription.deleted") {
relatedTenantId = await syncSubscriptionStatusFromStripeSubscription(event.data.object as StripeSubscriptionLike, now, client);
} else if (event.type === "invoice.payment_failed") {
relatedTenantId = await markInvoiceSubscriptionStatus(event.data.object as unknown as Record<string, unknown>, "past_due", now, client);
} else if (event.type === "invoice.paid" || event.type === "invoice.payment_succeeded") {
relatedTenantId = await markInvoiceSubscriptionStatus(event.data.object as unknown as Record<string, unknown>, "active", now, client);
}
await client.stripeWebhookLog.update({
where: { stripeEventId: event.id },
data: { processedAt: now, relatedTenantId, error: null },
});
return { replayed: false, relatedTenantId };
} catch (error) {
await client.stripeWebhookLog.update({
where: { stripeEventId: event.id },
data: { error: error instanceof Error ? error.message : UNKNOWN_STRIPE_WEBHOOK_ERROR_CODE },
});
throw error;
}
}