From b5883bac0784504d343ffb714aa94b0b9fb63f1a Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 15 Nov 2026 11:38:47 +0100 Subject: [PATCH 1/3] feat(billing): balance alert mail subjects read unit word from config billing.alerts.balanceUnit (default 'credits') sets the unit word in the low-balance and out-of-balance mail subjects. Closes #4278 --- modules/billing/README.md | 2 ++ modules/billing/billing.email.js | 5 +++-- .../config/billing.development.config.js | 2 ++ .../billing.init.email-alerts.unit.tests.js | 20 +++++++++++++++++-- 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/modules/billing/README.md b/modules/billing/README.md index dd253ba20..034733403 100644 --- a/modules/billing/README.md +++ b/modules/billing/README.md @@ -122,6 +122,8 @@ e.g. `500 * (1 - 80/100) = 99.99999999999997`, silently missing an exact boundar comparing the debit's own pre/post balance, and emits `billing.extras.balance_threshold_crossed` (`{ organizationId, threshold, remaining, planId }`). `billing.email.js` sends a credit-warning (80%) or credit-exhausted (100%) email off of it. +The subjects use `billing.alerts.balanceUnit` as the unit word (default `'credits'`); set it +when your templates speak in another unit, so subject and body agree. - **Stateless — no `alertedAtN` field.** The weekly `alertedAt80`/`alertedAt100` fields are scoped to a week and would re-fire every week against a lifetime balance, so this diff --git a/modules/billing/billing.email.js b/modules/billing/billing.email.js index 56fbe9797..54a9a6dfb 100644 --- a/modules/billing/billing.email.js +++ b/modules/billing/billing.email.js @@ -114,6 +114,7 @@ export const setupBillingEmails = () => { const appName = mailer.getBrand().name ?? ''; const billingUrl = getBillingUrl(); const isWarning = threshold === 80; + const unit = config.billing?.alerts?.balanceUnit || 'credits'; resolveOrgAdminEmails(organizationId).then((emails) => { if (!emails.length) return; @@ -122,8 +123,8 @@ export const setupBillingEmails = () => { { to: email, subject: isWarning - ? `${appName} — your credits are running low` - : `${appName} — you are out of credits`, + ? `${appName} — your ${unit} are running low` + : `${appName} — you are out of ${unit}`, template: isWarning ? 'billing-credit-warning' : 'billing-credit-exhausted', params: { remaining: remaining ?? 0, diff --git a/modules/billing/config/billing.development.config.js b/modules/billing/config/billing.development.config.js index 34f6642a8..9b3fd87eb 100644 --- a/modules/billing/config/billing.development.config.js +++ b/modules/billing/config/billing.development.config.js @@ -137,6 +137,8 @@ const config = { }, alerts: { thresholdPercents: [80, 100], + // Unit word in the balance-alert mail subjects ("your credits are running low"). + balanceUnit: 'credits', }, events: { extrasExhausted: 'billing.extras_debit.exhausted', diff --git a/modules/billing/tests/billing.init.email-alerts.unit.tests.js b/modules/billing/tests/billing.init.email-alerts.unit.tests.js index 4bc724d22..c4af92afb 100644 --- a/modules/billing/tests/billing.init.email-alerts.unit.tests.js +++ b/modules/billing/tests/billing.init.email-alerts.unit.tests.js @@ -386,7 +386,7 @@ describe('billing.email setupBillingEmails listeners:', () => { expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ to: 'owner@test.com', - subject: expect.stringContaining('credits are running low'), + subject: 'MyApp — your credits are running low', template: 'billing-credit-warning', params: expect.objectContaining({ remaining: 100 }), }), @@ -406,13 +406,29 @@ describe('billing.email setupBillingEmails listeners:', () => { expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ to: 'owner@test.com', - subject: expect.stringContaining('out of credits'), + subject: 'MyApp — you are out of credits', template: 'billing-credit-exhausted', params: expect.objectContaining({ remaining: 0 }), }), ); }); + test('subjects use billing.alerts.balanceUnit when set', async () => { + mockConfig.billing.alerts = { balanceUnit: 'tokens' }; + + listeners['billing.extras.balance_threshold_crossed']({ organizationId: orgId, threshold: 80, remaining: 10, planId: 'free' }); + listeners['billing.extras.balance_threshold_crossed']({ organizationId: orgId, threshold: 100, remaining: 0, planId: 'free' }); + + await new Promise((r) => setImmediate(r)); + + expect(mockMailer.sendMail).toHaveBeenCalledWith( + expect.objectContaining({ subject: 'MyApp — your tokens are running low' }), + ); + expect(mockMailer.sendMail).toHaveBeenCalledWith( + expect.objectContaining({ subject: 'MyApp — you are out of tokens' }), + ); + }); + test('subject includes appName from brand (falls back to config.app.title), never the org id/name', async () => { listeners['billing.extras.balance_threshold_crossed']({ organizationId: orgId, From 7885e1cd648a4cc7cbd6c73834c4430fc4dbdf7b Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 15 Nov 2026 11:47:01 +0100 Subject: [PATCH 2/3] fix(billing): unit-agnostic low-balance subject wording --- modules/billing/billing.email.js | 2 +- modules/billing/config/billing.development.config.js | 2 +- modules/billing/tests/billing.init.email-alerts.unit.tests.js | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/billing/billing.email.js b/modules/billing/billing.email.js index 54a9a6dfb..ec159751b 100644 --- a/modules/billing/billing.email.js +++ b/modules/billing/billing.email.js @@ -123,7 +123,7 @@ export const setupBillingEmails = () => { { to: email, subject: isWarning - ? `${appName} — your ${unit} are running low` + ? `${appName} — you are running low on ${unit}` : `${appName} — you are out of ${unit}`, template: isWarning ? 'billing-credit-warning' : 'billing-credit-exhausted', params: { diff --git a/modules/billing/config/billing.development.config.js b/modules/billing/config/billing.development.config.js index 9b3fd87eb..f71209b55 100644 --- a/modules/billing/config/billing.development.config.js +++ b/modules/billing/config/billing.development.config.js @@ -137,7 +137,7 @@ const config = { }, alerts: { thresholdPercents: [80, 100], - // Unit word in the balance-alert mail subjects ("your credits are running low"). + // Unit word in the balance-alert mail subjects ("you are running low on credits"). balanceUnit: 'credits', }, events: { diff --git a/modules/billing/tests/billing.init.email-alerts.unit.tests.js b/modules/billing/tests/billing.init.email-alerts.unit.tests.js index c4af92afb..95ff1315b 100644 --- a/modules/billing/tests/billing.init.email-alerts.unit.tests.js +++ b/modules/billing/tests/billing.init.email-alerts.unit.tests.js @@ -386,7 +386,7 @@ describe('billing.email setupBillingEmails listeners:', () => { expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ to: 'owner@test.com', - subject: 'MyApp — your credits are running low', + subject: 'MyApp — you are running low on credits', template: 'billing-credit-warning', params: expect.objectContaining({ remaining: 100 }), }), @@ -422,7 +422,7 @@ describe('billing.email setupBillingEmails listeners:', () => { await new Promise((r) => setImmediate(r)); expect(mockMailer.sendMail).toHaveBeenCalledWith( - expect.objectContaining({ subject: 'MyApp — your tokens are running low' }), + expect.objectContaining({ subject: 'MyApp — you are running low on tokens' }), ); expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ subject: 'MyApp — you are out of tokens' }), From 9fa286037363c88eb9e43ca88dbd090e6e1692b8 Mon Sep 17 00:00:00 2001 From: Pierre Brisorgueil Date: Sun, 15 Nov 2026 12:00:37 +0100 Subject: [PATCH 3/3] fix(billing): keep default balance subjects unchanged, document plural unit word --- modules/billing/README.md | 2 +- modules/billing/billing.email.js | 2 +- modules/billing/config/billing.development.config.js | 2 +- modules/billing/tests/billing.init.email-alerts.unit.tests.js | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/billing/README.md b/modules/billing/README.md index 034733403..34567b912 100644 --- a/modules/billing/README.md +++ b/modules/billing/README.md @@ -122,7 +122,7 @@ e.g. `500 * (1 - 80/100) = 99.99999999999997`, silently missing an exact boundar comparing the debit's own pre/post balance, and emits `billing.extras.balance_threshold_crossed` (`{ organizationId, threshold, remaining, planId }`). `billing.email.js` sends a credit-warning (80%) or credit-exhausted (100%) email off of it. -The subjects use `billing.alerts.balanceUnit` as the unit word (default `'credits'`); set it +The subjects use `billing.alerts.balanceUnit` as a plural unit word (default `'credits'`); set it when your templates speak in another unit, so subject and body agree. - **Stateless — no `alertedAtN` field.** The weekly `alertedAt80`/`alertedAt100` fields diff --git a/modules/billing/billing.email.js b/modules/billing/billing.email.js index ec159751b..54a9a6dfb 100644 --- a/modules/billing/billing.email.js +++ b/modules/billing/billing.email.js @@ -123,7 +123,7 @@ export const setupBillingEmails = () => { { to: email, subject: isWarning - ? `${appName} — you are running low on ${unit}` + ? `${appName} — your ${unit} are running low` : `${appName} — you are out of ${unit}`, template: isWarning ? 'billing-credit-warning' : 'billing-credit-exhausted', params: { diff --git a/modules/billing/config/billing.development.config.js b/modules/billing/config/billing.development.config.js index f71209b55..f28e9682d 100644 --- a/modules/billing/config/billing.development.config.js +++ b/modules/billing/config/billing.development.config.js @@ -137,7 +137,7 @@ const config = { }, alerts: { thresholdPercents: [80, 100], - // Unit word in the balance-alert mail subjects ("you are running low on credits"). + // Plural unit word in the balance-alert mail subjects ("your credits are running low"). balanceUnit: 'credits', }, events: { diff --git a/modules/billing/tests/billing.init.email-alerts.unit.tests.js b/modules/billing/tests/billing.init.email-alerts.unit.tests.js index 95ff1315b..c4af92afb 100644 --- a/modules/billing/tests/billing.init.email-alerts.unit.tests.js +++ b/modules/billing/tests/billing.init.email-alerts.unit.tests.js @@ -386,7 +386,7 @@ describe('billing.email setupBillingEmails listeners:', () => { expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ to: 'owner@test.com', - subject: 'MyApp — you are running low on credits', + subject: 'MyApp — your credits are running low', template: 'billing-credit-warning', params: expect.objectContaining({ remaining: 100 }), }), @@ -422,7 +422,7 @@ describe('billing.email setupBillingEmails listeners:', () => { await new Promise((r) => setImmediate(r)); expect(mockMailer.sendMail).toHaveBeenCalledWith( - expect.objectContaining({ subject: 'MyApp — you are running low on tokens' }), + expect.objectContaining({ subject: 'MyApp — your tokens are running low' }), ); expect(mockMailer.sendMail).toHaveBeenCalledWith( expect.objectContaining({ subject: 'MyApp — you are out of tokens' }),