Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp

feat(billing): add payment dispute reviews

Hampus503de04bd097
diff --git a/fluxer_api/src/api/payment_disputes/PaymentDisputeRepository.ts b/fluxer_api/src/api/payment_disputes/PaymentDisputeRepository.ts
new file mode 100644
index 000000000..e9a4d2ec5
--- /dev/null
+++ b/fluxer_api/src/api/payment_disputes/PaymentDisputeRepository.ts
@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {UserID} from '@app/api/BrandedTypes';
+import {
+ executeConditional,
+ fetchMany,
+ fetchOne,
+ fetchPage,
+ type PagedQueryResult,
+ upsertOne,
+} from '@app/api/database/CassandraQueryExecution';
+import {Db, type DbOp, nextVersion, type PatchObject} from '@app/api/database/CassandraTypes';
+import {applyPatchToRow} from '@app/api/database/CassandraVersionedUpdate';
+import type {
+ PaymentDisputeReviewByPurchaserRow,
+ PaymentDisputeReviewRow,
+} from '@app/api/database/types/PaymentDisputeTypes';
+import {PaymentDisputeReviews, PaymentDisputeReviewsByPurchaser} from '@app/api/Tables';
+import {BACKGROUND_READ_TIMEOUT_MS} from '@pkgs/cassandra/src/Client';
+
+export type PaymentDisputeReviewPatch = Partial<{
+ [K in Exclude<keyof PaymentDisputeReviewRow, 'dispute_id' | 'version'>]: DbOp<PaymentDisputeReviewRow[K]>;
+}>;
+
+const FETCH_REVIEW = PaymentDisputeReviews.selectCql({
+ where: PaymentDisputeReviews.where.eq('dispute_id'),
+ limit: 1,
+});
+const SCAN_REVIEWS = PaymentDisputeReviews.selectCql();
+const FETCH_DISPUTE_IDS_BY_PURCHASER = PaymentDisputeReviewsByPurchaser.selectCql({
+ columns: ['dispute_id'],
+ where: PaymentDisputeReviewsByPurchaser.where.eq('purchaser_id'),
+});
+const SCAN_PAGE_SIZE = 200;
+
+export class PaymentDisputeRepository {
+ async findReview(disputeId: string): Promise<PaymentDisputeReviewRow | null> {
+ return fetchOne<PaymentDisputeReviewRow>(FETCH_REVIEW, {dispute_id: disputeId});
+ }
+
+ async createReview(row: PaymentDisputeReviewRow): Promise<boolean> {
+ await upsertOne(
+ PaymentDisputeReviewsByPurchaser.upsertAll({purchaser_id: row.purchaser_id, dispute_id: row.dispute_id}),
+ );
+ return executeConditional(PaymentDisputeReviews.insertIfNotExists(row));
+ }
+
+ async updateReview(
+ current: PaymentDisputeReviewRow,
+ patch: PaymentDisputeReviewPatch,
+ ): Promise<PaymentDisputeReviewRow | null> {
+ const version = nextVersion(current.version);
+ const applied = await executeConditional(
+ PaymentDisputeReviews.conditionalPatchByPk(
+ {dispute_id: current.dispute_id},
+ {...patch, version: Db.set(version)},
+ {version: current.version},
+ ),
+ );
+ if (!applied) {
+ return null;
+ }
+ return {
+ ...applyPatchToRow<PaymentDisputeReviewRow>(current, patch as PatchObject),
+ version,
+ } as PaymentDisputeReviewRow;
+ }
+
+ async listReviewsByPurchaser(purchaserId: UserID): Promise<Array<PaymentDisputeReviewRow>> {
+ const mappings = await fetchMany<Pick<PaymentDisputeReviewByPurchaserRow, 'dispute_id'>>(
+ FETCH_DISPUTE_IDS_BY_PURCHASER,
+ {purchaser_id: purchaserId},
+ );
+ const reviews = await Promise.all(mappings.map((mapping) => this.findReview(mapping.dispute_id)));
+ return reviews.filter((review): review is PaymentDisputeReviewRow => review !== null);
+ }
+
+ async listReviews(): Promise<Array<PaymentDisputeReviewRow>> {
+ const rows: Array<PaymentDisputeReviewRow> = [];
+ let pageState: string | null = null;
+ do {
+ const page: PagedQueryResult<PaymentDisputeReviewRow> = await fetchPage<PaymentDisputeReviewRow>(
+ SCAN_REVIEWS,
+ {},
+ {pageSize: SCAN_PAGE_SIZE, pageState, readTimeout: BACKGROUND_READ_TIMEOUT_MS},
+ );
+ rows.push(...page.rows);
+ pageState = page.pageState;
+ } while (pageState);
+ return rows;
+ }
+}
diff --git a/fluxer_api/src/api/payment_disputes/PaymentDisputeReviews.ts b/fluxer_api/src/api/payment_disputes/PaymentDisputeReviews.ts
new file mode 100644
index 000000000..2a0ea2ee3
--- /dev/null
+++ b/fluxer_api/src/api/payment_disputes/PaymentDisputeReviews.ts
@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import type {AdminAuditService} from '@app/api/admin/services/AdminAuditService';
+import type {UserID} from '@app/api/BrandedTypes';
+import {Config} from '@app/api/Config';
+import {SYSTEM_USER_ID} from '@app/api/constants/Core';
+import {Db} from '@app/api/database/CassandraTypes';
+import type {OperatorPassPurchaseRow, OperatorPassRemovalHistoryRow} from '@app/api/database/types/OperatorPassTypes';
+import type {PaymentDisputeProduct, PaymentDisputeReviewRow} from '@app/api/database/types/PaymentDisputeTypes';
+import {resolveContactEmails} from '@app/api/instance/ContactEmails';
+import {Logger} from '@app/api/Logger';
+import {getOperatorPassWithdrawalRightEndsAt} from '@app/api/operator_pass/OperatorPassPurchaseRules';
+import type {PaymentDisputeRepository} from '@app/api/payment_disputes/PaymentDisputeRepository';
+import {extractId} from '@app/api/stripe/StripeUtils';
+import {PremiumPurchaseBlockedError} from '@fluxer/errors/src/domains/payment/PremiumPurchaseBlockedError';
+import type {IEmailService} from '@pkgs/email/src/IEmailService';
+import type Stripe from 'stripe';
+
+const PAYMENT_DISPUTE_EXEMPT_REASONS: ReadonlyArray<string> = [
+ 'fraudulent',
+ 'unrecognized',
+ 'debit_not_authorized',
+ 'duplicate',
+ 'credit_not_processed',
+ 'product_not_received',
+ 'product_unacceptable',
+];
+
+const PAYMENT_DISPUTE_REVIEW_BLOCKERS = [
+ 'exempt_reason',
+ 'during_withdrawal',
+ 'withdrawn',
+ 'refunded_before_dispute',
+ 'perks_not_provided',
+ 'perks_removed',
+ 'before_terms_effective',
+] as const;
+
+export type PaymentDisputeReviewBlocker = (typeof PAYMENT_DISPUTE_REVIEW_BLOCKERS)[number];
+
+export interface PaymentDisputeSubject {
+ product: PaymentDisputeProduct;
+ orderId: string;
+ invoiceNumber: string | null;
+ purchaserId: UserID;
+ isGift: boolean;
+ paymentIntentId: string | null;
+ amountMinor: number;
+ currency: string;
+ disputedAt: Date | null;
+ purchasedAt: Date | null;
+ perksStartedAt: Date | null;
+ withdrawalEndsAt: Date | null;
+ withdrawnAt: Date | null;
+ refundedAt: Date | null;
+ perksRemovedAt: Date | null;
+}
+
+export function isPaymentDisputeOpen(review: PaymentDisputeReviewRow): boolean {
+ return review.closed_at == null;
+}
+
+function underClosureTerms(review: PaymentDisputeReviewRow, disputedAt: number): boolean {
+ const effectiveAt = Config.paymentDisputes.closureEffectiveAt?.getTime() ?? null;
+ if (effectiveAt === null || !review.purchased_at) return false;
+ return disputedAt >= effectiveAt && review.purchased_at.getTime() >= effectiveAt;
+}
+
+export function getPaymentDisputeReviewBlockers(review: PaymentDisputeReviewRow): Array<PaymentDisputeReviewBlocker> {
+ const blockers: Array<PaymentDisputeReviewBlocker> = [];
+ if (PAYMENT_DISPUTE_EXEMPT_REASONS.includes(review.reason)) {
+ blockers.push('exempt_reason');
+ }
+ const disputedAt = review.disputed_at?.getTime() ?? review.created_at.getTime();
+ if (!review.withdrawal_ends_at || disputedAt < review.withdrawal_ends_at.getTime()) {
+ blockers.push('during_withdrawal');
+ }
+ if (review.withdrawn_at) {
+ blockers.push('withdrawn');
+ }
+ if (review.refunded_at && review.refunded_at.getTime() <= disputedAt) {
+ blockers.push('refunded_before_dispute');
+ }
+ if (!review.perks_started_at) {
+ blockers.push('perks_not_provided');
+ }
+ if (review.perks_removed_at) {
+ blockers.push('perks_removed');
+ }
+ if (review.product === 'plutonium' && !underClosureTerms(review, disputedAt)) {
+ blockers.push('before_terms_effective');
+ }
+ return blockers;
+}
+
+function firstPerkRemovalBefore(history: ReadonlyArray<OperatorPassRemovalHistoryRow>, disputedAt: Date): Date | null {
+ let first: Date | null = null;
+ for (const entry of history) {
+ if (entry.removed_at.getTime() <= disputedAt.getTime() && (!first || entry.removed_at < first)) {
+ first = entry.removed_at;
+ }
+ }
+ return first;
+}
+
+export function getOperatorPassDisputeSubject(
+ purchase: OperatorPassPurchaseRow,
+ dispute: Stripe.Dispute,
+ holderRemovals: ReadonlyArray<OperatorPassRemovalHistoryRow>,
+): PaymentDisputeSubject {
+ const disputedAt = purchase.disputed_at ?? new Date(dispute.created * 1000);
+ return {
+ product: 'operator_pass',
+ orderId: purchase.checkout_session_id,
+ invoiceNumber: purchase.invoice_number ?? null,
+ purchaserId: purchase.purchaser_id,
+ isGift: false,
+ paymentIntentId: purchase.payment_intent_id ?? null,
+ amountMinor: purchase.amount_minor,
+ currency: purchase.currency,
+ disputedAt,
+ purchasedAt: purchase.purchased_at ?? null,
+ perksStartedAt: purchase.perks_granted_at ?? null,
+ withdrawalEndsAt: getOperatorPassWithdrawalRightEndsAt(purchase),
+ withdrawnAt: purchase.withdrawn_at ?? null,
+ refundedAt: purchase.refunded_at ?? null,
+ perksRemovedAt: firstPerkRemovalBefore(holderRemovals, disputedAt),
+ };
+}
+
+function getEvidenceDueBy(dispute: Stripe.Dispute): Date | null {
+ const dueBy = dispute.evidence_details?.due_by;
+ return typeof dueBy === 'number' ? new Date(dueBy * 1000) : null;
+}
+
+function isClosedDisputeStatus(status: Stripe.Dispute.Status): boolean {
+ return status === 'won' || status === 'lost' || status === 'warning_closed' || status === 'prevented';
+}
+
+export async function hasOpenPaymentDispute(
+ repository: Pick<PaymentDisputeRepository, 'listReviewsByPurchaser'>,
+ userId: UserID,
+): Promise<boolean> {
+ const reviews = await repository.listReviewsByPurchaser(userId);
+ return reviews.some(isPaymentDisputeOpen);
+}
+
+export async function assertNoOpenPaymentDispute(
+ repository: Pick<PaymentDisputeRepository, 'listReviewsByPurchaser'>,
+ userId: UserID,
+): Promise<void> {
+ if (await hasOpenPaymentDispute(repository, userId)) {
+ throw new PremiumPurchaseBlockedError('payment_dispute_open');
+ }
+}
+
+export async function flagPurchaseDuringDispute(
+ repository: Pick<PaymentDisputeRepository, 'listReviewsByPurchaser' | 'updateReview'>,
+ userId: UserID,
+ purchaseKey: string,
+): Promise<number> {
+ let flagged = 0;
+ for (const review of await repository.listReviewsByPurchaser(userId)) {
+ if (!isPaymentDisputeOpen(review) || review.dispute_purchase_at) {
+ continue;
+ }
+ if (await repository.updateReview(review, {dispute_purchase_at: Db.set(new Date())})) {
+ flagged += 1;
+ Logger.warn(
+ {disputeId: review.dispute_id, purchaserId: userId.toString(), purchaseKey},
+ 'A purchase was applied while a payment dispute is open',
+ );
+ }
+ }
+ return flagged;
+}
+
+export async function listPaymentDisputeReviews(
+ repository: Pick<PaymentDisputeRepository, 'listReviews'>,
+): Promise<Array<PaymentDisputeReviewRow>> {
+ const reviews = await repository.listReviews();
+ return reviews.sort((left, right) => right.created_at.getTime() - left.created_at.getTime());
+}
+
+export class PaymentDisputeReviewService {
+ constructor(
+ private readonly repository: PaymentDisputeRepository,
+ private readonly auditService: AdminAuditService,
+ private readonly emailService: Pick<IEmailService, 'send'>,
+ ) {}
+
+ async openReview(subject: PaymentDisputeSubject, dispute: Stripe.Dispute): Promise<PaymentDisputeReviewRow> {
+ const existing = await this.repository.findReview(dispute.id);
+ if (existing) {
+ return (await this.refreshReview(dispute)) ?? existing;
+ }
+ const review = this.buildReview(subject, dispute);
+ const created = await this.repository.createReview(review);
+ if (!created) {
+ return (await this.repository.findReview(dispute.id)) ?? review;
+ }
+ await this.auditService.createAuditLog({
+ adminUserId: SYSTEM_USER_ID,
+ targetType: 'user',
+ targetId: BigInt(subject.purchaserId),
+ action: 'open_payment_dispute_review',
+ auditLogReason: 'Payment dispute opened, purchases are blocked until it closes and a person reviews it',
+ metadata: new Map([
+ ['dispute_id', dispute.id],
+ ['product', review.product],
+ ['order_id', review.order_id],
+ ['reason', review.reason],
+ ['evidence_due_by', review.evidence_due_by?.toISOString() ?? ''],
+ ['blockers', getPaymentDisputeReviewBlockers(review).join(',')],
+ ]),
+ });
+ Logger.info(
+ {disputeId: dispute.id, product: review.product, orderId: review.order_id, purchaserId: subject.purchaserId},
+ 'Opened a payment dispute review',
+ );
+ await this.alertStaff(review);
+ return review;
+ }
+
+ private async alertStaff(review: PaymentDisputeReviewRow): Promise<void> {
+ const {supportEmail} = resolveContactEmails();
+ if (!supportEmail || review.closed_at) {
+ return;
+ }
+ const sent = await this.emailService.send('payment_dispute_review_alert', supportEmail, {
+ disputeId: review.dispute_id,
+ product: review.product,
+ invoiceNumber: review.invoice_number ?? null,
+ purchaserId: review.purchaser_id.toString(),
+ reason: review.reason,
+ amountMinor: review.amount_minor,
+ currency: review.currency,
+ evidenceDueBy: review.evidence_due_by ?? null,
+ blockers: getPaymentDisputeReviewBlockers(review),
+ reviewUrl: `${Config.endpoints.admin}/payment-disputes`,
+ });
+ if (!sent) {
+ Logger.warn({disputeId: review.dispute_id}, 'Failed to email staff about a new payment dispute review');
+ }
+ }
+
+ async refreshReview(dispute: Stripe.Dispute): Promise<PaymentDisputeReviewRow | null> {
+ for (let attempt = 0; attempt < 3; attempt++) {
+ const review = await this.repository.findReview(dispute.id);
+ if (!review || !isPaymentDisputeOpen(review)) {
+ return review;
+ }
+ const updated = await this.repository.updateReview(review, {
+ reason: Db.set(dispute.reason ?? review.reason),
+ evidence_submitted: Db.set(dispute.evidence_details?.has_evidence === true),
+ evidence_due_by: Db.set(getEvidenceDueBy(dispute) ?? review.evidence_due_by),
+ });
+ if (updated) {
+ return updated;
+ }
+ }
+ return this.repository.findReview(dispute.id);
+ }
+
+ async closeReview(subject: PaymentDisputeSubject, dispute: Stripe.Dispute): Promise<PaymentDisputeReviewRow> {
+ const closedAt = new Date();
+ for (let attempt = 0; attempt < 3; attempt++) {
+ const review = await this.repository.findReview(dispute.id);
+ if (!review) {
+ await this.repository.createReview({
+ ...this.buildReview(subject, dispute),
+ closed_at: closedAt,
+ outcome: dispute.status,
+ });
+ continue;
+ }
+ if (!isPaymentDisputeOpen(review)) {
+ return review;
+ }
+ const updated = await this.repository.updateReview(review, {
+ reason: Db.set(dispute.reason ?? review.reason),
+ evidence_submitted: Db.set(dispute.evidence_details?.has_evidence === true),
+ closed_at: Db.set(closedAt),
+ outcome: Db.set(dispute.status),
+ withdrawn_at: Db.set(review.withdrawn_at ?? subject.withdrawnAt),
+ perks_removed_at: Db.set(review.perks_removed_at ?? subject.perksRemovedAt),
+ });
+ if (updated) {
+ Logger.info(
+ {disputeId: dispute.id, outcome: dispute.status, status: updated.status},
+ 'Closed a payment dispute review',
+ );
+ return updated;
+ }
+ }
+ const review = await this.repository.findReview(dispute.id);
+ if (!review || isPaymentDisputeOpen(review)) {
+ throw new Error(`Payment dispute review ${dispute.id} could not be closed`);
+ }
+ return review;
+ }
+
+ private buildReview(subject: PaymentDisputeSubject, dispute: Stripe.Dispute): PaymentDisputeReviewRow {
+ const now = new Date();
+ return {
+ dispute_id: dispute.id,
+ product: subject.product,
+ order_id: subject.orderId,
+ invoice_number: subject.invoiceNumber,
+ purchaser_id: subject.purchaserId,
+ is_gift: subject.isGift,
+ reason: dispute.reason ?? 'general',
+ payment_intent_id: subject.paymentIntentId,
+ charge_id: extractId(dispute.charge),
+ amount_minor: dispute.amount ?? subject.amountMinor,
+ currency: (dispute.currency ?? subject.currency).toUpperCase(),
+ evidence_submitted: dispute.evidence_details?.has_evidence === true,
+ evidence_due_by: getEvidenceDueBy(dispute),
+ disputed_at: subject.disputedAt ?? new Date(dispute.created * 1000),
+ closed_at: isClosedDisputeStatus(dispute.status) ? now : null,
+ outcome: isClosedDisputeStatus(dispute.status) ? dispute.status : null,
+ purchased_at: subject.purchasedAt,
+ perks_started_at: subject.perksStartedAt,
+ withdrawal_ends_at: subject.withdrawalEndsAt,
+ withdrawn_at: subject.withdrawnAt,
+ refunded_at: subject.refundedAt,
+ perks_removed_at: subject.perksRemovedAt,
+ status: 'open',
+ created_at: now,
+ decided_at: null,
+ decided_by: null,
+ decision_note: null,
+ warning_deadline: null,
+ warned_at: null,
+ warning_email_sent_at: null,
+ warning_dm_sent_at: null,
+ enforcement_decision_id: null,
+ reversed_at: null,
+ reversed_by: null,
+ reversal_note: null,
+ dispute_purchase_at: null,
+ version: 1,
+ };
+ }
+}