feat(deleter): clear or report org delete blockers up front

The delete first checks everything that blocks it and returns all the
reasons together as one failed_precondition response: unpaid (open or
uncollectible) invoices, and a negative token balance which support has
to settle. When nothing blocks, running subscriptions are canceled
immediately with unbilled usage invoiced on the spot, and the invoice
check runs again so a final invoice still blocks the delete. Unused
tokens do not block: the delete forfeits them and writes the amount to
an audit record. An already-deleted org returns not found before any
checks run. Invoice checks always sync from the billing provider first
so the decision is made on fresh data.

Author: whoAbhishekSah

billing/invoice/invoice.go

@@ -43,6 +43,9 @@ const (
 	DraftState State = "draft"
 	OpenState  State = "open"
 	PaidState  State = "paid"
+	// UncollectibleState marks an invoice the provider has written off; it
+	// can still be paid.
+	UncollectibleState State = "uncollectible"
 )
 
 type Invoice struct {

core/audit/audit.go

@@ -97,6 +97,7 @@ const (
 
 	BillingAccountDetailsUpdatedEvent EventName = "app.billing.account.details.updated"
 	BillingCheckoutDeletedEvent       EventName = "app.billing.checkout.deleted"
+	BillingTokensForfeitedEvent       EventName = "app.billing.tokens.forfeited"
 )
 
 var systemEvents = []EventName{
@@ -113,6 +114,7 @@ var systemEvents = []EventName{
 	OrgDeletedEvent,
 	OrgDisabledEvent,
 	BillingCheckoutDeletedEvent,
+	BillingTokensForfeitedEvent,
 }
 
 func IsSystemEvent(event EventName) bool {

core/deleter/deleter.go

@@ -1,7 +1,39 @@
 package deleter
 
-import "fmt"
+import "strings"
 
-var (
-	ErrDeleteNotAllowed = fmt.Errorf("deletion not allowed for billed accounts")
+// Blocker types returned by the org delete pre-flight check. They are
+// machine-readable and end up as PreconditionFailure violation types on
+// the API error, so clients can branch on them.
+const (
+	BlockerUnpaidInvoice        = "UNPAID_INVOICE"
+	BlockerNegativeTokenBalance = "NEGATIVE_TOKEN_BALANCE"
 )
+
+// Blocker is one reason an organization cannot be deleted right now. The
+// message names the fix: paying an invoice is something the caller can do
+// themselves, settling a token debt goes through support.
+type Blocker struct {
+	// Type is one of the Blocker* constants.
+	Type string
+	// Subject is the id of the blocking entity, e.g. a subscription id.
+	Subject string
+	// Message says what blocks the delete and what to do about it.
+	Message string
+}
+
+// BlockedError carries every blocker the pre-flight check found, so the
+// caller gets one checklist instead of discovering blockers one retry at
+// a time.
+type BlockedError struct {
+	OrgID    string
+	Blockers []Blocker
+}
+
+func (e *BlockedError) Error() string {
+	msgs := make([]string, 0, len(e.Blockers))
+	for _, b := range e.Blockers {
+		msgs = append(msgs, b.Message)
+	}
+	return "organization cannot be deleted yet: " + strings.Join(msgs, "; ")
+}

core/deleter/service.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"strconv"
 
 	"github.com/raystack/frontier/core/audit"
 
@@ -16,6 +17,8 @@ import (
 
 	"github.com/raystack/frontier/billing/customer"
 
+	"github.com/raystack/frontier/billing/subscription"
+
 	"github.com/raystack/frontier/core/organization"
 
 	"github.com/raystack/frontier/internal/bootstrap/schema"
@@ -34,10 +37,6 @@ import (
 	"github.com/raystack/frontier/core/serviceuser"
 )
 
-const (
-	DisableDeleteIfBilled = true
-)
-
 type ProjectService interface {
 	List(ctx context.Context, flt project.Filter) ([]project.Project, error)
 	DeleteModel(ctx context.Context, id string) error
@@ -98,11 +97,14 @@ type CustomerService interface {
 }
 
 type SubscriptionService interface {
+	List(ctx context.Context, filter subscription.Filter) ([]subscription.Subscription, error)
+	Cancel(ctx context.Context, id string, immediate bool) (subscription.Subscription, error)
 	DeleteByCustomer(ctx context.Context, customr customer.Customer) error
 }
 
 type InvoiceService interface {
 	List(ctx context.Context, flt invoice.Filter) ([]invoice.Invoice, error)
+	SyncWithProvider(ctx context.Context, customr customer.Customer) error
 	DeleteByCustomer(ctx context.Context, customr customer.Customer) error
 }
 
@@ -112,6 +114,7 @@ type CheckoutService interface {
 }
 
 type CreditService interface {
+	GetBalance(ctx context.Context, accountID string) (int64, error)
 	DeleteByAccountID(ctx context.Context, accountID string) error
 }
 
@@ -217,9 +220,16 @@ func (d Service) DeleteGroup(ctx context.Context, id string) error {
 // leaves the org owned and the delete can simply be run again. Every step
 // treats already-deleted data as success for the same reason.
 func (d Service) DeleteOrganization(ctx context.Context, id string) error {
-	// check if delete is allowed
-	if err := d.canDelete(ctx, id); err != nil {
-		return fmt.Errorf("%s: %w", err.Error(), ErrDeleteNotAllowed)
+	// an org that is already gone has nothing left to check or tear down;
+	// disabled orgs stay deletable
+	if _, err := d.orgService.Get(ctx, id); err != nil && !errors.Is(err, organization.ErrDisabled) {
+		return err
+	}
+
+	// clear what we can and collect what still blocks the delete, before
+	// touching any data
+	if err := d.preflight(ctx, id); err != nil {
+		return err
 	}
 
 	// delete all billing accounts
@@ -364,6 +374,22 @@ func (d Service) DeleteCustomers(ctx context.Context, id string) error {
 				slog.WarnContext(ctx, "failed to write audit log", "error", err, "event", audit.BillingCheckoutDeletedEvent, "checkout_id", ch.ID)
 			}
 		}
+		// tokens still on the account are forfeited by this delete, so
+		// record the amount before the transactions are removed
+		balance, err := d.creditService.GetBalance(ctx, c.ID)
+		if err != nil {
+			return fmt.Errorf("failed to delete org while checking balance of billing account[%s]: %w", c.ID, err)
+		}
+		if balance > 0 {
+			if err := auditLogger.LogWithAttrs(audit.BillingTokensForfeitedEvent, audit.Target{
+				ID:   c.ID,
+				Type: "billing_account",
+			}, map[string]string{
+				"amount": strconv.FormatInt(balance, 10),
+			}); err != nil {
+				slog.WarnContext(ctx, "failed to write audit log", "error", err, "event", audit.BillingTokensForfeitedEvent, "customer_id", c.ID)
+			}
+		}
 		if err := d.creditService.DeleteByAccountID(ctx, c.ID); err != nil {
 			return fmt.Errorf("failed to delete org while deleting a billing account transactions[%s]: %w", c.ID, err)
 		}
@@ -412,23 +438,117 @@ func (d Service) DeleteUser(ctx context.Context, userID string) error {
 	return d.userService.Delete(ctx, userID)
 }
 
-func (d Service) canDelete(ctx context.Context, id string) error {
-	// check if any invoice is present for customer
+// preflight collects everything that blocks deleting the organization and
+// returns it all as one BlockedError, so the caller gets a full checklist
+// instead of discovering blockers one retry at a time.
+//
+// Running subscriptions do not block: once nothing else does, preflight
+// cancels them itself, before any deletion starts. The cancel is immediate
+// and invoices unbilled usage on the spot, so the invoice check runs again
+// after it — a final invoice coming out of the cancellation still blocks
+// the delete until it is paid.
+//
+// Unused tokens do not block either: the delete forfeits them. The client
+// gets the caller's confirmation before sending the delete, and the
+// forfeited amount is written to an audit record during teardown.
+//
+// Accounts without a billing provider are only checked for token balances:
+// their subscription and invoice rows have nothing behind them the caller
+// could cancel or pay.
+func (d Service) preflight(ctx context.Context, id string) error {
 	customers, err := d.customerService.List(ctx, customer.Filter{
 		OrgID: id,
 	})
 	if err != nil {
 		return err
 	}
 
+	var blockers []Blocker
 	for _, c := range customers {
-		if invoices, err := d.invoiceService.List(ctx, invoice.Filter{CustomerID: c.ID}); err != nil {
-			return fmt.Errorf("failed to check invoices for billing account[%s]: %w", c.ID, err)
-		} else if len(invoices) > 0 {
-			if DisableDeleteIfBilled {
-				return fmt.Errorf("cannot delete organization with billing account[%s]", c.ID)
+		if !c.IsOffline() {
+			bs, err := d.invoiceBlockers(ctx, c)
+			if err != nil {
+				return err
 			}
+			blockers = append(blockers, bs...)
+		}
+
+		balance, err := d.creditService.GetBalance(ctx, c.ID)
+		if err != nil {
+			return fmt.Errorf("failed to check token balance of billing account[%s]: %w", c.ID, err)
 		}
+		if balance < 0 {
+			blockers = append(blockers, Blocker{
+				Type:    BlockerNegativeTokenBalance,
+				Subject: c.ID,
+				Message: fmt.Sprintf("billing account[%s] owes %d tokens: contact support to settle the balance, then retry the delete", c.ID, -balance),
+			})
+		}
+	}
+	if len(blockers) > 0 {
+		return &BlockedError{OrgID: id, Blockers: blockers}
+	}
+
+	// nothing blocks the delete so far; cancel running subscriptions and
+	// re-check the invoices the cancellation may have created. Subscriptions
+	// are only canceled once every other blocker is clear, so a delete that
+	// stays blocked does not cost the caller their subscription
+	for _, c := range customers {
+		if c.IsOffline() {
+			continue
+		}
+		subs, err := d.subService.List(ctx, subscription.Filter{CustomerID: c.ID})
+		if err != nil {
+			return fmt.Errorf("failed to check subscriptions for billing account[%s]: %w", c.ID, err)
+		}
+		canceled := false
+		for _, sub := range subs {
+			if !sub.IsActive() {
+				continue
+			}
+			if _, err := d.subService.Cancel(ctx, sub.ID, true); err != nil {
+				return fmt.Errorf("failed to cancel subscription[%s] of billing account[%s]: %w", sub.ID, c.ID, err)
+			}
+			canceled = true
+		}
+		if canceled {
+			bs, err := d.invoiceBlockers(ctx, c)
+			if err != nil {
+				return err
+			}
+			blockers = append(blockers, bs...)
+		}
+	}
+	if len(blockers) > 0 {
+		return &BlockedError{OrgID: id, Blockers: blockers}
 	}
 	return nil
 }
+
+// invoiceBlockers returns a blocker for every invoice of the account the
+// caller can still pay; paid, void, and draft invoices don't block. The
+// billing provider keeps its own permanent copy of every invoice, so
+// deleting our rows later loses nothing.
+func (d Service) invoiceBlockers(ctx context.Context, c customer.Customer) ([]Blocker, error) {
+	// the local invoice rows sync from the provider on a timer, so pull
+	// them fresh first: a just-paid invoice must not block, a just-created
+	// one must
+	if err := d.invoiceService.SyncWithProvider(ctx, c); err != nil {
+		return nil, fmt.Errorf("failed to sync invoices for billing account[%s]: %w", c.ID, err)
+	}
+	invoices, err := d.invoiceService.List(ctx, invoice.Filter{CustomerID: c.ID, NonZeroOnly: true})
+	if err != nil {
+		return nil, fmt.Errorf("failed to check invoices for billing account[%s]: %w", c.ID, err)
+	}
+	var blockers []Blocker
+	for _, inv := range invoices {
+		if inv.State == invoice.OpenState || inv.State == invoice.UncollectibleState {
+			blockers = append(blockers, Blocker{
+				Type:    BlockerUnpaidInvoice,
+				Subject: inv.ID,
+				Message: fmt.Sprintf("invoice[%s] is unpaid: pay it via its hosted payment page, then retry the delete", inv.ID),
+			})
+		}
+	}
+	return blockers, nil
+}