feat: generate invoice for overdraft credits (#796)

It's necessary to configure the product name to calculate
per unit price before the overdraft credits can be invoiced
in `billing.customer.credit_overdraft_product`.
If not set, invoice reconcilation and creation is skipped.

If there is already an invoice for overdraft credits for same
time range, no new invoice will be created for that customer.
Currently the system generates them on the first day of the month.
When the overdraft invoice is created for the first time, it
accounts for transactions from the start of customer life but
then moving forward only accounts from the last month time
range.

Reconcilation of these invoice happens on same cadence as
invoices gets synced from the billing provider.

Signed-off-by: Kush Sharma <[email protected]>

Makefile

@@ -4,7 +4,7 @@ TAG := $(shell git rev-list --tags --max-count=1)
 VERSION := $(shell git describe --tags ${TAG})
 .PHONY: build check fmt lint test test-race vet test-cover-html help install proto ui compose-up-dev
 .DEFAULT_GOAL := build
-PROTON_COMMIT := "5e5f98bafba2a218b35a9130d75bd68980151d00"
+PROTON_COMMIT := "251281aa0c311904eb263eb9bfa7e3b9c41f99b0"
 
 ui:
 	@echo " > generating ui build"

billing/config.go

@@ -30,6 +30,17 @@ type AccountConfig struct {
 	DefaultPlan           string `yaml:"default_plan" mapstructure:"default_plan"`
 	DefaultOffline        bool   `yaml:"default_offline" mapstructure:"default_offline"`
 	OnboardCreditsWithOrg int64  `yaml:"onboard_credits_with_org" mapstructure:"onboard_credits_with_org"`
+
+	// CreditOverdraftProduct helps identify the product pricing per unit amount for the overdraft
+	// credits being invoiced
+	CreditOverdraftProduct string `yaml:"credit_overdraft_product" mapstructure:"credit_overdraft_product"`
+
+	// CreditOverdraftInvoiceDay is the day of the range(month) when the overdraft credits are invoiced
+	CreditOverdraftInvoiceDay int `yaml:"credit_overdraft_invoice_day" mapstructure:"credit_overdraft_invoice_day" default:"1"`
+
+	// CreditOverdraftInvoiceRangeShift is the shift in the invoice range for the overdraft credits
+	// if positive, the invoice range will be shifted to the future else it will be shifted to the past
+	CreditOverdraftInvoiceRangeShift int `yaml:"credit_overdraft_invoice_range_shift" mapstructure:"credit_overdraft_invoice_range_shift" default:"0"`
 }
 
 type PlanChangeConfig struct {

billing/credit/credit.go

@@ -2,6 +2,7 @@ package credit
 
 import (
 	"errors"
+	"strings"
 	"time"
 
 	"github.com/google/uuid"
@@ -20,10 +21,11 @@ var (
 	// TxNamespaceUUID is the namespace for generating transaction UUIDs deterministically
 	TxNamespaceUUID = uuid.MustParse("967416d0-716e-4308-b58f-2468ac14f20a")
 
-	SourceSystemBuyEvent     = "system.buy"
-	SourceSystemAwardedEvent = "system.awarded"
-	SourceSystemOnboardEvent = "system.starter"
-	SourceSystemRevertEvent  = "system.revert"
+	SourceSystemBuyEvent       = "system.buy"
+	SourceSystemAwardedEvent   = "system.awarded"
+	SourceSystemOnboardEvent   = "system.starter"
+	SourceSystemRevertEvent    = "system.revert"
+	SourceSystemOverdraftEvent = "system.overdraft"
 )
 
 type TransactionType string
@@ -71,3 +73,7 @@ type Filter struct {
 	StartRange time.Time
 	EndRange   time.Time
 }
+
+func TxUUID(tags ...string) string {
+	return uuid.NewSHA1(TxNamespaceUUID, []byte(strings.Join(tags, ":"))).String()
+}

billing/credit/service.go

@@ -3,6 +3,7 @@ package credit
 import (
 	"context"
 	"fmt"
+	"time"
 
 	"github.com/pkg/errors"
 
@@ -14,6 +15,7 @@ type TransactionRepository interface {
 	GetBalance(ctx context.Context, id string) (int64, error)
 	List(ctx context.Context, flt Filter) ([]Transaction, error)
 	GetByID(ctx context.Context, id string) (Transaction, error)
+	GetBalanceForRange(ctx context.Context, accountID string, start time.Time, end time.Time) (int64, error)
 }
 
 type Service struct {
@@ -115,6 +117,12 @@ func (s Service) GetBalance(ctx context.Context, accountID string) (int64, error
 	return s.transactionRepository.GetBalance(ctx, accountID)
 }
 
+// GetBalanceForRange returns the balance for the given accountID within the given time range
+// start time is inclusive, end time is exclusive
+func (s Service) GetBalanceForRange(ctx context.Context, accountID string, start time.Time, end time.Time) (int64, error) {
+	return s.transactionRepository.GetBalanceForRange(ctx, accountID, start, end)
+}
+
 func (s Service) GetByID(ctx context.Context, id string) (Transaction, error) {
 	return s.transactionRepository.GetByID(ctx, id)
 }

billing/customer/customer.go

@@ -82,6 +82,9 @@ type Filter struct {
 	OrgID      string
 	ProviderID string
 	State      State
+
+	Online           *bool
+	AllowedOverdraft *bool
 }
 
 type PaymentMethod struct {

billing/invoice/invoice.go

@@ -14,11 +14,42 @@ var (
 	ErrInvalidDetail = fmt.Errorf("invalid invoice detail")
 )
 
+const (
+	// ItemIDMetadataKey is used to uniquely identify the item in the invoice
+	// this is useful when reconciling the invoice items for payments and
+	// avoid creating duplicate credits
+	ItemIDMetadataKey = "item_id"
+	// ItemTypeMetadataKey is used to identify the item type in the invoice
+	// this is useful when reconciling the invoice items for payments and
+	// avoid creating duplicate invoices
+	ItemTypeMetadataKey = "item_type"
+
+	// ReconciledMetadataKey marks the invoice as reconciled and avoid processing it again
+	// as an optimization
+	ReconciledMetadataKey = "reconciled"
+
+	// GenerateForCreditLockKey is used to lock the invoice generation within current application
+	GenerateForCreditLockKey = "generate_for_credit"
+)
+
+type State string
+
+func (s State) String() string {
+	return string(s)
+}
+
+const (
+	DraftState State = "draft"
+	OpenState  State = "open"
+	PaidState  State = "paid"
+)
+
 type Invoice struct {
-	ID            string
-	CustomerID    string
-	ProviderID    string
-	State         string
+	ID         string
+	CustomerID string
+	ProviderID string
+	// State could be one of draft, open, paid, uncollectible, void
+	State         State
 	Currency      string
 	Amount        int64
 	HostedURL     string
@@ -28,12 +59,44 @@ type Invoice struct {
 	PeriodStartAt time.Time
 	PeriodEndAt   time.Time
 
+	Items    []Item
 	Metadata metadata.Metadata
 }
 
+type ItemType string
+
+func (t ItemType) String() string {
+	return string(t)
+}
+
+const (
+	// CreditItemType is used to charge for the credits used in the system
+	// as overdraft
+	CreditItemType ItemType = "credit"
+)
+
+type Item struct {
+	ID         string `json:"id"`
+	ProviderID string `json:"provider_id"`
+	// Name is the item name
+	Name string `json:"name"`
+	// Type is the item type
+	Type ItemType `json:"type"`
+	// UnitAmount is per unit cost
+	UnitAmount int64 `json:"unit_amount"`
+	// Quantity is the number of units
+	Quantity int64 `json:"quantity"`
+
+	// TimeRangeStart is the start time of the item since it's effective
+	TimeRangeStart *time.Time `json:"range_start"`
+	// TimeRangeEnd is the end time of the item since it's effective
+	TimeRangeEnd *time.Time `json:"range_end"`
+}
+
 type Filter struct {
 	CustomerID  string
 	NonZeroOnly bool
+	State       State
 
 	Pagination *pagination.Pagination
 }