Evergreen farms (pos)

Background & Motivation¶

In production multi-tenant SaaS billing, two critical gaps needed closure:
1. When a suspended or past-due tenant settles their balance via the Stripe Customer Portal, their workspace previously remained blocked until manual administrator intervention.
2. Super Admin and Support teams lacked an auditable timeline in `saasBillingActionHistory` tracking exactly when billing emails were sent (payment receipts, payment failures, suspension alerts, pre-renewal notices, cancellation notices). Furthermore, sending multiple separate emails for receipt and workspace restoration created customer inbox clutter.

Key Features Implemented¶

1. Self-Healing Payment Recovery (`handleStripeInvoicePaid` & `handleStripeSubscriptionUpdated`): * Automatically detects when an incoming Stripe `invoice.paid` webhook settles an invoice for a tenant in `suspended` or `past_due` state. * Instantly unlocks the workspace by restoring root `company.status = "Active"`, `saasBilling.status = "active"`, and clearing `saasBilling.graceEndsAt = null`. * Automatically appends an audit event (`"Workspace restored"`) to `company.saasBillingActionHistory`. * Tenant immediately regains uninterrupted access across POS, eCommerce, and all operations without waiting for manual Super Admin action.

2. Single Consolidated Email for Payment Receipt & Workspace Restoration: * Unified payment confirmation and workspace reactivation notice into ONE single email (`sendBillingInvoiceEmail` with dynamic `isRestored` banner, clear receipt breakdown, and attached PDF invoice). * Eliminates sending duplicate emails to the tenant.

3. Automatic Email Audit Trail in Action History (`saasBillingActionHistory`): * Hooked up `dispatchDualNotification` in `subscriptionBillingMailer.js` and `sendBillingInvoiceEmail` / `sendBillingFailureEmail` in `tenantBilling.service.js`. * Every billing email dispatched to a tenant is automatically recorded in MongoDB: * Action: `"Email sent"` * Note: Clean summary (e.g., `Payment receipt email (Invoice #EG-803A6FC8, $79.00) sent to divya@yopmail.com with workspace restored notice`) * Performed By: `"Mailer"` * Metadata: `{ emailType, invoiceNumber, recipient, subject, ... }` * Covers: * Urgent Suspension Alerts (`sendSubscriptionStatusAlertEmail`) * Payment Failure & Grace Notices (`sendBillingFailureEmail`) * Pre-Renewal 7-Day Reminders (`sendSubscriptionRenewalReminderEmail`) * Payment Receipt & Recovery Notices (`sendBillingInvoiceEmail`) * Subscription Cancellation Scheduled / Resumed / Terminated Notices

4. Standard Recurring Renewal Audit: * Standard recurring payments now also log an explicit `"Subscription renewed"` event in `saasBillingActionHistory` ensuring full lifecycle visibility in both `TenantsListPage` and `CompanyDetailsPage`.

5. Tenant Status Terminology & UI Filtering: * Updated UI labels from ambiguous "Inactive" to "Deactivate" / "Deactivated" for clarity. * Added multi-status filters to the Tenants table (`Active`, `Suspended`, `Past Due`, `Deactivated`).