feat: generate invoice for overdraft credits

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 open(unpaid) invoice for overdraft
credits, no new invoice will be created for that customer.
Reconcilation of these invoice happens on same cadence as
invoices gets synced from the billing provider.

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

billing/config.go

@@ -30,6 +30,10 @@ 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"`
 }
 
 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/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,31 @@ var (
 	ErrInvalidDetail = fmt.Errorf("invalid invoice detail")
 )
 
+const (
+	ItemTypeMetadataKey   = "item_type"
+	ReconciledMetadataKey = "reconciled"
+
+	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 +48,39 @@ 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"`
+}
+
 type Filter struct {
 	CustomerID  string
 	NonZeroOnly bool
+	State       State
 
 	Pagination *pagination.Pagination
 }