Skip to content

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

TypeScript fluxerfluxerapp

feat(billing): issue business invoices for checkouts

Hampus3ebbccfb9a22
diff --git a/fluxer_api/src/api/stripe/StripeB2BInvoice.ts b/fluxer_api/src/api/stripe/StripeB2BInvoice.ts
new file mode 100644
index 000000000..08a5c6ac9
--- /dev/null
+++ b/fluxer_api/src/api/stripe/StripeB2BInvoice.ts
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {Logger} from '@app/api/Logger';
+import {extractId} from '@app/api/stripe/StripeUtils';
+import type Stripe from 'stripe';
+
+const B2B_INVOICE_METADATA_KEY = 'b2b_invoice_id';
+const INVOICE_LINE_ITEM_LIMIT = 20;
+
+export async function ensureB2BInvoiceForCheckout(
+ stripe: Stripe | null,
+ session: Stripe.Checkout.Session,
+): Promise<string | null> {
+ if (
+ !stripe ||
+ session.mode !== 'payment' ||
+ session.payment_status !== 'paid' ||
+ extractId(session.invoice) !== null
+ ) {
+ return null;
+ }
+ const customerId = extractId(session.customer);
+ if (customerId === null) {
+ return null;
+ }
+ const hasTaxIds = (session.customer_details?.tax_ids?.length ?? 0) > 0;
+ if (!hasTaxIds) {
+ return null;
+ }
+ const paymentIntentId = extractId(session.payment_intent);
+ if (paymentIntentId) {
+ const intent = await stripe.paymentIntents.retrieve(paymentIntentId);
+ const existing = intent.metadata?.[B2B_INVOICE_METADATA_KEY];
+ if (existing) {
+ return existing;
+ }
+ }
+ const currency = session.currency;
+ if (!currency) {
+ return null;
+ }
+ const draft = await stripe.invoices.create(
+ {
+ customer: customerId,
+ currency,
+ collection_method: 'send_invoice',
+ days_until_due: 0,
+ auto_advance: false,
+ pending_invoice_items_behavior: 'exclude',
+ automatic_tax: {enabled: session.automatic_tax?.enabled === true},
+ metadata: {checkout_session_id: session.id, ...(paymentIntentId ? {payment_intent_id: paymentIntentId} : {})},
+ },
+ {idempotencyKey: `b2b-invoice:${session.id}`},
+ );
+ const lineItems = await stripe.checkout.sessions.listLineItems(session.id, {
+ limit: INVOICE_LINE_ITEM_LIMIT,
+ expand: ['data.price'],
+ });
+ for (const [index, item] of lineItems.data.entries()) {
+ const price = item.price;
+ const productId = price ? extractId(price.product) : null;
+ const unitAmount = price?.unit_amount ?? null;
+ const invoiceItems = stripe.invoiceItems;
+ const params: Stripe.InvoiceItemCreateParams = {
+ customer: customerId,
+ invoice: draft.id,
+ currency,
+ quantity: item.quantity ?? 1,
+ };
+ if (productId && unitAmount !== null) {
+ params.price_data = {
+ currency,
+ product: productId,
+ unit_amount: unitAmount,
+ tax_behavior: price?.tax_behavior === 'exclusive' ? 'exclusive' : 'inclusive',
+ };
+ } else {
+ params.amount = item.amount_total;
+ params.description = item.description ?? undefined;
+ }
+ await invoiceItems.create(params, {idempotencyKey: `b2b-invoice-item:${session.id}:${index}`});
+ }
+ const finalized = await stripe.invoices.finalizeInvoice(draft.id, {auto_advance: false});
+ await stripe.invoices.pay(finalized.id, {paid_out_of_band: true}, {idempotencyKey: `b2b-invoice-pay:${session.id}`});
+ if (paymentIntentId) {
+ await stripe.paymentIntents.update(paymentIntentId, {metadata: {[B2B_INVOICE_METADATA_KEY]: finalized.id}});
+ }
+ Logger.info({sessionId: session.id, invoiceId: finalized.id}, 'Created a business invoice for a paid checkout');
+ return finalized.id;
+}
diff --git a/fluxer_api/src/api/stripe/tests/StripeB2BInvoice.test.ts b/fluxer_api/src/api/stripe/tests/StripeB2BInvoice.test.ts
new file mode 100644
index 000000000..38402a33d
--- /dev/null
+++ b/fluxer_api/src/api/stripe/tests/StripeB2BInvoice.test.ts
@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {STRIPE_API_VERSION} from '@app/api/stripe/StripeApiVersion';
+import {ensureB2BInvoiceForCheckout} from '@app/api/stripe/StripeB2BInvoice';
+import {server} from '@app/api/test/msw/server';
+import {HttpStatus} from '@fluxer/constants/src/HttpConstants';
+import {HttpResponse, http} from 'msw';
+import Stripe from 'stripe';
+import {describe, expect, test} from 'vitest';
+
+function customerDetails(
+ overrides: Partial<Stripe.Checkout.Session.CustomerDetails> = {},
+): Stripe.Checkout.Session.CustomerDetails {
+ return {
+ address: null,
+ business_name: null,
+ email: '[email protected]',
+ individual_name: null,
+ name: 'Buyer',
+ phone: null,
+ tax_exempt: 'none',
+ tax_ids: [{type: 'eu_vat', value: 'SE556677889901'}],
+ ...overrides,
+ };
+}
+
+function session(overrides: Partial<Stripe.Checkout.Session> = {}): Stripe.Checkout.Session {
+ return {
+ id: 'cs_b2b_1',
+ object: 'checkout.session',
+ adaptive_pricing: null,
+ after_expiration: null,
+ allow_promotion_codes: null,
+ amount_subtotal: 39800,
+ amount_total: 39800,
+ automatic_tax: {enabled: true, liability: null, provider: null, status: 'complete'},
+ billing_address_collection: null,
+ cancel_url: null,
+ client_reference_id: null,
+ client_secret: null,
+ collected_information: null,
+ consent: null,
+ consent_collection: null,
+ created: 1700000000,
+ currency: 'eur',
+ currency_conversion: null,
+ custom_fields: [],
+ custom_text: {after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null},
+ customer: 'cus_b2b',
+ customer_account: null,
+ customer_creation: null,
+ customer_details: customerDetails(),
+ customer_email: null,
+ discounts: null,
+ expires_at: 1700086400,
+ integration_identifier: null,
+ invoice: null,
+ invoice_creation: null,
+ livemode: false,
+ locale: null,
+ managed_payments: null,
+ metadata: {},
+ mode: 'payment',
+ origin_context: null,
+ payment_intent: 'pi_b2b',
+ payment_link: null,
+ payment_method_collection: null,
+ payment_method_configuration_details: null,
+ payment_method_options: null,
+ payment_method_types: ['card'],
+ payment_status: 'paid',
+ permissions: null,
+ recovered_from: null,
+ saved_payment_method_options: null,
+ setup_intent: null,
+ shipping_address_collection: null,
+ shipping_cost: null,
+ shipping_options: [],
+ status: 'complete',
+ submit_type: null,
+ subscription: null,
+ success_url: null,
+ total_details: null,
+ ui_mode: null,
+ url: null,
+ wallet_options: null,
+ ...overrides,
+ };
+}
+
+function price(overrides: Partial<Stripe.Price> = {}): Stripe.Price {
+ return {
+ id: 'price_pass',
+ object: 'price',
+ active: true,
+ billing_scheme: 'per_unit',
+ created: 1700000000,
+ currency: 'eur',
+ custom_unit_amount: null,
+ livemode: false,
+ lookup_key: null,
+ metadata: {},
+ nickname: null,
+ product: 'prod_pass',
+ recurring: null,
+ tax_behavior: 'inclusive',
+ tiers_mode: null,
+ transform_quantity: null,
+ type: 'one_time',
+ unit_amount: 19900,
+ unit_amount_decimal: null,
+ ...overrides,
+ };
+}
+
+function lineItem(overrides: Partial<Stripe.LineItem> = {}): Stripe.LineItem {
+ return {
+ id: 'li_pass',
+ object: 'item',
+ adjustable_quantity: null,
+ amount_discount: 0,
+ amount_subtotal: 39800,
+ amount_tax: 0,
+ amount_total: 39800,
+ currency: 'eur',
+ description: 'Fluxer Operator Pass',
+ metadata: null,
+ price: price(),
+ quantity: 2,
+ ...overrides,
+ };
+}
+
+interface RecordedRequest {
+ method: string;
+ path: string;
+ params: Record<string, string>;
+ idempotencyKey: string | null;
+}
+
+function recordStripeInvoices({
+ existingInvoiceId,
+ lines = [lineItem()],
+}: {
+ existingInvoiceId?: string;
+ lines?: Array<Stripe.LineItem>;
+} = {}) {
+ const requests: Array<RecordedRequest> = [];
+ server.use(
+ http.all('https://api.stripe.com/v1/*', async ({request}) => {
+ const url = new URL(request.url);
+ const params = request.method === 'GET' ? url.searchParams : new URLSearchParams(await request.text());
+ requests.push({
+ method: request.method,
+ path: url.pathname,
+ params: Object.fromEntries(params),
+ idempotencyKey: request.headers.get('idempotency-key'),
+ });
+ switch (`${request.method} ${url.pathname}`) {
+ case 'GET /v1/payment_intents/pi_b2b':
+ return HttpResponse.json({id: 'pi_b2b', metadata: {b2b_invoice_id: existingInvoiceId}});
+ case 'POST /v1/invoices':
+ return HttpResponse.json({id: 'in_draft'});
+ case 'GET /v1/checkout/sessions/cs_b2b_1/line_items':
+ return HttpResponse.json({object: 'list', data: lines, has_more: false, url: url.pathname});
+ case 'POST /v1/invoiceitems':
+ return HttpResponse.json({id: 'ii_b2b'});
+ case 'POST /v1/invoices/in_draft/finalize':
+ return HttpResponse.json({id: 'in_final'});
+ case 'POST /v1/invoices/in_final/pay':
+ return HttpResponse.json({id: 'in_final', status: 'paid'});
+ case 'POST /v1/payment_intents/pi_b2b':
+ return HttpResponse.json({id: 'pi_b2b', metadata: {b2b_invoice_id: 'in_final'}});
+ default:
+ return HttpResponse.json({error: {message: 'Unexpected Stripe request'}}, {status: HttpStatus.BAD_REQUEST});
+ }
+ }),
+ );
+ const stripe = new Stripe('sk_test_b2b', {
+ apiVersion: STRIPE_API_VERSION,
+ httpClient: Stripe.createFetchHttpClient(),
+ maxNetworkRetries: 0,
+ });
+ return {stripe, requests};
+}
+
+describe('business invoices after checkout', () => {
+ test.each([
+ {label: 'without customer details', overrides: {customer_details: null}},
+ {label: 'without tax IDs', overrides: {customer_details: customerDetails({tax_ids: []})}},
+ {label: 'with null tax IDs', overrides: {customer_details: customerDetails({tax_ids: null})}},
+ {label: 'with an existing invoice', overrides: {invoice: 'in_existing'}},
+ {label: 'for a subscription', overrides: {mode: 'subscription'}},
+ {label: 'while unpaid', overrides: {payment_status: 'unpaid'}},
+ {label: 'without a customer', overrides: {customer: null}},
+ {label: 'with an empty customer ID', overrides: {customer: ''}},
+ ] satisfies Array<{label: string; overrides: Partial<Stripe.Checkout.Session>}>)(
+ 'skips checkout $label',
+ async ({overrides}) => {
+ const {stripe, requests} = recordStripeInvoices();
+ expect(await ensureB2BInvoiceForCheckout(stripe, session(overrides))).toBeNull();
+ expect(requests).toEqual([]);
+ },
+ );
+
+ test('creates and pays an invoice with checkout currency and stable request keys', async () => {
+ const {stripe, requests} = recordStripeInvoices();
+ expect(await ensureB2BInvoiceForCheckout(stripe, session())).toBe('in_final');
+ expect(requests.map(({method, path}) => `${method} ${path}`)).toEqual([
+ 'GET /v1/payment_intents/pi_b2b',
+ 'POST /v1/invoices',
+ 'GET /v1/checkout/sessions/cs_b2b_1/line_items',
+ 'POST /v1/invoiceitems',
+ 'POST /v1/invoices/in_draft/finalize',
+ 'POST /v1/invoices/in_final/pay',
+ 'POST /v1/payment_intents/pi_b2b',
+ ]);
+ expect(requests[1]).toMatchObject({
+ params: {
+ customer: 'cus_b2b',
+ currency: 'eur',
+ collection_method: 'send_invoice',
+ days_until_due: '0',
+ auto_advance: 'false',
+ pending_invoice_items_behavior: 'exclude',
+ 'automatic_tax[enabled]': 'true',
+ 'metadata[checkout_session_id]': 'cs_b2b_1',
+ 'metadata[payment_intent_id]': 'pi_b2b',
+ },
+ idempotencyKey: 'b2b-invoice:cs_b2b_1',
+ });
+ expect(requests[2]?.params).toEqual({limit: '20', 'expand[0]': 'data.price'});
+ expect(requests[3]).toMatchObject({
+ params: {
+ customer: 'cus_b2b',
+ invoice: 'in_draft',
+ currency: 'eur',
+ quantity: '2',
+ 'price_data[currency]': 'eur',
+ 'price_data[product]': 'prod_pass',
+ 'price_data[unit_amount]': '19900',
+ 'price_data[tax_behavior]': 'inclusive',
+ },
+ idempotencyKey: 'b2b-invoice-item:cs_b2b_1:0',
+ });
+ expect(requests[4]?.params).toEqual({auto_advance: 'false'});
+ expect(requests[5]).toMatchObject({params: {paid_out_of_band: 'true'}, idempotencyKey: 'b2b-invoice-pay:cs_b2b_1'});
+ expect(requests[6]?.params).toEqual({'metadata[b2b_invoice_id]': 'in_final'});
+ });
+
+ test('returns an already recorded invoice without writes', async () => {
+ const {stripe, requests} = recordStripeInvoices({existingInvoiceId: 'in_earlier'});
+ expect(await ensureB2BInvoiceForCheckout(stripe, session())).toBe('in_earlier');
+ expect(requests).toEqual([{method: 'GET', path: '/v1/payment_intents/pi_b2b', params: {}, idempotencyKey: null}]);
+ });
+
+ test('does nothing without Stripe', async () => {
+ const {requests} = recordStripeInvoices();
+ expect(await ensureB2BInvoiceForCheckout(null, session())).toBeNull();
+ expect(requests).toEqual([]);
+ });
+});