feat: add AvailableFrom for income transactions

With this field, you can set for which month an income transaction
will be counted towards the available for budget sum.

This also updates the YNAB 4 importer to set the AvailableFrom field
to the following month for all transactions that are marked as
„Income for next month“ in YNAB 4.

Author: morremeyer

api/docs.go

@@ -3257,6 +3257,11 @@ const docTemplate = `{
                     "multipleOf": 1e-8,
                     "example": 14.03
                 },
+                "availableFrom": {
+                    "description": "The date from which on the transaction amount is available for budgeting. Only used for income transactions. Defaults to the transaction date.",
+                    "type": "string",
+                    "example": "2021-11-17:00:00:00Z"
+                },
                 "budgetId": {
                     "type": "string",
                     "example": "55eecbd8-7c46-4b06-ada9-f287802fb05e"
@@ -3719,6 +3724,11 @@ const docTemplate = `{
                     "multipleOf": 1e-8,
                     "example": 14.03
                 },
+                "availableFrom": {
+                    "description": "The date from which on the transaction amount is available for budgeting. Only used for income transactions. Defaults to the transaction date.",
+                    "type": "string",
+                    "example": "2021-11-17:00:00:00Z"
+                },
                 "budgetId": {
                     "type": "string",
                     "example": "55eecbd8-7c46-4b06-ada9-f287802fb05e"

api/swagger.json

@@ -3245,6 +3245,11 @@
                     "multipleOf": 1e-8,
                     "example": 14.03
                 },
+                "availableFrom": {
+                    "description": "The date from which on the transaction amount is available for budgeting. Only used for income transactions. Defaults to the transaction date.",
+                    "type": "string",
+                    "example": "2021-11-17:00:00:00Z"
+                },
                 "budgetId": {
                     "type": "string",
                     "example": "55eecbd8-7c46-4b06-ada9-f287802fb05e"
@@ -3707,6 +3712,11 @@
                     "multipleOf": 1e-8,
                     "example": 14.03
                 },
+                "availableFrom": {
+                    "description": "The date from which on the transaction amount is available for budgeting. Only used for income transactions. Defaults to the transaction date.",
+                    "type": "string",
+                    "example": "2021-11-17:00:00:00Z"
+                },
                 "budgetId": {
                     "type": "string",
                     "example": "55eecbd8-7c46-4b06-ada9-f287802fb05e"

api/swagger.yaml

@@ -403,6 +403,12 @@ definitions:
         minimum: 1e-08
         multipleOf: 1e-08
         type: number
+      availableFrom:
+        description: The date from which on the transaction amount is available for
+          budgeting. Only used for income transactions. Defaults to the transaction
+          date.
+        example: 2021-11-17:00:00:00Z
+        type: string
       budgetId:
         example: 55eecbd8-7c46-4b06-ada9-f287802fb05e
         type: string
@@ -749,6 +755,12 @@ definitions:
         minimum: 1e-08
         multipleOf: 1e-08
         type: number
+      availableFrom:
+        description: The date from which on the transaction amount is available for
+          budgeting. Only used for income transactions. Defaults to the transaction
+          date.
+        example: 2021-11-17:00:00:00Z
+        type: string
       budgetId:
         example: 55eecbd8-7c46-4b06-ada9-f287802fb05e
         type: string

pkg/importer/parser/ynab4/parse.go

@@ -304,6 +304,10 @@ func parseTransactions(resources *types.ParsedResources, transactions []Transact
 			newTransaction.Model.TransactionCreate.Reconciled = true
 		}
 
+		if transaction.CategoryID == "Category/__DeferredIncome__" {
+			newTransaction.Model.AvailableFrom = internal_types.MonthOf(date).AddDate(0, 1)
+		}
+
 		// No subtransactions, add transaction directly
 		if len(transaction.SubTransactions) == 0 {
 			if mapping, ok := envelopeIDNames[transaction.CategoryID]; ok {
@@ -326,6 +330,12 @@ func parseTransactions(resources *types.ParsedResources, transactions []Transact
 				newTransaction.Category = ""
 			}
 
+			if sub.CategoryID == "Category/__DeferredIncome__" {
+				newTransaction.Model.AvailableFrom = internal_types.MonthOf(date).AddDate(0, 1)
+			} else {
+				newTransaction.Model.AvailableFrom = internal_types.MonthOf(date)
+			}
+
 			if sub.Amount.IsPositive() {
 				newTransaction.Model.Amount = sub.Amount
 			} else {

pkg/models/account.go

@@ -71,37 +71,49 @@ func (a Account) SumReconciledTransactions(db *gorm.DB) decimal.Decimal {
 	))
 }
 
-// GetBalanceMonth calculates the balance at the end of a specific month.
-func (a Account) GetBalanceMonth(db *gorm.DB, month types.Month) (decimal.Decimal, error) {
+// GetBalanceMonth calculates the balance and available sums for a specific month.
+//
+// The balance Decimal is the actual account balance, factoring in all transactions before the end of the month.
+// The available Decimal is the sum that is available for budgeting at the end of the specified month.
+func (a Account) GetBalanceMonth(db *gorm.DB, month types.Month) (balance, available decimal.Decimal, err error) {
 	var transactions []Transaction
 
-	err := db.
+	err = db.
+		Preload("DestinationAccount").
+		Preload("SourceAccount").
 		Where("transactions.date < date(?)", month.AddDate(0, 1)).
 		Where(
 			db.Where(Transaction{TransactionCreate: TransactionCreate{DestinationAccountID: a.ID}}).
 				Or(db.Where(Transaction{TransactionCreate: TransactionCreate{SourceAccountID: a.ID}}))).
 		Find(&transactions).
 		Error
 	if err != nil {
-		return decimal.Zero, err
+		return decimal.Zero, decimal.Zero, err
 	}
 
-	sum := decimal.Zero
-
 	if a.InitialBalanceDate != nil && month.AddDate(0, 1).AfterTime(*a.InitialBalanceDate) {
-		sum = a.InitialBalance
+		balance = a.InitialBalance
+		available = a.InitialBalance
 	}
 
 	// Add incoming transactions, subtract outgoing transactions
+	// For available, only do so if the next month is after the availableFrom date
 	for _, t := range transactions {
 		if t.DestinationAccountID == a.ID {
-			sum = sum.Add(t.Amount)
+			balance = balance.Add(t.Amount)
+
+			// If the transaction is an income transaction, but its AvailableFrom is after this month, skip it
+			if !month.AddDate(0, 1).After(t.AvailableFrom) && t.SourceAccount.External && t.EnvelopeID == nil {
+				continue
+			}
+			available = available.Add(t.Amount)
 		} else {
-			sum = sum.Sub(t.Amount)
+			balance = balance.Sub(t.Amount)
+			available = available.Sub(t.Amount)
 		}
 	}
 
-	return sum, nil
+	return
 }
 
 // getBalance returns the balance of the account calculated over all transactions.

pkg/models/account_test.go

@@ -95,25 +95,47 @@ func (suite *TestSuiteStandard) TestAccountCalculations() {
 		suite.Assert().Fail("Resource could not be saved", err)
 	}
 
-	a := account.WithCalculations(suite.db)
+	futureIncomeTransaction := suite.createTestTransaction(models.TransactionCreate{
+		BudgetID:             budget.ID,
+		SourceAccountID:      externalAccount.ID,
+		DestinationAccountID: account.ID,
+		Amount:               decimal.NewFromFloat(100),
+		AvailableFrom:        types.MonthOf(time.Now()).AddDate(0, 1),
+		Note:                 "Future Income Transaction",
+	})
+	err = suite.db.Save(&futureIncomeTransaction).Error
+	if err != nil {
+		suite.Assert().Fail("Resource could not be saved", err)
+	}
 
-	assert.True(suite.T(), a.Balance.Equal(incomingTransaction.Amount.Sub(outgoingTransaction.Amount).Add(a.InitialBalance)), "Balance for account is not correct. Should be: %v but is %v", incomingTransaction.Amount.Sub(outgoingTransaction.Amount), a.Balance)
+	a := account.WithCalculations(suite.db)
 
-	assert.True(suite.T(), a.ReconciledBalance.Equal(incomingTransaction.Amount.Add(a.InitialBalance)), "Reconciled balance for account is not correct. Should be: %v but is %v", incomingTransaction.Amount, a.ReconciledBalance)
+	expected := incomingTransaction.Amount.Sub(outgoingTransaction.Amount).Add(a.InitialBalance).Add(decimal.NewFromFloat(100)) // Add 100 for futureIncomeTransaction
+	assert.True(suite.T(), a.Balance.Equal(expected), "Balance for account is not correct. Should be: %v but is %v", expected, a.Balance)
 
-	balanceNow, err := account.GetBalanceMonth(suite.db, types.Month(time.Now()))
+	expected = incomingTransaction.Amount.Add(a.InitialBalance)
+	assert.True(suite.T(), a.ReconciledBalance.Equal(expected), "Reconciled balance for account is not correct. Should be: %v but is %v", expected, a.ReconciledBalance)
 
+	balanceNow, availableNow, err := account.GetBalanceMonth(suite.db, types.MonthOf(time.Now()))
 	assert.Nil(suite.T(), err)
-	assert.True(suite.T(), balanceNow.Equal(decimal.NewFromFloat(184.72)), "Current balance for account is not correct. Should be: %v but is %v", decimal.NewFromFloat(184.72), balanceNow)
+
+	expected = decimal.NewFromFloat(284.72)
+	assert.True(suite.T(), balanceNow.Equal(expected), "Current balance for account is not correct. Should be: %v but is %v", expected, balanceNow)
+
+	expected = decimal.NewFromFloat(184.72)
+	assert.True(suite.T(), availableNow.Equal(expected), "Available balance for account is not correct. Should be: %v but is %v", expected, availableNow)
 
 	err = suite.db.Delete(&incomingTransaction).Error
 	if err != nil {
 		suite.Assert().Fail("Resource could not be deleted", err)
 	}
 
 	a = account.WithCalculations(suite.db)
-	assert.True(suite.T(), a.Balance.Equal(outgoingTransaction.Amount.Neg().Add(a.InitialBalance)), "Balance for account is not correct. Should be: %v but is %v", outgoingTransaction.Amount.Neg(), a.Balance)
-	assert.True(suite.T(), a.ReconciledBalance.Equal(decimal.NewFromFloat(0).Add(a.InitialBalance)), "Reconciled balance for account is not correct. Should be: %v but is %v", decimal.NewFromFloat(0), a.ReconciledBalance)
+	expected = outgoingTransaction.Amount.Neg().Add(a.InitialBalance).Add(decimal.NewFromFloat(100)) // Add 100 for futureIncomeTransaction
+	assert.True(suite.T(), a.Balance.Equal(expected), "Balance for account is not correct. Should be: %v but is %v", expected, a.Balance)
+
+	expected = decimal.NewFromFloat(0).Add(a.InitialBalance)
+	assert.True(suite.T(), a.ReconciledBalance.Equal(expected), "Reconciled balance for account is not correct. Should be: %v but is %v", expected, a.ReconciledBalance)
 }
 
 func (suite *TestSuiteStandard) TestAccountTransactions() {
@@ -256,7 +278,7 @@ func (suite *TestSuiteStandard) TestAccountGetBalanceMonthDBFail() {
 
 	suite.CloseDB()
 
-	_, err := account.GetBalanceMonth(suite.db, types.NewMonth(2017, 7))
+	_, _, err := account.GetBalanceMonth(suite.db, types.NewMonth(2017, 7))
 	suite.Assert().NotNil(err)
 	suite.Assert().Equal("sql: database is closed", err.Error())
 }

pkg/models/budget.go

@@ -313,11 +313,11 @@ func (b Budget) Month(db *gorm.DB, month types.Month, baseURL string) (Month, er
 
 	// Add all on-balance accounts to the available sum
 	for _, a := range accounts {
-		b, err := a.GetBalanceMonth(db, month)
+		_, available, err := a.GetBalanceMonth(db, month)
 		if err != nil {
 			return Month{}, err
 		}
-		result.Available = result.Available.Add(b)
+		result.Available = result.Available.Add(available)
 	}
 
 	return result, nil

pkg/models/transaction.go

@@ -3,6 +3,7 @@ package models
 import (
 	"time"
 
+	"github.com/envelope-zero/backend/internal/types"
 	"github.com/google/uuid"
 	"github.com/shopspring/decimal"
 	"gorm.io/gorm"
@@ -27,6 +28,7 @@ type TransactionCreate struct {
 	DestinationAccountID uuid.UUID       `json:"destinationAccountId" example:"8e16b456-a719-48ce-9fec-e115cfa7cbcc"`
 	EnvelopeID           *uuid.UUID      `json:"envelopeId" example:"2649c965-7999-4873-ae16-89d5d5fa972e"`
 	Reconciled           bool            `json:"reconciled" example:"true" default:"false"`
+	AvailableFrom        types.Month     `json:"availableFrom" example:"2021-11-17:00:00:00Z"` // The date from which on the transaction amount is available for budgeting. Only used for income transactions. Defaults to the transaction date.
 }
 
 // AfterFind updates the timestamps to use UTC as
@@ -52,5 +54,10 @@ func (t *Transaction) BeforeSave(tx *gorm.DB) (err error) {
 		t.Date = t.Date.In(time.UTC)
 	}
 
+	// Default the AvailableForBudget date to the transaction date
+	if t.AvailableFrom.IsZero() {
+		t.AvailableFrom = types.MonthOf(t.Date)
+	}
+
 	return nil
 }