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 {createUserID, type UserID} from '@app/api/BrandedTypes';
import {alertSupport} from '@app/api/billing/BillingSupportAlert';
import {
type BillingDocumentService,
billingDocumentAttachment,
billingDocumentTotals,
createBillingDocumentService,
} from '@app/api/billing_documents/BillingDocumentService';
import {Config} from '@app/api/Config';
import {Db} from '@app/api/database/CassandraTypes';
import type {
OperatorPassCertificateRow,
OperatorPassOfferRow,
OperatorPassPurchaseRow,
OperatorPassUnitRow,
OperatorPassWithdrawalChannel,
} from '@app/api/database/types/OperatorPassTypes';
import {Logger} from '@app/api/Logger';
import type {OperatorPassServices} from '@app/api/middleware/OperatorPassServiceFactory';
import {getBillingRepository, getKVClient, getWorkerService} from '@app/api/middleware/ServiceRegistry';
import type {User} from '@app/api/models/User';
import {findOperatorPassBusinessPurchase} from '@app/api/operator_pass/OperatorPassBusinessListing';
import {
type OperatorPassCertificateReissueReason,
OperatorPassCertificateService,
} from '@app/api/operator_pass/OperatorPassCertificateService';
import {creditOperatorPassRefunds, operatorPassDocumentContext} from '@app/api/operator_pass/OperatorPassCreditNotes';
import {
isOperatorPassPermanentlyRemoved,
loadOperatorPassEntitlementState,
} from '@app/api/operator_pass/OperatorPassEntitlementService';
import type {
OperatorPassHoldingService,
OperatorPassOfferParams,
} from '@app/api/operator_pass/OperatorPassHoldingService';
import {
keepsOperatorsThroughVisionary,
OPERATOR_PASS_LABS_INVITE_URL,
} from '@app/api/operator_pass/OperatorPassLabsRole';
import {
type OperatorPassLockLease,
operatorPassHolderLockKey,
operatorPassPurchaseLockKey,
withOperatorPassLock,
} from '@app/api/operator_pass/OperatorPassLocks';
import {
OPERATOR_PASS_WITHDRAWAL_RULE_VERSION,
type OperatorPassWithdrawalRuleMatch,
resolveOperatorPassWithdrawalRule,
} from '@app/api/operator_pass/OperatorPassPrices';
import {
getOperatorPassCertificateUrl,
getOperatorPassWithdrawalEndsAt,
getOperatorPassWithdrawalEndsOn,
isOperatorPassCertificatePageCancelled,
isOperatorPassPurchaseWithdrawable,
isOperatorPassSinglePassWithdrawable,
isOperatorPassWelcomeSettled,
isOperatorPassWithinWithdrawalDeadline,
listOperatorPassWithdrawableUnits,
replaceOperatorPassCertificateName,
wasOperatorPassPurchaseUndeliveredAt,
} from '@app/api/operator_pass/OperatorPassPurchaseRules';
import type {OperatorPassRepository} from '@app/api/operator_pass/OperatorPassRepository';
import {isOperatorPassCurrency, operatorPassNow} from '@app/api/operator_pass/OperatorPassSchedule';
import {OperatorPassVisionaryService} from '@app/api/operator_pass/OperatorPassVisionaryService';
import type {OperatorPassWallService} from '@app/api/operator_pass/OperatorPassWallService';
import {extractId} from '@app/api/stripe/StripeUtils';
import {enqueueBillingEmail} from '@app/api/stripe/services/BillingEmailService';
import type {UserRepository} from '@app/api/user/repositories/UserRepository';
import {APIErrorCodes} from '@fluxer/constants/src/ApiErrorCodes';
import {ConflictError} from '@fluxer/errors/src/domains/core/ConflictError';
import {InputValidationError} from '@fluxer/errors/src/domains/core/InputValidationError';
import {OperatorPassOfferBusyError} from '@fluxer/errors/src/domains/operator_pass/OperatorPassOfferBusyError';
import {OperatorPassWithdrawalUnavailableError} from '@fluxer/errors/src/domains/operator_pass/OperatorPassWithdrawalUnavailableError';
import {UnknownOperatorPassPurchaseError} from '@fluxer/errors/src/domains/operator_pass/UnknownOperatorPassPurchaseError';
import {UnknownOperatorPassUnitError} from '@fluxer/errors/src/domains/operator_pass/UnknownOperatorPassUnitError';
import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
import {OPERATOR_PASS_PHASES} from '@fluxer/schema/src/domains/operator_pass/OperatorPassSchemas';
import type {ICacheService} from '@pkgs/cache/src/ICacheService';
import type {
BillingDocumentAttachment,
BillingTotals,
EmailAttachment,
EmailSendParams,
IEmailService,
OperatorPassWithdrawalRefund,
} from '@pkgs/email/src/IEmailService';
import {OPERATOR_PASS_TERMS_VERSION} from '@pkgs/email/src/operator_pass_terms/OperatorPassTerms';
import type {IKVProvider} from '@pkgs/kv_client/src/IKVProvider';
import {ms, seconds} from 'itty-time';
import Stripe from 'stripe';
const APPLIED_TTL_SECONDS = seconds('365 days');
const WITHDRAWAL_RECEIPT_REQUEUE_AFTER_MS = ms('10 minutes');
const WITHDRAWAL_RECEIPT_ALERT_MS = ms('24 hours');
const WITHDRAWAL_RECEIPT_RETRY_MS = ms('7 days');
const OWED_CREDIT_NOTE_DELAY_MS = ms('1 hour');
const BILLING_RECORD_ATTEMPTS = 3;
interface ReturnedPassPayment {
refundId: string | null;
viaDispute: boolean;
amountMinor: number;
}
interface AcceptedWithdrawalDispute {
receivedAt: Date;
passCount: number;
amountMinor: number;
}
interface CheckoutPaymentReferences {
paymentIntentId: string | null;
}
export interface OperatorPassWithdrawParams {
purchaser: User;
purchaseId: string;
name: string;
channel: OperatorPassWithdrawalChannel;
receivedAt: Date;
}
export interface OperatorPassWithdrawalReceipt {
purchaseId: string;
passId: string | null;
recipientUserId: UserID;
name: string;
receivedAt: Date;
recordedAt: Date;
amountMinor: number;
refund: OperatorPassWithdrawalRefund;
delivered: boolean;
passCount: number;
lastPass: boolean;
visionary: boolean;
refundId: string | null;
}
export interface OperatorPassRefundReceipt {
recipient: {email: string; locale: string | null; timeZone: string | null};
params: EmailSendParams['operator_pass_refund_receipt'];
}
export const OPERATOR_PASS_WITHDRAWAL_RECEIPT_TASK = 'sendOperatorPassWithdrawalReceipt';
export const OPERATOR_PASS_DELIVERY_RECORD_TASK = 'recordOperatorPassDelivery';
function encodeOperatorPassWithdrawalReceipt(receipt: OperatorPassWithdrawalReceipt): Record<string, unknown> {
return {
purchase_id: receipt.purchaseId,
pass_id: receipt.passId ?? 'all',
recipient_user_id: receipt.recipientUserId.toString(),
name: receipt.name,
received_at: receipt.receivedAt.toISOString(),
recorded_at: receipt.recordedAt.toISOString(),
amount_minor: receipt.amountMinor,
refund: receipt.refund,
delivered: receipt.delivered,
pass_count: receipt.passCount,
last_pass: receipt.lastPass,
visionary: receipt.visionary,
refund_id: receipt.refundId ?? '',
};
}
function startedWithdrawalRefund(returned: {viaDispute: boolean}): OperatorPassWithdrawalRefund {
return returned.viaDispute ? 'dispute' : 'started';
}
function decodeWithdrawalRefund(value: unknown): OperatorPassWithdrawalRefund {
return value === 'dispute' || value === 'already' ? value : 'started';
}
export function decodeOperatorPassWithdrawalReceipt(payload: Record<string, unknown>): OperatorPassWithdrawalReceipt {
const passId = String(payload.pass_id);
return {
purchaseId: String(payload.purchase_id),
passId: passId === 'all' ? null : passId,
recipientUserId: createUserID(BigInt(String(payload.recipient_user_id))),
name: String(payload.name),
receivedAt: new Date(String(payload.received_at)),
recordedAt: new Date(String(payload.recorded_at)),
amountMinor: Number(payload.amount_minor),
refund: decodeWithdrawalRefund(payload.refund),
delivered: payload.delivered !== false,
passCount: Math.max(1, Number(payload.pass_count) || 1),
lastPass: payload.last_pass === true,
visionary: payload.visionary === true,
refundId: typeof payload.refund_id === 'string' && payload.refund_id !== '' ? payload.refund_id : null,
};
}
export interface OperatorPassUnitWithdrawParams {
holder: User;
passId: string;
name: string;
receivedAt: Date;
}
export async function recordOperatorPassDeliveryOnPayment(
stripe: Stripe | null,
purchase: Pick<
OperatorPassPurchaseRow,
'payment_intent_id' | 'checkout_session_id' | 'purchased_at' | 'withdrawal_country'
>,
deliveredAt: Date,
): Promise<void> {
if (!purchase.payment_intent_id) {
return;
}
if (!stripe) {
throw new StripeError('Stripe is not available to record the Operator Pass certificate delivery time');
}
const metadata: Record<string, string> = {
operator_pass_delivered_at: deliveredAt.toISOString(),
operator_pass_withdrawal_country: purchase.withdrawal_country ?? '',
};
if (purchase.purchased_at) {
metadata.operator_pass_paid_at = purchase.purchased_at.toISOString();
}
for (let attempt = 1; attempt <= BILLING_RECORD_ATTEMPTS; attempt++) {
try {
await stripe.paymentIntents.update(purchase.payment_intent_id, {metadata});
return;
} catch (error) {
Logger.warn(
{error, attempt, sessionId: purchase.checkout_session_id},
'Failed to record the Operator Pass certificate delivery time on the payment',
);
}
}
throw new StripeError('Could not record the Operator Pass certificate delivery time on the payment');
}
export async function syncOperatorPassDeliveryRecord(
stripe: Stripe | null,
repository: Pick<OperatorPassRepository, 'updatePurchase'>,
purchase: OperatorPassPurchaseRow,
): Promise<OperatorPassPurchaseRow> {
if (purchase.delivered_at == null || purchase.delivery_recorded_at != null) {
return purchase;
}
await recordOperatorPassDeliveryOnPayment(stripe, purchase, purchase.delivered_at);
return repository.updatePurchase(purchase, {delivery_recorded_at: Db.set(operatorPassNow())});
}
const OPERATOR_PASS_REFUSALS = [
'operator_pass_removed',
'operator_pass_names_missing',
'operator_pass_email_undeliverable',
] as const;
type OperatorPassRefusal = (typeof OPERATOR_PASS_REFUSALS)[number];
function refusalOfRefund(refund: Stripe.Refund, purchase: OperatorPassPurchaseRow): OperatorPassRefusal | null {
if (refund.metadata?.checkout_session_id !== purchase.checkout_session_id) {
return null;
}
const reason = refund.metadata?.rejection_reason ?? '';
return OPERATOR_PASS_REFUSALS.find((refusal) => refusal === reason) ?? null;
}
function alertWithdrawalReceiptNotSent(
purchase: OperatorPassPurchaseRow,
receipt: OperatorPassWithdrawalReceipt,
dedupeKey: string,
summary: string,
): Promise<void> {
return alertSupport({
dedupeKey,
subject: 'Operator Pass withdrawal receipt not sent',
summary,
facts: {
refundId: receipt.refundId,
paymentIntentId: purchase.payment_intent_id,
checkoutSessionId: purchase.checkout_session_id,
userId: receipt.recipientUserId,
documentNumber: purchase.invoice_number,
amountMinor: receipt.amountMinor,
currency: purchase.currency,
},
});
}
function alertOperatorPassRefundNotSent(
purchase: OperatorPassPurchaseRow,
refund: Stripe.Refund,
summary: string,
error: unknown = refund.failure_reason,
): Promise<void> {
return alertSupport({
dedupeKey: `operator-pass-refund:${refund.id}`,
subject: `Operator Pass refund ${refund.id} did not reach the buyer`,
summary,
facts: {
refundId: refund.id,
paymentIntentId: purchase.payment_intent_id,
checkoutSessionId: purchase.checkout_session_id,
userId: purchase.purchaser_id,
documentNumber: purchase.invoice_number,
amountMinor: refund.amount,
currency: refund.currency,
error,
},
});
}
const EMAILED_REFUSALS: ReadonlySet<OperatorPassRefusal> = new Set(['operator_pass_names_missing']);
const WITHDRAWAL_REFUND_PREFIX = 'operator_pass_withdrawal:';
const CONSUMER_ONLY_COUNTRIES: ReadonlySet<string> = new Set(['BR']);
export function isOperatorPassBusinessCheckout(session: Stripe.Checkout.Session): boolean {
const details = session.customer_details;
return Boolean(details?.business_name) || (details?.tax_ids?.length ?? 0) > 0;
}
export function resolveOperatorPassPurchaseWithdrawalRule(
session: Stripe.Checkout.Session,
purchase: Pick<OperatorPassPurchaseRow, 'withdrawal_country' | 'currency'>,
): OperatorPassWithdrawalRuleMatch | null {
if (session.metadata?.operator_pass_cnpj) {
return null;
}
const rule = resolveOperatorPassWithdrawalRule(
Config.operatorPass.withdrawalCountries,
[purchase.withdrawal_country, session.customer_details?.address?.country],
purchase.currency,
);
if (rule && CONSUMER_ONLY_COUNTRIES.has(rule.country)) {
return rule;
}
return isOperatorPassBusinessCheckout(session) ? null : rule;
}
export function isOperatorPassCheckoutSession(session: Stripe.Checkout.Session): boolean {
return session.metadata?.operator_pass === 'true';
}
interface OperatorPassFulfilmentDependencies {
stripe: Stripe | null;
userRepository: UserRepository;
emailService: IEmailService;
cacheService: ICacheService;
services: OperatorPassServices;
}
export function createOperatorPassFulfilmentService(
dependencies: OperatorPassFulfilmentDependencies,
): OperatorPassFulfilmentService | null {
if (Config.instance.selfHosted) {
return null;
}
return new OperatorPassFulfilmentService(
dependencies.stripe,
dependencies.services.repository,
dependencies.userRepository,
dependencies.emailService,
dependencies.cacheService,
getKVClient(),
dependencies.services,
);
}
export class OperatorPassFulfilmentService {
readonly wallService: OperatorPassWallService;
readonly holdingService: OperatorPassHoldingService;
readonly certificates: OperatorPassCertificateService;
readonly visionary: OperatorPassVisionaryService;
constructor(
private readonly stripe: Stripe | null,
readonly repository: OperatorPassRepository,
private readonly userRepository: UserRepository,
private readonly emailService: IEmailService,
private readonly cacheService: ICacheService,
kvClient: IKVProvider,
private readonly services: OperatorPassServices,
private readonly documents: BillingDocumentService | null = createBillingDocumentService(stripe),
) {
this.wallService = services.wallService;
this.holdingService = services.holdingService;
this.certificates = new OperatorPassCertificateService(repository, cacheService, kvClient);
this.visionary = new OperatorPassVisionaryService({
repository,
userRepository,
holdingService: services.holdingService,
wallService: services.wallService,
roleService: services.roleService,
certificates: this.certificates,
emailService,
cacheService,
});
}
get removalService(): OperatorPassServices['removalService'] {
return this.services.removalService;
}
async handleCheckoutSessionCompleted(session: Stripe.Checkout.Session): Promise<void> {
if (session.payment_status === 'unpaid') {
Logger.info(
{sessionId: session.id, paymentStatus: session.payment_status},
'Operator Pass checkout completed with unpaid status; deferring fulfilment until settlement',
);
return;
}
await this.fulfilCheckoutSession(session, null);
}
async handleAsyncPaymentSucceeded(session: Stripe.Checkout.Session, paidAt: Date): Promise<void> {
await this.fulfilCheckoutSession(session, paidAt);
}
async handleCheckoutSessionExpired(session: Stripe.Checkout.Session): Promise<void> {
await this.withPurchaseLock(session.id, async () => {
const purchase = await this.repository.findPurchase(session.id);
if (purchase?.status !== 'pending') {
return;
}
await this.repository.deletePurchase(purchase);
Logger.info(
{sessionId: session.id, purchaserId: purchase.purchaser_id},
'Deleted the pending Operator Pass purchase of an expired checkout session',
);
});
}
async handleAsyncPaymentFailed(session: Stripe.Checkout.Session): Promise<void> {
await this.withPurchaseLock(session.id, async () => {
const purchase = await this.repository.findPurchase(session.id);
if (purchase?.status !== 'pending' || purchase.purchased_at != null) {
return;
}
await this.repository.deletePurchase(purchase);
Logger.warn(
{sessionId: session.id, purchaserId: purchase.purchaser_id, paymentStatus: session.payment_status},
'Deleted the pending Operator Pass purchase of a failed async payment',
);
});
}
async findPurchaseByPaymentIntent(paymentIntentId: string): Promise<OperatorPassPurchaseRow | null> {
return this.repository.findPurchaseByPaymentIntent(paymentIntentId);
}
async findRefundedPurchase(
paymentIntentId: string,
operatorPassPayment: boolean,
): Promise<OperatorPassPurchaseRow | null> {
const purchase = await this.repository.findPurchaseByPaymentIntent(paymentIntentId);
if (purchase) {
return this.settlePendingPurchase(purchase);
}
if (!this.stripe || !operatorPassPayment) {
return null;
}
const sessions = await this.stripe.checkout.sessions.list({payment_intent: paymentIntentId, limit: 1});
const session = sessions.data[0];
if (session?.metadata?.operator_pass !== 'true') {
return null;
}
return this.settleCheckoutSession(session);
}
async settlePendingPurchase(purchase: OperatorPassPurchaseRow): Promise<OperatorPassPurchaseRow> {
if (purchase.status !== 'pending' || !this.stripe) {
return purchase;
}
const session = await this.stripe.checkout.sessions.retrieve(purchase.checkout_session_id);
return (await this.settleCheckoutSession(session)) ?? purchase;
}
async settleReturnedCheckout(purchaserId: UserID, sessionId: string): Promise<void> {
const purchase = await this.repository.findPurchase(sessionId);
if (purchase?.purchaser_id !== purchaserId || purchase.status !== 'pending') {
return;
}
try {
await this.settlePendingPurchase(purchase);
} catch (error) {
Logger.warn(
{error, sessionId},
'Could not fulfil a returned Operator Pass checkout right away; the webhook or the sweep will',
);
}
}
private async settleCheckoutSession(session: Stripe.Checkout.Session): Promise<OperatorPassPurchaseRow | null> {
if (session.payment_status !== 'unpaid') {
await this.fulfilCheckoutSession(session, null);
}
return this.repository.findPurchase(session.id);
}
async markFraudWarning(paymentIntentId: string): Promise<void> {
const purchase =
(await this.repository.findPurchaseByPaymentIntent(paymentIntentId)) ??
(await this.findPurchaseBySessionPaymentIntent(paymentIntentId));
if (!purchase || purchase.fraud_warning_at) {
return;
}
await this.withCurrentPurchase(purchase, (current) =>
this.repository.updatePurchase(current, {fraud_warning_at: Db.set(operatorPassNow())}),
);
}
private async findPurchaseBySessionPaymentIntent(paymentIntentId: string): Promise<OperatorPassPurchaseRow | null> {
if (!this.stripe) {
return null;
}
const sessions = await this.stripe.checkout.sessions.list({payment_intent: paymentIntentId, limit: 1});
const session = sessions.data[0];
return session?.metadata?.operator_pass === 'true' ? this.repository.findPurchase(session.id) : null;
}
async listPurchases(purchaserId: UserID): Promise<Array<OperatorPassPurchaseRow>> {
const purchases = await this.repository.listPurchasesByPurchaser(purchaserId);
return purchases
.filter((purchase) => purchase.status !== 'pending' || purchase.purchased_at != null)
.sort((left, right) => right.created_at.getTime() - left.created_at.getTime());
}
async handleChargeRefunded(purchase: OperatorPassPurchaseRow, charge: Stripe.Charge): Promise<void> {
await this.withCurrentPurchase(purchase, async (current) => {
if (current.status === 'pending') {
Logger.info(
{sessionId: current.checkout_session_id, chargeId: charge.id},
'Operator Pass refund arrived before fulfilment finished, so the webhook job retries it',
);
throw new StripeError('Operator Pass purchase is not fulfilled yet; retrying the refund');
}
await this.handleChargeRefundedLocked(current, charge);
if (this.stripe && this.documents) {
await creditOperatorPassRefunds(this.stripe, this.documents, current);
}
});
}
private async creditRefundsMadeHere(purchase: OperatorPassPurchaseRow): Promise<void> {
if (!this.stripe || !this.documents) return;
try {
await creditOperatorPassRefunds(this.stripe, this.documents, purchase);
} catch (error) {
Logger.error(
{error, sessionId: purchase.checkout_session_id},
'Could not issue the credit note for an Operator Pass refund; the charge.refunded webhook will retry',
);
}
}
async handleDisputeCreated(purchase: OperatorPassPurchaseRow, dispute: Stripe.Dispute): Promise<void> {
await this.withCurrentPurchase(purchase, (current) => this.handleDisputeCreatedLocked(current, dispute));
}
async handleDisputeReleased(purchase: OperatorPassPurchaseRow, dispute: Stripe.Dispute): Promise<void> {
await this.withCurrentPurchase(purchase, (current) => this.handleDisputeReleasedLocked(current, dispute));
}
async handleDisputeLost(
purchase: OperatorPassPurchaseRow,
dispute: Stripe.Dispute,
): Promise<OperatorPassPurchaseRow> {
return this.withCurrentPurchase(purchase, (current) => this.handleDisputeLostLocked(current, dispute));
}
private async handleChargeRefundedLocked(purchase: OperatorPassPurchaseRow, charge: Stripe.Charge): Promise<void> {
if (
purchase.status === 'duplicate_refunded' ||
purchase.status === 'withdrawn' ||
purchase.status === 'dispute_lost'
) {
Logger.debug(
{sessionId: purchase.checkout_session_id, status: purchase.status, chargeId: charge.id},
'Operator Pass refund already handled',
);
return;
}
const passRefunded = charge.refunded ? purchase.amount_minor : charge.amount_refunded;
const quantity = Math.max(1, purchase.quantity ?? 1);
if (passRefunded < purchase.amount_minor) {
const unitAmount = Math.round(purchase.amount_minor / quantity);
const units = await this.repository.listUnitsByPurchase(purchase.checkout_session_id);
const ended = units.filter(isOperatorPassCertificatePageCancelled).length;
const covered = unitAmount > 0 ? Math.floor(passRefunded / unitAmount) : 0;
const toEnd = Math.max(0, covered - ended);
if (toEnd > 0) {
await this.holdingService.endPurchaseUnits(purchase, 'refund', 'revoked', toEnd);
}
await this.certificates.cancelReversedPages(purchase, 'refund', covered);
const cancelled = (await this.repository.listUnitsByPurchase(purchase.checkout_session_id)).filter(
isOperatorPassCertificatePageCancelled,
).length;
if (cancelled >= quantity) {
await this.markRefunded(purchase);
}
Logger.info(
{
sessionId: purchase.checkout_session_id,
chargeId: charge.id,
amountRefunded: charge.amount_refunded,
passRefunded,
passAmount: purchase.amount_minor,
revoked: toEnd,
cancelled,
},
'Partial refund of an Operator Pass purchase; revoked the passes it covers',
);
return;
}
await this.revokeWholePurchase(purchase);
Logger.info(
{sessionId: purchase.checkout_session_id, purchaserId: purchase.purchaser_id},
'Operator Pass revoked after a refund',
);
}
private async revokeWholePurchase(purchase: OperatorPassPurchaseRow): Promise<void> {
await this.holdingService.endPurchaseUnits(purchase, 'refund', 'revoked');
await this.certificates.cancelReversedPages(purchase, 'refund');
await this.markRefunded(purchase);
}
private async markRefunded(purchase: OperatorPassPurchaseRow): Promise<void> {
if (purchase.status === 'refunded') {
return;
}
await this.repository.updatePurchase(purchase, {status: Db.set('refunded'), refunded_at: Db.set(new Date())});
await this.reviewBusinessListing(purchase);
}
private async reviewBusinessListing(purchase: OperatorPassPurchaseRow): Promise<void> {
const userId = purchase.purchaser_id;
if (!(await this.wallService.getEntry(userId))?.live_business) {
return;
}
let qualifying: OperatorPassPurchaseRow | null = null;
if (this.stripe) {
try {
qualifying = await findOperatorPassBusinessPurchase({
stripe: this.stripe,
repository: this.repository,
userId,
now: operatorPassNow(),
});
} catch (error) {
Logger.warn({error, userId}, 'Could not check a business listing again, so it goes back to personal');
}
}
if (!qualifying) {
await this.wallService.endBusinessListing(userId);
}
}
private async applyRefundsMadeElsewhere(purchase: OperatorPassPurchaseRow): Promise<OperatorPassPurchaseRow> {
if (!this.stripe || !purchase.payment_intent_id || !['completed', 'disputed'].includes(purchase.status)) {
return purchase;
}
const intent = await this.stripe.paymentIntents.retrieve(purchase.payment_intent_id, {expand: ['latest_charge']});
const charge = typeof intent.latest_charge === 'object' ? intent.latest_charge : null;
if (!charge || charge.amount_refunded === 0) {
return purchase;
}
await this.handleChargeRefundedLocked(purchase, charge);
return (await this.repository.findPurchase(purchase.checkout_session_id)) ?? purchase;
}
private async handleDisputeCreatedLocked(purchase: OperatorPassPurchaseRow, dispute: Stripe.Dispute): Promise<void> {
const disputeFields = {
dispute_id: Db.set(dispute.id),
dispute_reason: Db.set(dispute.reason ?? null),
dispute_status: Db.set(dispute.status),
disputed_at: Db.set(purchase.disputed_at ?? new Date(dispute.created * 1000)),
};
if (purchase.dispute_id === dispute.id && purchase.dispute_closed_at != null) {
Logger.info(
{sessionId: purchase.checkout_session_id, status: purchase.status, disputeId: dispute.id},
'Dispute opened event arrived after the dispute closed; leaving the Operator Pass as it is',
);
return;
}
if (purchase.status !== 'completed') {
Logger.info(
{sessionId: purchase.checkout_session_id, status: purchase.status, disputeId: dispute.id},
'Dispute on an Operator Pass purchase that has no active pass to pause',
);
await this.repository.updatePurchase(purchase, disputeFields);
return;
}
await this.holdingService.setPurchasePaused(purchase, true);
await this.repository.updatePurchase(purchase, {...disputeFields, status: Db.set('disputed')});
await this.reviewBusinessListing(purchase);
Logger.info(
{sessionId: purchase.checkout_session_id, purchaserId: purchase.purchaser_id, disputeId: dispute.id},
'Operator Pass paused while a payment dispute is open',
);
}
private async handleDisputeReleasedLocked(purchase: OperatorPassPurchaseRow, dispute: Stripe.Dispute): Promise<void> {
if (purchase.status !== 'disputed') {
Logger.debug(
{sessionId: purchase.checkout_session_id, status: purchase.status, disputeId: dispute.id},
'Closed dispute on an Operator Pass purchase that the dispute did not pause',
);
const current = await this.repository.updatePurchase(purchase, {
dispute_id: Db.set(dispute.id),
dispute_status: Db.set(dispute.status),
dispute_closed_at: Db.set(new Date()),
});
await this.sendDueWelcome(current);
return;
}
const updated = await this.repository.updatePurchase(purchase, {
status: Db.set('completed'),
dispute_status: Db.set(dispute.status),
dispute_closed_at: Db.set(new Date()),
});
await this.holdingService.setPurchasePaused(updated, false);
Logger.info(
{sessionId: purchase.checkout_session_id, purchaserId: purchase.purchaser_id, disputeStatus: dispute.status},
'Operator Pass restored after a payment dispute closed without the money being returned',
);
await this.sendDueWelcome(updated);
}
private async sendDueWelcome(purchase: OperatorPassPurchaseRow): Promise<void> {
if (purchase.status !== 'completed' || purchase.delivered_at == null || isOperatorPassWelcomeSettled(purchase)) {
return;
}
const purchaser = await this.userRepository.findUnique(purchase.purchaser_id);
if (!purchaser) {
Logger.error(
{sessionId: purchase.checkout_session_id, userId: purchase.purchaser_id},
'Operator Pass purchaser not found for the certificate email',
);
return;
}
try {
await this.sendWelcomeOnce(purchase, purchaser);
} catch (error) {
Logger.warn(
{error, sessionId: purchase.checkout_session_id},
'Operator Pass certificate email failed after a dispute closed, the fulfilment sweep will retry it',
);
}
}
private async handleDisputeLostLocked(
purchase: OperatorPassPurchaseRow,
dispute: Stripe.Dispute,
): Promise<OperatorPassPurchaseRow> {
if (purchase.status === 'dispute_lost') {
await this.certificates.cancelReversedPages(purchase, 'dispute');
return purchase;
}
const active = purchase.status === 'disputed' || purchase.status === 'completed';
if (active) {
await this.holdingService.endPurchaseUnits(purchase, 'dispute', 'revoked');
}
await this.certificates.cancelReversedPages(purchase, 'dispute');
const updated = await this.repository.updatePurchase(purchase, {
status: Db.set(active || purchase.status === 'pending' ? 'dispute_lost' : purchase.status),
dispute_id: Db.set(dispute.id),
dispute_reason: Db.set(dispute.reason ?? null),
dispute_status: Db.set(dispute.status),
disputed_at: Db.set(purchase.disputed_at ?? new Date(dispute.created * 1000)),
dispute_closed_at: Db.set(new Date()),
});
await this.reviewBusinessListing(purchase);
Logger.info(
{sessionId: purchase.checkout_session_id, purchaserId: purchase.purchaser_id, disputeId: dispute.id},
'Operator Pass ended after a payment dispute returned the money',
);
return updated;
}
async withdraw({
purchaser,
purchaseId,
name,
channel,
receivedAt: requestedAt,
}: OperatorPassWithdrawParams): Promise<OperatorPassPurchaseRow> {
const found = await this.repository.findPurchase(purchaseId);
if (!found || found.purchaser_id !== purchaser.id) {
throw new UnknownOperatorPassPurchaseError();
}
return this.withPurchaseLock(
purchaseId,
async () => {
const purchase = await this.applyRefundsMadeElsewhere(
(await this.repository.findPurchase(purchaseId)) ?? found,
);
const accepted = await this.findAcceptedWithdrawalDispute(purchase);
const receivedAt = accepted?.receivedAt ?? requestedAt;
const refundedBefore = purchase.status === 'refunded' && channel !== 'button';
const units = await this.repository.listUnitsByPurchase(purchase.checkout_session_id);
const undeliveredAtReceipt =
channel !== 'button' && !refundedBefore && wasOperatorPassPurchaseUndeliveredAt(purchase, receivedAt);
const heldUnits = units.filter((unit) => unit.status === 'held');
const withdrawableUnits = undeliveredAtReceipt
? heldUnits.filter((unit) => unit.holder_id === purchase.purchaser_id)
: listOperatorPassWithdrawableUnits(purchase, units, receivedAt);
const movedUnits = undeliveredAtReceipt
? heldUnits.filter((unit) => unit.holder_id !== purchase.purchaser_id)
: await this.listUnitsPassedOnAfterReceipt(purchase, units, receivedAt, channel, refundedBefore);
const withinPeriod =
accepted !== null ||
(refundedBefore
? isOperatorPassWithinWithdrawalDeadline(purchase, receivedAt)
: undeliveredAtReceipt ||
isOperatorPassPurchaseWithdrawable(purchase, units, receivedAt) ||
withdrawableUnits.length + movedUnits.length > 0);
if (!withinPeriod || !purchase.payment_intent_id) {
throw new OperatorPassWithdrawalUnavailableError();
}
const quantity = Math.max(1, purchase.quantity ?? 1);
const unitPrice = Math.round(purchase.amount_minor / quantity);
const refundedUnits = units.filter((unit) => unit.end_reason === 'refund').length;
let amountMinor = purchase.amount_minor;
let passCount = quantity;
if (accepted) {
amountMinor = accepted.amountMinor;
passCount = accepted.passCount;
} else if (refundedBefore) {
if (refundedUnits > 0 && refundedUnits < quantity) {
amountMinor = unitPrice * refundedUnits;
passCount = refundedUnits;
}
} else if (undeliveredAtReceipt) {
if (refundedUnits > 0) amountMinor = unitPrice * (quantity - refundedUnits);
if (units.length > 0) passCount = withdrawableUnits.length + movedUnits.length;
} else if (units.length > 0) {
amountMinor = unitPrice * (withdrawableUnits.length + movedUnits.length);
passCount = withdrawableUnits.length + movedUnits.length;
}
let returned: ReturnedPassPayment | null = null;
if (accepted) {
returned = {refundId: null, viaDispute: true, amountMinor};
} else if (!refundedBefore) {
returned = await this.returnPassPayment(purchase, amountMinor, `all:${receivedAt.toISOString()}`, {
receivedAt,
passCount,
});
}
if (returned?.refundId) {
await this.creditRefundsMadeHere(purchase);
}
if (!refundedBefore) {
await this.holdingService.endPurchaseUnits(
purchase,
'withdrawal',
'withdrawn',
Number.POSITIVE_INFINITY,
units.length === 0 ? null : new Set(withdrawableUnits.map((unit) => unit.pass_id)),
);
if (movedUnits.length > 0) {
await this.holdingService.endPurchaseUnits(
purchase,
'withdrawal',
'revoked',
Number.POSITIVE_INFINITY,
new Set(movedUnits.map((unit) => unit.pass_id)),
);
}
await this.certificates.syncCancellations(purchase);
}
const remaining = (await this.repository.listUnitsByPurchase(purchase.checkout_session_id)).filter(
(unit) => unit.status === 'held',
);
const receipt: OperatorPassWithdrawalReceipt = {
purchaseId: purchase.checkout_session_id,
passId: null,
recipientUserId: purchaser.id,
name,
receivedAt,
recordedAt: operatorPassNow(),
amountMinor: returned?.amountMinor ?? amountMinor,
refund: returned ? startedWithdrawalRefund(returned) : 'already',
delivered: purchase.delivered_at != null || units.length > 0,
passCount: Math.max(1, passCount),
lastPass: (await this.holdingService.queries.listHeldUnits(purchaser.id)).length === 0,
visionary: keepsOperatorsThroughVisionary(purchaser),
refundId: returned?.refundId ?? null,
};
const withdrawn = await this.repository.updatePurchase(purchase, {
...(remaining.length === 0
? {status: Db.set('withdrawn'), refunded_at: Db.set(purchase.refunded_at ?? new Date())}
: {}),
...(remaining.length === 0 && purchase.delivered_at == null
? {certificate_names: Db.clear(), wall_name: Db.clear()}
: {}),
withdrawn_at: Db.set(receivedAt),
withdrawal_name: Db.set(name),
withdrawal_refund_id: Db.set(returned?.refundId ?? null),
withdrawal_channel: Db.set(channel),
withdrawal_receipts_owed: Db.set(withOwedWithdrawalReceipt(purchase, receipt)),
});
await this.reviewBusinessListing(purchase);
Logger.info(
{sessionId: purchase.checkout_session_id, purchaserId: purchaser.id, channel},
'Operator Pass purchase withdrawn',
);
await this.queueWithdrawalReceipt(receipt);
return withdrawn;
},
purchaseBusyError,
);
}
async withdrawUnit({holder, passId, name, receivedAt}: OperatorPassUnitWithdrawParams): Promise<OperatorPassUnitRow> {
const unit = await this.repository.findUnit(passId);
if (!unit || unit.holder_id !== holder.id || !unit.purchase_id) {
throw new UnknownOperatorPassUnitError();
}
const purchaseId = unit.purchase_id;
return this.withPurchaseLock(
purchaseId,
async () => {
const found = await this.repository.findPurchase(purchaseId);
const purchase = found ? await this.applyRefundsMadeElsewhere(found) : null;
const current = await this.repository.findUnit(passId);
if (!purchase || !current || purchase.purchaser_id !== holder.id) {
throw new UnknownOperatorPassUnitError();
}
if (!isOperatorPassSinglePassWithdrawable(purchase, current, receivedAt) || !purchase.payment_intent_id) {
throw new OperatorPassWithdrawalUnavailableError();
}
const amountMinor = Math.round(purchase.amount_minor / Math.max(1, purchase.quantity ?? 1));
const returned = await this.returnPassPayment(purchase, amountMinor, current.pass_id, null);
if (returned.refundId) {
await this.creditRefundsMadeHere(purchase);
}
await this.holdingService.withdrawUnit(current, purchase);
await this.certificates.syncCancellations(purchase);
const remaining = (await this.repository.listUnitsByPurchase(purchaseId)).filter(
(unit) => unit.status === 'held',
);
const receipt: OperatorPassWithdrawalReceipt = {
purchaseId,
passId,
recipientUserId: holder.id,
name,
receivedAt,
recordedAt: operatorPassNow(),
amountMinor: returned.amountMinor,
refund: startedWithdrawalRefund(returned),
delivered: true,
passCount: 1,
lastPass: (await this.holdingService.queries.listHeldUnits(holder.id)).length === 0,
visionary: keepsOperatorsThroughVisionary(holder),
refundId: returned.refundId,
};
await this.repository.updatePurchase(purchase, {
...(remaining.length === 0
? {status: Db.set('withdrawn'), refunded_at: Db.set(purchase.refunded_at ?? new Date())}
: {}),
withdrawn_at: Db.set(receivedAt),
withdrawal_name: Db.set(name),
withdrawal_refund_id: Db.set(returned.refundId),
withdrawal_channel: Db.set('button'),
withdrawal_receipts_owed: Db.set(withOwedWithdrawalReceipt(purchase, receipt)),
});
await this.reviewBusinessListing(purchase);
Logger.info({sessionId: purchaseId, passId, holderId: holder.id}, 'Operator Pass withdrawn');
await this.queueWithdrawalReceipt(receipt);
return (await this.repository.findUnit(passId)) ?? current;
},
purchaseBusyError,
);
}
private async returnPassPayment(
purchase: OperatorPassPurchaseRow,
amountMinor: number,
idempotencyScope: string,
acceptance: Omit<AcceptedWithdrawalDispute, 'amountMinor'> | null,
): Promise<ReturnedPassPayment> {
try {
const refund = await this.refundPassAmount(
purchase,
amountMinor,
`${WITHDRAWAL_REFUND_PREFIX}${idempotencyScope}`,
);
return {refundId: refund.id, viaDispute: false, amountMinor};
} catch (error) {
if (
!acceptance ||
purchase.status !== 'disputed' ||
!purchase.dispute_id ||
!isChargeDisputedError(error) ||
!this.stripe
) {
throw error;
}
const current = await this.stripe.disputes.retrieve(purchase.dispute_id);
const dispute = current.status === 'lost' ? current : await this.stripe.disputes.close(purchase.dispute_id);
await this.cacheService.set(
withdrawalDisputeAcceptedKey(purchase.dispute_id),
{
receivedAt: acceptance.receivedAt.toISOString(),
passCount: acceptance.passCount,
amountMinor: dispute.amount,
},
APPLIED_TTL_SECONDS,
);
Logger.info(
{sessionId: purchase.checkout_session_id, disputeId: purchase.dispute_id, closedBefore: dispute === current},
'Accepted the payment dispute so the withdrawal returns the money',
);
return {refundId: null, viaDispute: true, amountMinor: dispute.amount};
}
}
private async findAcceptedWithdrawalDispute(
purchase: OperatorPassPurchaseRow,
): Promise<AcceptedWithdrawalDispute | null> {
if (!purchase.dispute_id || purchase.withdrawn_at != null) {
return null;
}
const stored = await this.cacheService.get<Record<string, unknown>>(
withdrawalDisputeAcceptedKey(purchase.dispute_id),
);
if (
!stored ||
typeof stored.receivedAt !== 'string' ||
typeof stored.passCount !== 'number' ||
typeof stored.amountMinor !== 'number'
) {
return null;
}
return {receivedAt: new Date(stored.receivedAt), passCount: stored.passCount, amountMinor: stored.amountMinor};
}
private async listUnitsPassedOnAfterReceipt(
purchase: OperatorPassPurchaseRow,
units: ReadonlyArray<OperatorPassUnitRow>,
receivedAt: Date,
channel: OperatorPassWithdrawalChannel,
refundedBefore: boolean,
): Promise<Array<OperatorPassUnitRow>> {
if (
channel === 'button' ||
refundedBefore ||
purchase.withdrawal_days == null ||
!['completed', 'disputed'].includes(purchase.status) ||
!isOperatorPassWithinWithdrawalDeadline(purchase, receivedAt)
) {
return [];
}
const moved: Array<OperatorPassUnitRow> = [];
for (const unit of units) {
if (unit.status !== 'held' || unit.source !== 'transfer' || unit.holder_id === purchase.purchaser_id) {
continue;
}
const events = await this.repository.listUnitEvents(unit.pass_id);
const passedOn = events.find(
(event) => event.kind === 'transferred' && event.sender_id === purchase.purchaser_id,
);
if (passedOn && passedOn.occurred_at.getTime() > receivedAt.getTime()) {
moved.push(unit);
}
}
return moved;
}
private async queueWithdrawalReceipt(receipt: OperatorPassWithdrawalReceipt): Promise<void> {
try {
await getWorkerService().addJob(
OPERATOR_PASS_WITHDRAWAL_RECEIPT_TASK,
encodeOperatorPassWithdrawalReceipt(receipt),
{
jobKey: withdrawalReceiptKey(receipt),
},
);
} catch (error) {
Logger.error(
{error, sessionId: receipt.purchaseId},
'Could not queue the Operator Pass withdrawal receipt, sending it directly',
);
try {
await this.sendWithdrawalReceipt(receipt);
} catch (sendError) {
Logger.error(
{error: sendError, sessionId: receipt.purchaseId},
'Failed to send the Operator Pass withdrawal receipt',
);
}
}
}
async requeueOwedWithdrawalReceipts(purchase: OperatorPassPurchaseRow, now: Date): Promise<void> {
for (const [key, encoded] of purchase.withdrawal_receipts_owed ?? []) {
if ((await this.cacheService.get<boolean>(withdrawalReceiptSentKey(key))) === true) {
await this.settleWithdrawalReceipt(purchase.checkout_session_id, key);
continue;
}
const receipt = decodeOperatorPassWithdrawalReceipt(JSON.parse(encoded) as Record<string, unknown>);
const ageMs = now.getTime() - receipt.recordedAt.getTime();
if (ageMs < WITHDRAWAL_RECEIPT_REQUEUE_AFTER_MS) {
continue;
}
if (ageMs >= WITHDRAWAL_RECEIPT_RETRY_MS) {
Logger.error(
{sessionId: purchase.checkout_session_id, receipt: key},
'Operator Pass withdrawal receipt was never sent, giving up a week after the withdrawal was recorded',
);
await alertWithdrawalReceiptNotSent(
purchase,
receipt,
`withdrawal-receipt-given-up:${key}`,
'An Operator Pass withdrawal receipt was never sent, and the code stopped retrying it a week after the withdrawal. Send the buyer the withdrawal confirmation by hand.',
);
await this.settleWithdrawalReceipt(purchase.checkout_session_id, key);
continue;
}
if (ageMs >= WITHDRAWAL_RECEIPT_ALERT_MS) {
Logger.error(
{sessionId: purchase.checkout_session_id, receipt: key},
'Operator Pass withdrawal receipt is still not sent a day after the withdrawal was recorded',
);
await alertWithdrawalReceiptNotSent(
purchase,
receipt,
`withdrawal-receipt-late:${key}`,
'An Operator Pass withdrawal receipt is still not sent a day after the withdrawal. The code keeps retrying for a week, but the buyer is waiting for the confirmation.',
);
}
await this.queueWithdrawalReceipt(receipt);
}
}
private async settleWithdrawalReceipt(purchaseId: string, key: string): Promise<void> {
try {
await this.withPurchaseLock(purchaseId, async () => {
const current = await this.repository.findPurchase(purchaseId);
if (!current?.withdrawal_receipts_owed?.has(key)) {
return;
}
const owed = new Map(current.withdrawal_receipts_owed);
owed.delete(key);
await this.repository.updatePurchase(current, {
withdrawal_receipts_owed: owed.size > 0 ? Db.set(owed) : Db.clear(),
});
});
} catch (error) {
Logger.warn(
{error, sessionId: purchaseId, receipt: key},
'Could not mark the Operator Pass withdrawal receipt as sent, the fulfilment sweep will',
);
}
}
async sendWithdrawalReceipt(receipt: OperatorPassWithdrawalReceipt, waitForRefund = false): Promise<void> {
const key = withdrawalReceiptKey(receipt);
if ((await this.cacheService.get<boolean>(withdrawalReceiptSentKey(key))) === true) {
await this.settleWithdrawalReceipt(receipt.purchaseId, key);
return;
}
const purchase = await this.repository.findPurchase(receipt.purchaseId);
if (!purchase) {
Logger.error({sessionId: receipt.purchaseId}, 'No purchase for the Operator Pass withdrawal receipt');
return;
}
const recipient = await this.userRepository.findUnique(receipt.recipientUserId);
const email = recipient?.email ?? (await this.findCheckoutEmail(purchase.checkout_session_id));
if (!email) {
Logger.error({sessionId: purchase.checkout_session_id}, 'No address for the Operator Pass withdrawal receipt');
return;
}
if (await this.emailService.isEmailBounced(email)) {
Logger.warn(
{sessionId: purchase.checkout_session_id, receipt: key},
'Operator Pass withdrawal receipt address has bounced; skipping the receipt',
);
await this.cacheService.set(withdrawalReceiptSentKey(key), true, APPLIED_TTL_SECONDS);
await this.settleWithdrawalReceipt(purchase.checkout_session_id, key);
return;
}
let creditNote: BillingDocumentAttachment | null;
try {
creditNote = await this.loadWithdrawalCreditNote(purchase, receipt.refundId, waitForRefund);
} catch (error) {
if (waitForRefund) {
throw error;
}
Logger.warn(
{error, sessionId: purchase.checkout_session_id, refundId: receipt.refundId},
'Sending the Operator Pass withdrawal receipt without its credit note, which stays owed',
);
creditNote = null;
}
if (receipt.refundId && this.documents && this.stripe) {
const owedKey = withdrawalCreditNoteOwedKey(receipt.refundId);
if (creditNote) {
await this.cacheService.delete(owedKey);
} else {
await this.cacheService.set(owedKey, encodeOperatorPassWithdrawalReceipt(receipt), APPLIED_TTL_SECONDS);
try {
await enqueueBillingEmail(
getWorkerService(),
{kind: 'refund', id: receipt.refundId},
{keySuffix: 'credit-note-owed', runAt: new Date(Date.now() + OWED_CREDIT_NOTE_DELAY_MS)},
);
} catch (error) {
Logger.error(
{error, sessionId: purchase.checkout_session_id, refundId: receipt.refundId},
'Could not queue the owed credit note of an Operator Pass withdrawal',
);
}
}
}
const sent = await this.emailService.send(
'operator_pass_withdrawal_receipt',
email,
{
name: receipt.name,
receivedAt: receipt.receivedAt,
invoiceNumber: purchase.invoice_number ?? null,
orderDate: purchase.purchased_at ?? purchase.created_at,
amountMinor: receipt.amountMinor,
currency: purchase.currency,
delivered: receipt.delivered,
passCount: receipt.passCount,
lastPass: receipt.lastPass,
visionary: receipt.visionary,
refund: receipt.refund,
creditNote,
timeZone: recipient?.timezone ?? null,
},
recipient?.locale ?? null,
);
if (!sent) {
throw new Error('Failed to send the Operator Pass withdrawal receipt');
}
await this.cacheService.set(withdrawalReceiptSentKey(key), true, APPLIED_TTL_SECONDS);
await this.settleWithdrawalReceipt(purchase.checkout_session_id, key);
}
private async loadWithdrawalCreditNote(
purchase: OperatorPassPurchaseRow,
refundId: string | null,
waitForRefund: boolean,
): Promise<BillingDocumentAttachment | null> {
if (!refundId || !this.stripe || !this.documents) {
return null;
}
const refund = await this.findWithdrawalRefundInEffect(this.stripe, refundId);
if (
waitForRefund &&
(refund.status === 'pending' || refund.status === 'requires_action' || refund.status === 'failed')
) {
throw new Error('The Operator Pass withdrawal refund has not settled yet, so its credit note does not exist yet');
}
return this.loadRefundCreditNote(purchase, refund);
}
private async findWithdrawalRefundInEffect(stripe: Stripe, refundId: string): Promise<Stripe.Refund> {
const refund = await stripe.refunds.retrieve(refundId);
const paymentIntentId = extractId(refund.payment_intent ?? null);
if (refund.status !== 'failed' || !paymentIntentId) {
return refund;
}
const refunds = await stripe.refunds.list({payment_intent: paymentIntentId, limit: 100});
return refunds.data.find((candidate) => candidate.metadata?.retry_of === refund.id) ?? refund;
}
private async countPassesCoveredByRefund(purchase: OperatorPassPurchaseRow, refund: Stripe.Refund): Promise<number> {
const quantity = Math.max(1, purchase.quantity ?? 1);
const unitPrice = Math.round(purchase.amount_minor / quantity);
const covered = (refunded: number) => {
if (refunded >= purchase.amount_minor) return quantity;
return unitPrice > 0 ? Math.min(quantity, Math.floor(refunded / unitPrice)) : 0;
};
if (!this.stripe || !purchase.payment_intent_id) {
return covered(refund.amount);
}
const refunds = await this.stripe.refunds.list({payment_intent: purchase.payment_intent_id, limit: 100});
const counted = refunds.data
.filter(
(candidate) => candidate.status === 'succeeded' || candidate.status === 'pending' || candidate.id === refund.id,
)
.sort((left, right) => left.created - right.created || left.id.localeCompare(right.id));
let before = 0;
for (const candidate of counted) {
if (candidate.id === refund.id) {
return Math.max(0, covered(before + refund.amount) - covered(before));
}
before += candidate.amount;
}
return Math.max(0, covered(before + refund.amount) - covered(before));
}
async prepareRefundReceipt(
found: OperatorPassPurchaseRow,
refund: Stripe.Refund,
): Promise<OperatorPassRefundReceipt | null> {
const applied = await this.withCurrentPurchase(found, async (current) => {
if (await this.refundSendsItsOwnEmail(current, refund)) {
if (this.stripe && this.documents) {
await creditOperatorPassRefunds(this.stripe, this.documents, current);
}
return {purchase: current, units: null};
}
const purchase = await this.applyRefundsMadeElsewhere(current);
return {purchase, units: await this.repository.listUnitsByPurchase(purchase.checkout_session_id)};
});
if (!applied) {
return null;
}
const {purchase, units} = applied;
if (!units) {
return this.prepareOwedWithdrawalCreditNote(purchase, refund);
}
const purchaser = await this.userRepository.findUnique(purchase.purchaser_id);
if (!purchaser?.email || purchaser.emailBounced) {
Logger.warn({refundId: refund.id}, 'No deliverable purchaser email for an Operator Pass refund');
return null;
}
const quantity = Math.max(1, purchase.quantity ?? 1);
const endedByRefund = units.filter((unit) => unit.end_reason === 'refund').length;
const endedThisRefund = Math.min(endedByRefund, await this.countPassesCoveredByRefund(purchase, refund));
const delivered = purchase.delivered_at != null;
return {
recipient: {email: purchaser.email, locale: purchaser.locale, timeZone: purchaser.timezone},
params: {
invoiceNumber: purchase.invoice_number ?? null,
orderDate: purchase.purchased_at ?? purchase.created_at,
refundedAt: new Date(refund.created * 1000),
amountMinor: refund.amount,
currency: refund.currency,
delivered,
passCount: delivered ? endedThisRefund : quantity,
lastPass: (await this.holdingService.queries.listHeldUnits(purchaser.id)).length === 0,
visionary: keepsOperatorsThroughVisionary(purchaser),
creditNote: await this.loadRefundCreditNote(purchase, refund),
timeZone: purchaser.timezone,
},
};
}
private async prepareOwedWithdrawalCreditNote(
purchase: OperatorPassPurchaseRow,
refund: Stripe.Refund,
): Promise<OperatorPassRefundReceipt | null> {
const owed = await this.cacheService.get<Record<string, unknown>>(
withdrawalCreditNoteOwedKey(refund.metadata?.retry_of ?? refund.id),
);
if (!owed) {
return null;
}
const withdrawal = decodeOperatorPassWithdrawalReceipt(owed);
const creditNote = await this.loadRefundCreditNote(purchase, refund);
if (!creditNote) {
Logger.error(
{sessionId: purchase.checkout_session_id, refundId: refund.id},
'The settled Operator Pass withdrawal refund still has no credit note to send',
);
return null;
}
const recipient = await this.userRepository.findUnique(withdrawal.recipientUserId);
if (!recipient?.email || recipient.emailBounced) {
Logger.warn({refundId: refund.id}, 'No deliverable email for the credit note of an Operator Pass withdrawal');
return null;
}
return {
recipient: {email: recipient.email, locale: recipient.locale, timeZone: recipient.timezone},
params: {
invoiceNumber: purchase.invoice_number ?? null,
orderDate: purchase.purchased_at ?? purchase.created_at,
refundedAt: new Date(refund.created * 1000),
amountMinor: refund.amount,
currency: refund.currency,
delivered: withdrawal.delivered,
passCount: withdrawal.passCount,
lastPass: withdrawal.lastPass,
visionary: withdrawal.visionary,
creditNote,
timeZone: recipient.timezone,
},
};
}
private async refundSendsItsOwnEmail(purchase: OperatorPassPurchaseRow, refund: Stripe.Refund): Promise<boolean> {
if (refund.metadata?.checkout_session_id !== purchase.checkout_session_id) {
return false;
}
const refusal = refusalOfRefund(refund, purchase);
if (refusal) {
if (!EMAILED_REFUSALS.has(refusal)) {
return false;
}
if (purchase.status === 'pending') {
return true;
}
return (
purchase.status === 'duplicate_refunded' &&
((!purchase.invoice_document_id && !purchase.invoice_id) ||
(await this.cacheService.get<boolean>(refusalCreditNoteKey(purchase.checkout_session_id))) === true)
);
}
const reason = refund.metadata?.rejection_reason ?? '';
if (!reason.startsWith(WITHDRAWAL_REFUND_PREFIX)) {
return false;
}
const scope = reason.slice(WITHDRAWAL_REFUND_PREFIX.length);
if (scope.startsWith('all:')) {
const key = `withdrawal-receipt:${purchase.checkout_session_id}:${scope}`;
return (
purchase.withdrawal_refund_id === (refund.metadata?.retry_of ?? refund.id) ||
purchase.withdrawal_receipts_owed?.has(key) === true ||
(await this.cacheService.get<boolean>(withdrawalReceiptSentKey(key))) === true
);
}
const unit = await this.repository.findUnit(scope);
return unit?.purchase_id === purchase.checkout_session_id && unit.status === 'withdrawn';
}
private async loadRefundCreditNote(
purchase: OperatorPassPurchaseRow,
refund: Stripe.Refund,
): Promise<BillingDocumentAttachment | null> {
if (!this.documents) {
return null;
}
const document = await this.documents.issueForRefund(refund, operatorPassDocumentContext(purchase));
return document ? billingDocumentAttachment(document) : null;
}
private async findCheckoutEmail(sessionId: string): Promise<string | null> {
if (!this.stripe) {
return null;
}
const session = await this.stripe.checkout.sessions.retrieve(sessionId);
return session.customer_details?.email ?? session.customer_email ?? null;
}
async refundPassAmount(
purchase: OperatorPassPurchaseRow,
amountMinor: number,
reason: string,
): Promise<Stripe.Refund> {
if (!this.stripe) {
throw new StripeError('Stripe client not available for an Operator Pass refund');
}
if (!purchase.payment_intent_id) {
throw new StripeError('Operator Pass purchase has no payment intent to refund');
}
const refund = await this.stripe.refunds.create(
{
payment_intent: purchase.payment_intent_id,
amount: amountMinor,
reason: 'requested_by_customer',
metadata: {checkout_session_id: purchase.checkout_session_id, rejection_reason: reason},
},
{idempotencyKey: `operator-pass-${reason}:${purchase.checkout_session_id}`},
);
try {
await getBillingRepository().refunds.upsertFromStripe(refund);
} catch (mirrorErr) {
Logger.error(
{mirrorErr, refundId: refund.id},
'Mirror upsert failed for an Operator Pass refund; reconciler will heal',
);
}
return refund;
}
async handleRefundFailed(refund: Stripe.Refund, eventType: string): Promise<void> {
const announcesEnd =
(refund.status === 'failed' && eventType === 'refund.failed') ||
(refund.status === 'canceled' && eventType === 'refund.updated');
if (!announcesEnd) return;
const sessionId = refund.metadata?.checkout_session_id;
if (!sessionId || !this.stripe) return;
const purchase = await this.repository.findPurchase(sessionId);
if (!purchase) return;
const stripe = this.stripe;
const isRetry = refund.metadata?.retry_of != null;
const canceled = refund.status === 'canceled';
let message = 'An Operator Pass refund failed; retrying once';
if (canceled) {
message = 'An Operator Pass refund was canceled; not retrying, support has to decide whether to send the money';
} else if (isRetry) {
message =
'The retry of a failed Operator Pass refund also failed; the passes stay ended and support has to send the money another way';
}
Logger.error(
{
sessionId,
refundId: refund.id,
amount: refund.amount,
currency: refund.currency,
status: refund.status,
failureReason: refund.failure_reason ?? null,
retryOf: refund.metadata?.retry_of ?? null,
},
message,
);
if (canceled) {
await alertOperatorPassRefundNotSent(
purchase,
refund,
'An Operator Pass refund was canceled at Stripe and was not retried. Decide whether to send the money another way.',
);
} else if (isRetry) {
await alertOperatorPassRefundNotSent(
purchase,
refund,
'The retry of a failed Operator Pass refund also failed. The passes stay ended, so send the money another way and tell the buyer.',
);
}
await this.withCurrentPurchase(purchase, async (current) => {
if (canceled || isRetry || !current.payment_intent_id) return;
const existing = await stripe.refunds.list({payment_intent: current.payment_intent_id, limit: 100});
const earlierRetry = existing.data.find((candidate) => candidate.metadata?.retry_of === refund.id);
if (earlierRetry) {
Logger.warn(
{sessionId, failedRefundId: refund.id, retryRefundId: earlierRetry.id},
'A failed Operator Pass refund was already retried; not retrying again',
);
return;
}
let retry: Stripe.Refund;
try {
retry = await stripe.refunds.create(
{
payment_intent: current.payment_intent_id,
amount: refund.amount,
...(refund.reason === 'requested_by_customer' ? {reason: refund.reason} : {}),
metadata: {...refund.metadata, checkout_session_id: sessionId, retry_of: refund.id},
},
{idempotencyKey: `operator-pass-refund-retry:${refund.id}`},
);
} catch (error) {
if (!(error instanceof Stripe.errors.StripeInvalidRequestError)) throw error;
Logger.error(
{sessionId, refundId: refund.id, amount: refund.amount, currency: refund.currency, error: error.message},
'Stripe refused to retry the failed Operator Pass refund; support has to send the money another way',
);
await alertOperatorPassRefundNotSent(
current,
refund,
'An Operator Pass refund failed and Stripe refused to retry it. The passes stay ended, so send the money another way and tell the buyer.',
error,
);
return;
}
try {
await getBillingRepository().refunds.upsertFromStripe(retry);
} catch (mirrorErr) {
Logger.error(
{mirrorErr, refundId: retry.id},
'Mirror upsert failed for an Operator Pass refund retry; reconciler will heal',
);
}
Logger.warn(
{sessionId, failedRefundId: refund.id, retryRefundId: retry.id, amount: retry.amount},
'Retried a failed Operator Pass refund',
);
await this.creditRefundsMadeHere(current);
});
}
private async fulfilCheckoutSession(session: Stripe.Checkout.Session, paidAt: Date | null): Promise<void> {
const appliedKey = getAppliedKey(session.id);
if (await this.cacheService.get<boolean>(appliedKey)) {
Logger.debug({sessionId: session.id}, 'Operator Pass checkout already fulfilled');
return;
}
await this.withPurchaseLock(session.id, async (lease) => {
const purchase = (await this.repository.findPurchase(session.id)) ?? (await this.recoverPurchase(session));
if (!purchase) {
Logger.error({sessionId: session.id}, 'No Operator Pass purchase found for checkout session, skipping event');
return;
}
const awaitingWelcome = purchase.status === 'completed' && !isOperatorPassWelcomeSettled(purchase);
if (purchase.status !== 'pending' && !awaitingWelcome) {
if (!isWelcomeOutstanding(purchase)) {
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
}
return;
}
const purchaser = await this.userRepository.findUnique(purchase.purchaser_id);
if (!purchaser) {
Logger.error({sessionId: session.id, userId: purchase.purchaser_id}, 'Operator Pass purchaser not found');
throw new StripeError('Operator Pass purchaser not found');
}
if (awaitingWelcome) {
await this.sendWelcomeOnce(purchase, purchaser);
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
return;
}
await this.fulfilPendingPurchase(session, purchase, purchaser, paidAt, lease);
});
}
private async fulfilPendingPurchase(
session: Stripe.Checkout.Session,
pending: OperatorPassPurchaseRow,
purchaser: User,
paidAt: Date | null,
lease: OperatorPassLockLease,
): Promise<void> {
const appliedKey = getAppliedKey(session.id);
let purchase = pending;
const references = this.resolvePaymentReferences(session);
purchase = await this.repository.updatePurchase(purchase, {
payment_intent_id: Db.set(references.paymentIntentId ?? purchase.payment_intent_id),
});
const charge = await this.retrieveLatestCharge(purchase.payment_intent_id ?? null);
purchase = await this.recordPayment(purchase, session, charge, paidAt);
if (charge && charge.amount_refunded > 0 && (charge.refunded || charge.amount_refunded >= purchase.amount_minor)) {
const recordedRefusal = await this.findRefusalRefund(purchase);
if (recordedRefusal) {
await this.finishRefusal(purchase, purchaser, session, recordedRefusal);
} else {
await this.handleChargeRefundedLocked(purchase, charge);
await this.queueRefundReceipts(purchase);
}
await this.creditRefundsMadeHere(purchase);
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
return;
}
const dispute = charge?.disputed ? await this.retrieveChargeDispute(charge) : null;
if (dispute?.status === 'lost') {
await this.handleDisputeLostLocked(purchase, dispute);
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
return;
}
let refusal: OperatorPassRefusal | null = null;
if (await this.isRefusedPurchase(purchaser)) {
refusal = 'operator_pass_removed';
} else if (purchase.delivered_at == null && !purchase.certificate_names?.length) {
refusal = 'operator_pass_names_missing';
} else if (
purchase.delivered_at == null &&
purchase.confirmation_sent_at == null &&
(await this.isConfirmationUndeliverable(purchaser, session))
) {
refusal = 'operator_pass_email_undeliverable';
}
if (refusal) {
const recordedRefusal = await this.findRefusalRefund(purchase);
if (!recordedRefusal) {
await this.refundRefusedPurchase(purchase, refusal);
}
await this.finishRefusal(purchase, purchaser, session, recordedRefusal ?? refusal);
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
return;
}
purchase = await this.recordPurchaseTerms(purchase, session);
if (purchase.delivered_at == null && purchase.confirmation_sent_at == null) {
purchase = await this.extendCountryWithdrawalDeadline(purchase, operatorPassNow());
}
await this.sendConfirmationOnce(purchase, purchaser, session);
purchase = await this.repository.updatePurchase(purchase, {
confirmation_sent_at: Db.set(purchase.confirmation_sent_at ?? new Date()),
});
await lease.assertHeld();
await this.certificates.issueForPurchase(purchase);
const deliveredAt = purchase.delivered_at ?? operatorPassNow();
purchase = await this.repository.updatePurchase(purchase, {delivered_at: Db.set(deliveredAt)});
purchase = await this.extendCountryWithdrawalDeadline(purchase, deliveredAt);
purchase = await this.recordDeliveryOnPayment(purchase);
await lease.assertHeld();
purchase = await this.withLock(
operatorPassHolderLockKey(purchase.purchaser_id),
async () => {
const recorded = await this.recordHolderBeforeDelivery(purchase);
const delivery: Parameters<OperatorPassHoldingService['deliverPurchase']>[0] = {
purchase: recorded,
buyer: purchaser,
deliveredAt,
choice: null,
};
if (recorded.wall_opt_out != null) {
delivery.choice = {
name: recorded.wall_opt_out ? null : (recorded.wall_name ?? null),
optedOut: recorded.wall_opt_out || !recorded.wall_name,
};
}
await this.holdingService.deliverPurchase(delivery);
return recorded;
},
() => new StripeError('Another Operator Pass delivery to this account is underway; retrying'),
);
const bonusAt = purchase.perks_granted_at ?? operatorPassNow();
await lease.assertHeld();
purchase = await this.repository.updatePurchase(purchase, {
status: Db.set('completed'),
completed_at: Db.set(purchase.completed_at ?? new Date()),
perks_granted_at: Db.set(bonusAt),
wall_name: Db.clear(),
});
if (charge && charge.amount_refunded > 0) {
await this.handleChargeRefundedLocked(purchase, charge);
await this.creditRefundsMadeHere(purchase);
}
if (dispute) {
const current = (await this.repository.findPurchase(purchase.checkout_session_id)) ?? purchase;
if (dispute.status === 'won' || dispute.status === 'warning_closed' || dispute.status === 'prevented') {
await this.handleDisputeReleasedLocked(current, dispute);
} else {
await this.handleDisputeCreatedLocked(current, dispute);
Logger.warn(
{sessionId: session.id, purchaserId: purchase.purchaser_id, disputeId: dispute.id},
'Operator Pass delivered after a dispute was already open, so it is paused; check that the dispute review exists',
);
}
}
purchase = (await this.repository.findPurchase(purchase.checkout_session_id)) ?? purchase;
if (purchase.status === 'completed') {
await this.sendWelcomeOnce(purchase, purchaser);
purchase = (await this.repository.findPurchase(purchase.checkout_session_id)) ?? purchase;
}
if (!isWelcomeOutstanding(purchase)) {
await this.cacheService.set(appliedKey, true, APPLIED_TTL_SECONDS);
}
Logger.info(
{sessionId: session.id, purchaserId: purchase.purchaser_id, quantity: purchase.quantity ?? 1},
'Operator Pass checkout fulfilled',
);
}
private async recordDeliveryOnPayment(purchase: OperatorPassPurchaseRow): Promise<OperatorPassPurchaseRow> {
try {
return await syncOperatorPassDeliveryRecord(this.stripe, this.repository, purchase);
} catch (error) {
Logger.warn(
{error, sessionId: purchase.checkout_session_id},
'Could not record the Operator Pass certificate delivery time on the payment yet, retrying in the background',
);
}
try {
await getWorkerService().addJob(
OPERATOR_PASS_DELIVERY_RECORD_TASK,
{purchase_id: purchase.checkout_session_id},
{jobKey: `operator-pass-delivery-record:${purchase.checkout_session_id}`},
);
} catch (error) {
Logger.error(
{error, sessionId: purchase.checkout_session_id},
'Could not queue the Operator Pass certificate delivery time for the payment, the fulfilment sweep will record it',
);
}
return purchase;
}
private async isConfirmationUndeliverable(purchaser: User, session: Stripe.Checkout.Session): Promise<boolean> {
const email = confirmationAddress(purchaser, session);
return email != null && (await this.emailService.isEmailBounced(email));
}
private async isRefusedPurchase(purchaser: User): Promise<boolean> {
const {removal} = await loadOperatorPassEntitlementState(this.repository, purchaser.id);
return isOperatorPassPermanentlyRemoved(removal);
}
private async extendCountryWithdrawalDeadline(
purchase: OperatorPassPurchaseRow,
startsAt: Date,
): Promise<OperatorPassPurchaseRow> {
if (purchase.withdrawal_days == null) {
return purchase;
}
const endsAt = getOperatorPassWithdrawalEndsAt(startsAt, purchase.withdrawal_days);
if (purchase.withdrawal_ends_at && endsAt.getTime() <= purchase.withdrawal_ends_at.getTime()) {
return purchase;
}
return this.repository.updatePurchase(purchase, {withdrawal_ends_at: Db.set(endsAt)});
}
private async recordPayment(
purchase: OperatorPassPurchaseRow,
session: Stripe.Checkout.Session,
charge: Stripe.Charge | null,
paidAt: Date | null,
): Promise<OperatorPassPurchaseRow> {
if (purchase.purchased_at && purchase.invoice_number && purchase.charge_id && purchase.business_buyer != null) {
return purchase;
}
const legacyInvoiceId = extractId(session.invoice);
const legacyInvoice =
legacyInvoiceId && this.stripe && !purchase.invoice_number
? await this.stripe.invoices.retrieve(legacyInvoiceId)
: null;
const invoice =
purchase.invoice_number || legacyInvoiceId || purchase.preview_label != null
? null
: await this.issuePurchaseInvoice(purchase, session);
return this.repository.updatePurchase(purchase, {
purchased_at: Db.set(purchase.purchased_at ?? paidAt ?? resolveOperatorPassPaidAt(charge, operatorPassNow())),
invoice_id: Db.set(purchase.invoice_id ?? legacyInvoiceId),
invoice_number: Db.set(purchase.invoice_number ?? invoice?.display_number ?? legacyInvoice?.number ?? null),
invoice_document_id: Db.set(purchase.invoice_document_id ?? invoice?.document_id ?? null),
charge_id: Db.set(purchase.charge_id ?? charge?.id ?? null),
business_buyer: Db.set(purchase.business_buyer ?? (session.customer_details?.tax_ids?.length ?? 0) > 0),
});
}
private async recordHolderBeforeDelivery(purchase: OperatorPassPurchaseRow): Promise<OperatorPassPurchaseRow> {
if (purchase.holder_had_pass != null) {
return purchase;
}
const held = await this.holdingService.queries.listHeldUnits(purchase.purchaser_id);
return this.repository.updatePurchase(purchase, {
holder_had_pass: Db.set(held.some((unit) => unit.purchase_id !== purchase.checkout_session_id)),
});
}
private async queueRefundReceipts(purchase: OperatorPassPurchaseRow): Promise<void> {
if (!this.stripe || !purchase.payment_intent_id) {
return;
}
const refunds = await this.stripe.refunds.list({payment_intent: purchase.payment_intent_id, limit: 100});
for (const refund of refunds.data) {
if (refund.status !== 'succeeded') continue;
try {
await enqueueBillingEmail(
getWorkerService(),
{kind: 'refund', id: refund.id},
{keySuffix: 'fulfilment', runAt: new Date()},
);
} catch (error) {
Logger.error(
{error, sessionId: purchase.checkout_session_id, refundId: refund.id},
'Could not queue the receipt for an Operator Pass refund made before fulfilment',
);
}
}
}
private async recordPurchaseTerms(
purchase: OperatorPassPurchaseRow,
session: Stripe.Checkout.Session,
): Promise<OperatorPassPurchaseRow> {
if (purchase.withdrawal_ends_at) {
return purchase;
}
const purchasedAt = purchase.purchased_at ?? operatorPassNow();
const rule = resolveOperatorPassPurchaseWithdrawalRule(session, purchase);
return this.repository.updatePurchase(purchase, {
withdrawal_country: Db.set(rule?.country ?? null),
withdrawal_days: Db.set(rule?.days ?? null),
withdrawal_rule_version: Db.set(rule ? OPERATOR_PASS_WITHDRAWAL_RULE_VERSION : null),
withdrawal_ends_at: Db.set(
getOperatorPassWithdrawalEndsAt(rule ? operatorPassNow() : purchasedAt, rule?.days ?? null),
),
stripe_terms_consent: Db.set(session.consent?.terms_of_service ?? null),
operator_pass_terms_version: Db.set(purchase.operator_pass_terms_version ?? OPERATOR_PASS_TERMS_VERSION),
});
}
private async describePaymentMethod(paymentIntentId: string | null): Promise<string | null> {
if (!this.stripe || !paymentIntentId) {
return null;
}
try {
const intent = await this.stripe.paymentIntents.retrieve(paymentIntentId, {expand: ['latest_charge']});
const details = typeof intent.latest_charge === 'object' ? intent.latest_charge?.payment_method_details : null;
if (!details) {
return null;
}
if (details.type === 'card' && details.card) {
const brand = details.card.brand
? details.card.brand.charAt(0).toUpperCase() + details.card.brand.slice(1)
: 'Card';
return details.card.last4 ? `${brand} ···· ${details.card.last4}` : brand;
}
return details.type === 'pix'
? 'Pix'
: details.type.charAt(0).toUpperCase() + details.type.slice(1).replaceAll('_', ' ');
} catch (error) {
Logger.warn({error, paymentIntentId}, 'Failed to describe the payment method of an Operator Pass payment');
return null;
}
}
private async retrieveLatestCharge(paymentIntentId: string | null): Promise<Stripe.Charge | null> {
if (!this.stripe || !paymentIntentId) {
return null;
}
const intent = await this.stripe.paymentIntents.retrieve(paymentIntentId, {expand: ['latest_charge']});
return typeof intent.latest_charge === 'object' ? intent.latest_charge : null;
}
private async retrieveChargeDispute(charge: Stripe.Charge): Promise<Stripe.Dispute> {
const disputes = this.stripe ? await this.stripe.disputes.list({charge: charge.id, limit: 1}) : null;
const dispute = disputes?.data[0];
if (!dispute) {
throw new StripeError('Operator Pass charge is marked disputed but Stripe returned no dispute');
}
return dispute;
}
private async issuePurchaseInvoice(purchase: OperatorPassPurchaseRow, session: Stripe.Checkout.Session) {
if (!this.documents) {
return null;
}
const purchaser = await this.userRepository.findUnique(purchase.purchaser_id);
return this.documents.issueForCheckoutSession(
session.id,
operatorPassDocumentContext(purchase, purchaser?.locale ?? session.metadata?.operator_pass_locale ?? null),
);
}
private async sendConfirmationOnce(
purchase: OperatorPassPurchaseRow,
purchaser: User,
session: Stripe.Checkout.Session,
): Promise<void> {
const sentKey = confirmationSentKey(purchase.checkout_session_id);
if (purchase.confirmation_sent_at || (await this.cacheService.get<boolean>(sentKey))) {
return;
}
const email = confirmationAddress(purchaser, session);
if (!email) {
throw new StripeError('Operator Pass buyer has no email address for the purchase confirmation');
}
const invoice =
purchase.invoice_document_id && this.documents
? await this.documents.findDocument(purchase.invoice_document_id)
: null;
const sent = await this.emailService.send(
'operator_pass_purchase_confirmation',
email,
{
invoiceNumber: purchase.invoice_number ?? null,
orderDate: purchase.purchased_at ?? operatorPassNow(),
quantity: Math.max(1, purchase.quantity ?? 1),
totals: invoice ? billingDocumentTotals(invoice) : plainPurchaseTotals(purchase),
document: invoice ? billingDocumentAttachment(invoice) : null,
business: purchase.business_buyer === true,
consentAt: purchase.waiver_consent_at ?? null,
withdrawalEndsOn:
purchase.withdrawal_days != null && purchase.withdrawal_ends_at
? getOperatorPassWithdrawalEndsOn(purchase.withdrawal_ends_at)
: null,
withdrawalCountry: purchase.withdrawal_country ?? null,
wallName: await this.resolveConfirmationWallName(purchase),
unitAmountMinor: Math.round(purchase.amount_minor / Math.max(1, purchase.quantity ?? 1)),
paymentMethod: await this.describePaymentMethod(purchase.payment_intent_id ?? null),
deliveryBoxText: purchase.waiver_consent_text ?? null,
termsVersion: purchase.operator_pass_terms_version ?? OPERATOR_PASS_TERMS_VERSION,
timeZone: purchaser.timezone,
},
purchaser.locale ?? session.metadata?.operator_pass_locale ?? null,
);
if (!sent) {
throw new StripeError('Failed to send the Operator Pass purchase confirmation; the pass is not granted');
}
await this.cacheService.set(sentKey, true, APPLIED_TTL_SECONDS);
if (invoice && invoice.emailed_at == null && this.documents) {
try {
await this.documents.repository.markEmailed(invoice.document_id, new Date());
} catch (error) {
Logger.error(
{error, sessionId: purchase.checkout_session_id},
'Sent the Operator Pass invoice but could not record when it was emailed',
);
}
}
}
private async resolveConfirmationWallName(purchase: OperatorPassPurchaseRow): Promise<string | null> {
if (purchase.wall_opt_out == null) {
const entry = await this.wallService.getEntry(purchase.purchaser_id);
return entry && !entry.opted_out ? (entry.name ?? null) : null;
}
return purchase.wall_opt_out ? null : (purchase.wall_name ?? null);
}
private async sendPurchaseRefused(
purchase: OperatorPassPurchaseRow,
purchaser: User,
session: Stripe.Checkout.Session,
refusal: OperatorPassRefusal,
): Promise<void> {
const sentKey = refusalSentKey(purchase.checkout_session_id);
if (await this.cacheService.get<boolean>(sentKey)) {
return;
}
const email = purchaser.email ?? session.customer_details?.email ?? session.customer_email;
if (!email) {
throw new StripeError('Operator Pass buyer has no email address for the refusal email');
}
if (await this.emailService.isEmailBounced(email)) {
Logger.warn(
{sessionId: purchase.checkout_session_id, refusal},
'Operator Pass buyer address has bounced; skipping the refusal email',
);
await this.cacheService.set(sentKey, true, APPLIED_TTL_SECONDS);
return;
}
const refund = await this.findRefusalRefundRecord(purchase);
const creditNote = refund ? await this.loadRefundCreditNote(purchase, refund) : null;
const sent = await this.emailService.send('operator_pass_purchase_refused', email, {creditNote}, purchaser.locale);
if (!sent) {
throw new StripeError('Failed to send the Operator Pass refusal email');
}
if (creditNote) {
await this.cacheService.set(refusalCreditNoteKey(purchase.checkout_session_id), true, APPLIED_TTL_SECONDS);
}
await this.cacheService.set(sentKey, true, APPLIED_TTL_SECONDS);
}
private async finishRefusal(
purchase: OperatorPassPurchaseRow,
purchaser: User,
session: Stripe.Checkout.Session,
refusal: OperatorPassRefusal,
): Promise<void> {
if (EMAILED_REFUSALS.has(refusal)) {
await this.sendPurchaseRefused(purchase, purchaser, session, refusal);
}
await this.repository.updatePurchase(purchase, {
status: Db.set('duplicate_refunded'),
completed_at: Db.set(new Date()),
certificate_names: Db.clear(),
wall_name: Db.clear(),
refusal_reason: Db.set(refusal),
});
}
private async findRefusalRefund(purchase: OperatorPassPurchaseRow): Promise<OperatorPassRefusal | null> {
const refund = await this.findRefusalRefundRecord(purchase);
return refund ? refusalOfRefund(refund, purchase) : null;
}
private async findRefusalRefundRecord(purchase: OperatorPassPurchaseRow): Promise<Stripe.Refund | null> {
if (!this.stripe || !purchase.payment_intent_id) {
return null;
}
const refunds = await this.stripe.refunds.list({payment_intent: purchase.payment_intent_id, limit: 100});
return refunds.data.find((refund) => refusalOfRefund(refund, purchase) != null) ?? null;
}
private async refundRefusedPurchase(purchase: OperatorPassPurchaseRow, reason: OperatorPassRefusal): Promise<void> {
if (!this.stripe) {
throw new StripeError('Stripe client not available for an Operator Pass refusal refund');
}
if (!purchase.payment_intent_id) {
throw new StripeError('Operator Pass refused purchase has no payment intent to refund');
}
Logger.warn(
{sessionId: purchase.checkout_session_id, purchaserId: purchase.purchaser_id, reason},
'Refusing the Operator Pass purchase before delivery; refunding it',
);
const refund = await this.stripe.refunds.create(
{
payment_intent: purchase.payment_intent_id,
metadata: {
checkout_session_id: purchase.checkout_session_id,
rejection_reason: reason,
},
},
{idempotencyKey: `operator-pass-duplicate-refund:${purchase.checkout_session_id}`},
);
try {
await getBillingRepository().refunds.upsertFromStripe(refund);
} catch (mirrorErr) {
Logger.error(
{mirrorErr, refundId: refund.id},
'Mirror upsert failed for an Operator Pass refusal refund; reconciler will heal',
);
}
await this.creditRefundsMadeHere(purchase);
}
private async withCurrentPurchase<T>(
purchase: OperatorPassPurchaseRow,
action: (current: OperatorPassPurchaseRow) => Promise<T>,
): Promise<T> {
return this.withPurchaseLock(purchase.checkout_session_id, async () =>
action((await this.repository.findPurchase(purchase.checkout_session_id)) ?? purchase),
);
}
async createOffer(params: OperatorPassOfferParams): Promise<OperatorPassOfferRow> {
return this.withLock(
`operator_pass:offer_lock:${params.sender.id}`,
() => this.holdingService.createOffer(params),
() => new OperatorPassOfferBusyError(),
);
}
private async withPurchaseLock<T>(
checkoutSessionId: string,
action: (lease: OperatorPassLockLease) => Promise<T>,
busyError: () => Error = () => new StripeError('Operator Pass purchase is busy; retrying'),
): Promise<T> {
return this.withLock(operatorPassPurchaseLockKey(checkoutSessionId), action, busyError);
}
private async withLock<T>(
lockKey: string,
action: (lease: OperatorPassLockLease) => Promise<T>,
busyError: () => Error,
): Promise<T> {
return withOperatorPassLock(this.cacheService, lockKey, action, busyError);
}
private resolvePaymentReferences(session: Stripe.Checkout.Session): CheckoutPaymentReferences {
return {paymentIntentId: extractId(session.payment_intent)};
}
private async recoverPurchase(session: Stripe.Checkout.Session): Promise<OperatorPassPurchaseRow | null> {
const metadata = session.metadata ?? {};
const purchaserId = metadata.operator_pass_purchaser_id;
const amountMinor = Number(metadata.operator_pass_amount_minor);
const quantity = Number(metadata.operator_pass_quantity ?? '1');
const currency = metadata.operator_pass_currency;
const phase = metadata.operator_pass_phase;
if (
!purchaserId ||
!/^\d{1,20}$/u.test(purchaserId) ||
!Number.isSafeInteger(amountMinor) ||
!Number.isSafeInteger(quantity) ||
quantity < 1 ||
!currency ||
!isOperatorPassCurrency(currency) ||
!phase ||
!(OPERATOR_PASS_PHASES as ReadonlyArray<string>).includes(phase)
) {
return null;
}
const purchase: OperatorPassPurchaseRow = {
checkout_session_id: session.id,
purchaser_id: createUserID(BigInt(purchaserId)),
quantity,
status: 'pending',
phase,
amount_minor: amountMinor,
currency,
quote_honored: metadata.operator_pass_quote_honored === 'true',
payment_intent_id: null,
invoice_id: null,
created_at: new Date((session.created ?? Math.floor(Date.now() / 1000)) * 1000),
completed_at: null,
refunded_at: null,
waiver_consent_at: parseDate(metadata.operator_pass_waiver_consent_at),
waiver_consent_version: metadata.operator_pass_waiver_consent_version ?? null,
waiver_consent_text: session.custom_text?.terms_of_service_acceptance?.message ?? null,
waiver_consent_ip: null,
waiver_consent_user_agent: null,
wall_name: null,
wall_opt_out:
metadata.operator_pass_wall_opt_out === undefined ? null : metadata.operator_pass_wall_opt_out === 'true',
withdrawal_country: metadata.operator_pass_withdrawal_country ?? null,
withdrawal_days: null,
withdrawal_rule_version: null,
fraud_warning_at: null,
stripe_terms_consent: null,
operator_pass_terms_version: metadata.operator_pass_terms_version ?? OPERATOR_PASS_TERMS_VERSION,
purchased_at: null,
withdrawal_ends_at: null,
perks_granted_at: null,
confirmation_sent_at: null,
withdrawn_at: null,
withdrawal_name: null,
withdrawal_refund_id: null,
withdrawal_channel: null,
withdrawal_receipts_owed: null,
invoice_number: null,
invoice_document_id: null,
dispute_id: null,
dispute_reason: null,
dispute_status: null,
disputed_at: null,
dispute_closed_at: null,
certificate_names: null,
age_confirmed_at:
metadata.operator_pass_age_confirmed === 'true' ? parseDate(metadata.operator_pass_waiver_consent_at) : null,
delivered_at: null,
delivery_recorded_at: null,
welcome_sent_at: null,
welcome_skipped_at: null,
refusal_reason: null,
charge_id: null,
business_buyer: null,
holder_had_pass: null,
labs_greeting:
metadata.operator_pass_labs_greeting === undefined ? null : metadata.operator_pass_labs_greeting === 'true',
preview_label: metadata.operator_pass_preview === 'true' ? (metadata.operator_pass_preview_label ?? '') : null,
version: 1,
};
await this.repository.createPurchase(purchase);
Logger.warn({sessionId: session.id, purchaserId}, 'Recovered Operator Pass purchase from checkout metadata');
return purchase;
}
private async loadCertificateAttachment(purchase: OperatorPassPurchaseRow): Promise<EmailAttachment | null> {
const file = await this.certificates.loadPurchaseFile(purchase);
return file ? {filename: file.filename, content: Buffer.from(file.bytes), contentType: 'application/pdf'} : null;
}
async reissueCertificatePage(params: {
passId: string;
holderName: string;
reason: OperatorPassCertificateReissueReason;
}): Promise<OperatorPassCertificateRow> {
const latest = await this.repository.findLatestCertificate(params.passId);
if (latest?.source === 'visionary') {
return this.reissueVisionaryPage(params);
}
if (!latest?.purchase_id) {
throw new UnknownOperatorPassPurchaseError();
}
const purchaseId = latest.purchase_id;
return this.withPurchaseLock(
purchaseId,
async () => {
const purchase = await this.repository.findPurchase(purchaseId);
if (!purchase) {
throw new UnknownOperatorPassPurchaseError();
}
const unit = await this.repository.findUnit(params.passId);
const page = await this.repository.findLatestCertificate(params.passId);
if (!unit || isOperatorPassCertificatePageCancelled(unit) || page?.cancelled_at != null) {
await this.certificates.syncCancellations(purchase);
if (params.reason !== 'objection') {
throw InputValidationError.create('pass_id', 'This certificate page is cancelled');
}
return this.eraseCancelledCertificatePage(purchase, params.passId);
}
const purchaser = await this.userRepository.findUnique(purchase.purchaser_id);
if (!purchaser || purchaser.deletionStartedAt) {
throw InputValidationError.create('pass_id', 'The buyer of this certificate page is deleting their account');
}
const row = await this.certificates.reissuePage(params);
await this.repository.updatePurchase(purchase, {
certificate_names: Db.set(replaceOperatorPassCertificateName(purchase, row.pass_id, row.holder_name)),
});
await this.certificates.syncCancellations(purchase);
return row;
},
purchaseBusyError,
);
}
private async reissueVisionaryPage(params: {
passId: string;
holderName: string;
reason: OperatorPassCertificateReissueReason;
}): Promise<OperatorPassCertificateRow> {
const unit = await this.repository.findUnit(params.passId);
const page = await this.repository.findLatestCertificate(params.passId);
if (unit?.status !== 'held' || page?.cancelled_at != null) {
if (params.reason !== 'objection') {
throw InputValidationError.create('pass_id', 'This certificate page is cancelled');
}
await this.repository.clearCertificatePersonalData(params.passId);
const erased = await this.repository.findLatestCertificate(params.passId);
if (!erased) {
throw InputValidationError.create('pass_id', 'This pass has no certificate page');
}
return erased;
}
const holder = await this.userRepository.findUnique(unit.holder_id);
if (!holder || holder.deletionStartedAt) {
throw InputValidationError.create('pass_id', 'The holder of this certificate page is deleting their account');
}
return this.certificates.reissuePage(params);
}
private async eraseCancelledCertificatePage(
purchase: OperatorPassPurchaseRow,
passId: string,
): Promise<OperatorPassCertificateRow> {
await this.repository.clearCertificatePersonalData(passId);
if (purchase.certificate_names != null) {
await this.repository.updatePurchase(purchase, {
certificate_names: Db.set(replaceOperatorPassCertificateName(purchase, passId, '')),
});
}
const erased = await this.repository.findLatestCertificate(passId);
if (!erased) {
throw InputValidationError.create('pass_id', 'This pass has no certificate page');
}
Logger.info(
{passId, number: erased.number, version: erased.version},
'Erased the name and PDF of a cancelled Operator certificate page after an objection',
);
return erased;
}
async resetCertificateLink(user: User, passId: string): Promise<string> {
const latest = await this.repository.findLatestCertificate(passId);
if (!latest) {
throw new UnknownOperatorPassUnitError();
}
const unit = await this.repository.findUnit(passId);
if (latest.source === 'visionary') {
if (unit?.holder_id !== user.id) {
throw new UnknownOperatorPassUnitError();
}
} else {
const purchaseId = unit?.purchase_id ?? latest.purchase_id;
const purchase = purchaseId ? await this.repository.findPurchase(purchaseId) : null;
if (purchase?.purchaser_id !== user.id) {
throw new UnknownOperatorPassUnitError();
}
}
const row = await this.reissueCertificatePage({passId, holderName: latest.holder_name, reason: 'link'});
if (!row.link_token) {
throw new Error(`Operator certificate page ${passId} has no link after a link reset`);
}
return getOperatorPassCertificateUrl(row.link_token);
}
private async sendWelcomeOnce(purchase: OperatorPassPurchaseRow, user: User): Promise<void> {
if (isOperatorPassWelcomeSettled(purchase)) {
return;
}
if (!user.email || (await this.emailService.isEmailBounced(user.email))) {
Logger.warn(
{userId: user.id, sessionId: purchase.checkout_session_id},
'Operator Pass buyer has no deliverable email; skipping welcome email',
);
await this.repository.updatePurchase(purchase, {welcome_skipped_at: Db.set(operatorPassNow())});
return;
}
const attachment = await this.loadCertificateAttachment(purchase);
const units = await this.repository.listUnitsByPurchase(purchase.checkout_session_id);
const livePages = units.filter((unit) => !isOperatorPassCertificatePageCancelled(unit)).length;
if (!attachment) {
if (livePages > 0) {
throw new StripeError('Operator Pass certificate is missing for the welcome email; retrying');
}
Logger.warn(
{sessionId: purchase.checkout_session_id},
'The Operator Pass purchase has no pass left with a certificate page; skipping welcome email',
);
await this.repository.updatePurchase(purchase, {welcome_skipped_at: Db.set(operatorPassNow())});
return;
}
const wallEntry = await this.wallService.getEntry(user.id);
const sent = await this.emailService.send(
'operator_pass_welcome',
user.email,
{
labsInviteUrl: OPERATOR_PASS_LABS_INVITE_URL,
labsMember: await this.services.roleService.isLabsMember(user.id),
invoiceNumber: purchase.invoice_number ?? null,
deliveredAt: purchase.delivered_at ?? purchase.perks_granted_at ?? operatorPassNow(),
wallName: wallEntry && !wallEntry.opted_out ? (wallEntry.name ?? null) : null,
passCount: units.length > 0 ? livePages : Math.max(1, purchase.quantity ?? 1),
certificate: attachment,
timeZone: user.timezone,
visionary: keepsOperatorsThroughVisionary(user),
},
user.locale,
);
if (!sent) {
throw new StripeError('Failed to send the Operator Pass welcome email with the certificate; retrying');
}
await this.repository.updatePurchase(purchase, {welcome_sent_at: Db.set(operatorPassNow())});
}
}
function plainPurchaseTotals(purchase: OperatorPassPurchaseRow): BillingTotals {
return {
totalMinor: purchase.amount_minor,
paidMinor: purchase.amount_minor,
currency: purchase.currency,
tax: null,
reverseCharge: false,
};
}
export function resolveOperatorPassPaidAt(charge: Stripe.Charge | null, fallback: Date): Date {
return charge?.created ? new Date(charge.created * 1000) : fallback;
}
const SETTLEMENT_EVENT_SCAN_LIMIT = 1000;
export async function resolveOperatorPassSettledAt(
stripe: Stripe,
session: Stripe.Checkout.Session,
fallback: Date,
): Promise<Date> {
const intent = typeof session.payment_intent === 'object' ? session.payment_intent : null;
if (!intent) {
return fallback;
}
let scanned = 0;
for await (const event of stripe.events.list({
type: 'payment_intent.succeeded',
created: {gte: intent.created},
limit: 100,
})) {
if ((event.data.object as {id?: string}).id === intent.id) {
return new Date(event.created * 1000);
}
scanned += 1;
if (scanned >= SETTLEMENT_EVENT_SCAN_LIMIT) {
break;
}
}
const charge = typeof intent.latest_charge === 'object' ? intent.latest_charge : null;
return charge?.payment_method_details?.type === 'card' ? resolveOperatorPassPaidAt(charge, fallback) : fallback;
}
function isChargeDisputedError(error: unknown): boolean {
return typeof error === 'object' && error !== null && 'code' in error && error.code === 'charge_disputed';
}
function parseDate(value: string | undefined): Date | null {
if (!value) {
return null;
}
const parsed = new Date(value);
return Number.isNaN(parsed.getTime()) ? null : parsed;
}
function confirmationAddress(purchaser: User, session: Stripe.Checkout.Session): string | null {
return purchaser.email ?? session.customer_details?.email ?? session.customer_email ?? null;
}
function isWelcomeOutstanding(purchase: OperatorPassPurchaseRow): boolean {
return (
(purchase.status === 'completed' || purchase.status === 'disputed') &&
purchase.delivered_at != null &&
!isOperatorPassWelcomeSettled(purchase)
);
}
function purchaseBusyError(): ConflictError {
return new ConflictError({
code: APIErrorCodes.CONFLICT,
message: 'This purchase is being updated, try again in a moment',
});
}
function withdrawalReceiptKey(receipt: OperatorPassWithdrawalReceipt): string {
return `withdrawal-receipt:${receipt.purchaseId}:${receipt.passId ?? 'all'}:${receipt.receivedAt.toISOString()}`;
}
function withdrawalDisputeAcceptedKey(disputeId: string): string {
return `operator_pass:withdrawal_dispute_accepted:${disputeId}`;
}
function withdrawalReceiptSentKey(key: string): string {
return `operator_pass:${key}:sent`;
}
function withOwedWithdrawalReceipt(
purchase: OperatorPassPurchaseRow,
receipt: OperatorPassWithdrawalReceipt,
): Map<string, string> {
const owed = new Map(purchase.withdrawal_receipts_owed ?? []);
owed.set(withdrawalReceiptKey(receipt), JSON.stringify(encodeOperatorPassWithdrawalReceipt(receipt)));
return owed;
}
function withdrawalCreditNoteOwedKey(refundId: string): string {
return `operator_pass:withdrawal:credit_note_owed:${refundId}`;
}
function refusalCreditNoteKey(checkoutSessionId: string): string {
return `operator_pass:refusal:credit_note:${checkoutSessionId}`;
}
function confirmationSentKey(checkoutSessionId: string): string {
return `operator_pass:confirmation:sent:${checkoutSessionId}`;
}
function refusalSentKey(checkoutSessionId: string): string {
return `operator_pass:refusal:sent:${checkoutSessionId}`;
}
function getAppliedKey(checkoutSessionId: string): string {
return `stripe:checkout:operator_pass:applied:${checkoutSessionId}`;
}