update: Plaid automatic transaction import with double entry accounting

app/Casts/MoneyCast.php

@@ -11,7 +11,7 @@ class MoneyCast implements CastsAttributes
 {
     public function get(Model $model, string $key, mixed $value, array $attributes): string
     {
-        $currency_code = $model->getAttribute('currency_code');
+        $currency_code = $model->getAttribute('currency_code') ?? CurrencyAccessor::getDefaultCurrency();
 
         if ($value !== null) {
             return money($value, $currency_code)->formatSimple();

app/Filament/Company/Resources/Accounting/TransactionResource.php

@@ -5,7 +5,7 @@ namespace App\Filament\Company\Resources\Accounting;
 use App\Enums\DateFormat;
 use App\Filament\Company\Resources\Accounting\TransactionResource\Pages;
 use App\Models\Accounting\Transaction;
-use App\Models\Banking\Account;
+use App\Models\Banking\BankAccount;
 use App\Models\Setting\Localization;
 use Filament\Forms;
 use Filament\Forms\Form;
@@ -49,14 +49,12 @@ class TransactionResource extends Resource
                 Forms\Components\TextInput::make('amount')
                     ->label('Amount')
                     ->money(static function (Forms\Get $get) {
-                        $account = $get('account_id');
+                        $bankAccount = $get('bank_account_id');
+                        $bankAccount = BankAccount::find($bankAccount);
+                        $account = $bankAccount->account ?? null;
 
                         if ($account) {
-                            $account = Account::find($account);
-
-                            if ($account) {
-                                return $account->currency_code;
-                            }
+                            return $account->currency_code;
                         }
 
                         return 'USD';
@@ -98,7 +96,7 @@ class TransactionResource extends Resource
                     ->sortable()
                     ->weight(FontWeight::Medium)
                     ->color(static fn (Transaction $record) => $record->type === 'expense' ? 'danger' : null)
-                    ->currency(static fn (Transaction $record) => $record->account->currency_code, true),
+                    ->currency(static fn (Transaction $record) => $record->bankAccount->account->currency_code ?? 'USD', true),
             ])
             ->filters([
                 //

app/Filament/Company/Resources/Banking/AccountResource.php

@@ -198,7 +198,7 @@ class AccountResource extends Resource
                     ->iconPosition('after')
                     ->description(static fn (BankAccount $record) => $record->mask ?: 'N/A')
                     ->sortable(),
-                Tables\Columns\TextColumn::make('account.starting_balance')
+                Tables\Columns\TextColumn::make('account.ending_balance')
                     ->localizeLabel('Current Balance')
                     ->sortable()
                     ->currency(static fn (BankAccount $record) => $record->account->currency_code, true),

app/Listeners/HandleTransactionImport.php

@@ -2,15 +2,23 @@
 
 namespace App\Listeners;
 
+use App\Enums\Accounting\AccountCategory;
+use App\Enums\Accounting\AccountType;
 use App\Events\StartTransactionImport;
+use App\Models\Accounting\Account;
 use App\Models\Accounting\AccountSubtype;
+use App\Models\Accounting\Transaction;
 use App\Models\Banking\BankAccount;
 use App\Models\Banking\ConnectedBankAccount;
 use App\Models\Company;
+use App\Models\Setting\Category;
 use App\Models\Setting\Currency;
 use App\Services\PlaidService;
 use App\Utilities\Currency\CurrencyAccessor;
+use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
 
 class HandleTransactionImport
 {
@@ -43,20 +51,184 @@ class HandleTransactionImport
 
         $accessToken = $connectedBankAccount->access_token;
 
-        if ($selectedBankAccountId === 'new') {
-            $bankAccount = $this->processNewBankAccount($company, $connectedBankAccount, $accessToken);
-        } else {
-            $bankAccount = BankAccount::find($selectedBankAccountId);
+        $bankAccount = $selectedBankAccountId === 'new'
+            ? $this->processNewBankAccount($company, $connectedBankAccount, $accessToken)
+            : BankAccount::find($selectedBankAccountId);
+
+        if ($bankAccount) {
+            $connectedBankAccount->update([
+                'bank_account_id' => $bankAccount->id,
+                'import_transactions' => true,
+            ]);
+
+            $account = $bankAccount->account;
+
+            $this->processTransactions($startDate, $company, $connectedBankAccount, $accessToken, $account);
+        }
+    }
+
+    public function processTransactions($startDate, Company $company, ConnectedBankAccount $connectedBankAccount, $accessToken, Account $account): void
+    {
+        $endDate = Carbon::now()->toDateString();
+        $startDate = Carbon::parse($startDate)->toDateString();
+
+        $transactionsResponse = $this->plaid->getTransactions($accessToken, $startDate, $endDate, [
+            'account_ids' => [$connectedBankAccount->external_account_id],
+        ]);
 
-            if ($bankAccount === null) {
-                return;
+        if (! empty($transactionsResponse->transactions)) {
+            foreach ($transactionsResponse->transactions as $transaction) {
+                $this->storeTransaction($company, $account, $connectedBankAccount, $transaction);
             }
         }
+    }
+
+    public function storeTransaction(Company $company, Account $account, ConnectedBankAccount $connectedBankAccount, $transaction): void
+    {
+        if ($account->category === AccountCategory::Asset) {
+            $transactionType = $transaction->amount < 0 ? 'income' : 'expense';
+        } else {
+            $transactionType = $transaction->amount < 0 ? 'expense' : 'income';
+        }
+
+        $method = $transactionType === 'income' ? 'deposit' : 'withdrawal';
+        $paymentChannel = $transaction->payment_channel ?? 'other';
+        $category = $this->getCategoryFromTransaction($company, $transaction, $transactionType);
+        $chartAccount = $category->account ?? $this->getChartFromTransaction($company, $transaction, $transactionType);
+
+        $postedAt = $transaction->datetime ?? Carbon::parse($transaction->date)->toDateTimeString();
+
+        $description = $transaction->original_description ?? $transaction->name;
 
-        $connectedBankAccount->update([
-            'bank_account_id' => $bankAccount->id,
-            'import_transactions' => true,
+        Log::info('Transaction description:', [
+            'name' => $transaction->name,
+            'description' => $description,
+            'amount' => $transaction->amount,
+            'detailedCategory' => $transaction->personal_finance_category->detailed,
+            'primaryCategory' => $transaction->personal_finance_category->primary,
         ]);
+
+        $transactionRecord = $account->transactions()->create([
+            'company_id' => $company->id,
+            'category_id' => $category->id,
+            'bank_account_id' => $connectedBankAccount->bank_account_id,
+            'type' => $transactionType,
+            'amount' => abs($transaction->amount),
+            'method' => $method,
+            'payment_channel' => $paymentChannel,
+            'posted_at' => $postedAt,
+            'description' => $description,
+            'pending' => $transaction->pending,
+            'reviewed' => false,
+        ]);
+
+        $this->createJournalEntries($company, $account, $transactionRecord, $chartAccount);
+    }
+
+    public function createJournalEntries(Company $company, Account $account, Transaction $transaction, Account $chartAccount): void
+    {
+        // For an expense (withdrawal) transaction, we need to credit the liability or asset account ($account), and debit the expense account ($chartAccount)
+        // For an income (deposit) transaction, we need to debit the liability or asset account ($account), and credit the revenue account ($chartAccount)
+        // Debiting an Asset account increases its balance. Crediting an Asset account decreases its balance.
+        // Crediting a Liability account increases its balance. Debiting a Liability account decreases its balance.
+        // Expense accounts should always be debited. Revenue accounts should always be credited.
+        $debitAccount = $transaction->type === 'expense' ? $chartAccount : $account;
+        $creditAccount = $transaction->type === 'expense' ? $account : $chartAccount;
+
+        $amount = $transaction->amount;
+
+        $debitAccount->journalEntries()->create([
+            'company_id' => $company->id,
+            'transaction_id' => $transaction->id,
+            'type' => 'debit',
+            'amount' => $amount,
+            'description' => $transaction->description,
+        ]);
+
+        $creditAccount->journalEntries()->create([
+            'company_id' => $company->id,
+            'transaction_id' => $transaction->id,
+            'type' => 'credit',
+            'amount' => $amount,
+            'description' => $transaction->description,
+        ]);
+    }
+
+    public function getCategoryFromTransaction(Company $company, $transaction, string $transactionType): Category
+    {
+        $acceptableConfidenceLevels = ['VERY_HIGH', 'HIGH'];
+
+        $userCategories = $company->categories()->get();
+        $plaidDetail = $transaction->personal_finance_category->detailed ?? null;
+        $plaidPrimary = $transaction->personal_finance_category->primary ?? null;
+
+        $category = null;
+
+        if ($plaidDetail !== null && in_array($transaction->personal_finance_category->confidence_level, $acceptableConfidenceLevels, true)) {
+            $category = $this->matchCategory($userCategories, $plaidDetail, $transactionType);
+        }
+
+        if ($plaidPrimary !== null && ($category === null || $this->isUncategorized($category))) {
+            $category = $this->matchCategory($userCategories, $plaidPrimary, $transactionType);
+        }
+
+        return $category ?? $this->getUncategorizedCategory($company, $transaction, $transactionType);
+    }
+
+    public function isUncategorized(Category $category): bool
+    {
+        return Str::contains(strtolower($category->name), 'other');
+    }
+
+    public function matchCategory($userCategories, $plaidCategory, string $transactionType): ?Category
+    {
+        $plaidWords = explode(' ', strtolower($plaidCategory));
+
+        $bestMatchCategory = null;
+        $bestMatchScore = 0; // Higher is better
+
+        foreach ($userCategories as $category) {
+            if (strtolower($category->type->value) !== strtolower($transactionType)) {
+                continue;
+            }
+
+            $categoryWords = explode(' ', strtolower($category->name));
+            $matchScore = count(array_intersect($plaidWords, $categoryWords));
+
+            if ($matchScore > $bestMatchScore) {
+                $bestMatchScore = $matchScore;
+                $bestMatchCategory = $category;
+            }
+        }
+
+        return $bestMatchCategory;
+    }
+
+    public function getUncategorizedCategory(Company $company, $transaction, string $transactionType): Category
+    {
+        $uncategorizedCategoryName = 'Other ' . ucfirst($transactionType);
+        $uncategorizedCategory = $company->categories()->where('type', $transactionType)->where('name', $uncategorizedCategoryName)->first();
+
+        if ($uncategorizedCategory === null) {
+            $uncategorizedCategory = $company->categories()->where('type', $transactionType)->where('name', 'Other')->first();
+
+            if ($uncategorizedCategory === null) {
+                $uncategorizedCategory = $company->categories()->where('name', 'Other')->first();
+            }
+        }
+
+        return $uncategorizedCategory;
+    }
+
+    public function getChartFromTransaction(Company $company, $transaction, string $transactionType): Account
+    {
+        if ($transactionType === 'income') {
+            $chart = $company->accounts()->where('type', AccountType::UncategorizedRevenue)->where('name', 'Uncategorized Income')->first();
+        } else {
+            $chart = $company->accounts()->where('type', AccountType::UncategorizedExpense)->where('name', 'Uncategorized Expense')->first();
+        }
+
+        return $chart;
     }
 
     public function processNewBankAccount(Company $company, ConnectedBankAccount $connectedBankAccount, $accessToken): BankAccount

app/Listeners/SyncTransactionsFromPlaid.php

@@ -4,7 +4,7 @@ namespace App\Listeners;
 
 use App\Enums\Accounting\AccountType;
 use App\Events\PlaidSuccess;
-use App\Models\Accounting\Chart;
+use App\Models\Accounting\Account;
 use App\Models\Company;
 use App\Models\Setting\Category;
 use App\Services\PlaidService;
@@ -141,12 +141,12 @@ class SyncTransactionsFromPlaid
         return $uncategorizedCategory;
     }
 
-    public function getChartFromTransaction(Company $company, $transaction, string $transactionType): Chart
+    public function getChartFromTransaction(Company $company, $transaction, string $transactionType): Account
     {
         if ($transactionType === 'income') {
-            $chart = $company->charts()->where('type', AccountType::OperatingRevenue)->where('name', 'Uncategorized Income')->first();
+            $chart = $company->accounts()->where('type', AccountType::OperatingRevenue)->where('name', 'Uncategorized Income')->first();
         } else {
-            $chart = $company->charts()->where('type', AccountType::OperatingExpense)->where('name', 'Uncategorized Expense')->first();
+            $chart = $company->accounts()->where('type', AccountType::OperatingExpense)->where('name', 'Uncategorized Expense')->first();
         }
 
         return $chart;

app/Models/Accounting/Account.php

@@ -3,6 +3,8 @@
 namespace App\Models\Accounting;
 
 use App\Casts\MoneyCast;
+use App\Enums\Accounting\AccountCategory;
+use App\Enums\Accounting\AccountType;
 use App\Models\Setting\Category;
 use App\Models\Setting\Currency;
 use App\Traits\Blamable;
@@ -37,6 +39,7 @@ class Account extends Model
         'starting_balance',
         'debit_balance',
         'credit_balance',
+        'net_movement',
         'ending_balance',
         'description',
         'active',
@@ -48,6 +51,8 @@ class Account extends Model
     ];
 
     protected $casts = [
+        'category' => AccountCategory::class,
+        'type' => AccountType::class,
         'starting_balance' => MoneyCast::class,
         'debit_balance' => MoneyCast::class,
         'credit_balance' => MoneyCast::class,

app/Models/Accounting/JournalEntry.php

@@ -3,6 +3,7 @@
 namespace App\Models\Accounting;
 
 use App\Casts\MoneyCast;
+use App\Models\Banking\BankAccount;
 use App\Traits\Blamable;
 use App\Traits\CompanyOwned;
 use Database\Factories\Accounting\JournalEntryFactory;
@@ -58,6 +59,11 @@ class JournalEntry extends Model
         return $query->where('type', 'credit');
     }
 
+    public function bankAccount(): BelongsTo
+    {
+        return $this->account()->where('accountable_type', BankAccount::class);
+    }
+
     public function createdBy(): BelongsTo
     {
         return $this->belongsTo(FilamentCompanies::userModel(), 'created_by');

app/Models/Accounting/Transaction.php

@@ -3,6 +3,7 @@
 namespace App\Models\Accounting;
 
 use App\Casts\MoneyCast;
+use App\Models\Banking\BankAccount;
 use App\Models\Common\Contact;
 use App\Models\Setting\Category;
 use App\Traits\Blamable;
@@ -24,6 +25,7 @@ class Transaction extends Model
     protected $fillable = [
         'company_id',
         'category_id',
+        'bank_account_id', // 'account_id' => 'bank_account_id'
         'contact_id',
         'type',
         'method',
@@ -66,6 +68,11 @@ class Transaction extends Model
         return $this->hasMany(JournalEntry::class, 'transaction_id');
     }
 
+    public function bankAccount(): BelongsTo
+    {
+        return $this->belongsTo(BankAccount::class, 'bank_account_id');
+    }
+
     public function createdBy(): BelongsTo
     {
         return $this->belongsTo(FilamentCompanies::userModel(), 'created_by');

app/Observers/JournalEntryObserver.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace App\Observers;
+
+use App\Enums\Accounting\AccountCategory;
+use App\Models\Accounting\Account;
+use App\Models\Accounting\JournalEntry;
+
+class JournalEntryObserver
+{
+    /**
+     * Handle the JournalEntry "created" event.
+     */
+    public function created(JournalEntry $journalEntry): void
+    {
+        $account = $journalEntry->account;
+
+        if ($account) {
+            $this->adjustBalance($account, $journalEntry->type, $journalEntry->amount);
+        }
+    }
+
+    private function updateEndingBalance(Account $account): void
+    {
+        $netMovementStrategy = match ($account->category) {
+            AccountCategory::Asset, AccountCategory::Expense => $account->debit_balance - $account->credit_balance,
+            AccountCategory::Liability, AccountCategory::Equity, AccountCategory::Revenue => $account->credit_balance - $account->debit_balance,
+        };
+
+        $account->net_movement = $netMovementStrategy;
+
+        if (in_array($account->category, [AccountCategory::Asset, AccountCategory::Liability, AccountCategory::Equity], true)) {
+            $account->ending_balance = $account->starting_balance + $account->net_movement;
+        }
+
+        $account->save();
+    }
+
+    /**
+     * Handle the JournalEntry "updated" event.
+     */
+    public function updated(JournalEntry $journalEntry): void
+    {
+        $accountChanged = $journalEntry->wasChanged('account_id');
+        $amountChanged = $journalEntry->wasChanged('amount');
+        $typeChanged = $journalEntry->wasChanged('type');
+
+        $originalAccountId = $journalEntry->getOriginal('account_id');
+        $originalAmount = $journalEntry->getOriginal('amount');
+        $originalType = $journalEntry->getOriginal('type');
+
+        if ($accountChanged || $amountChanged || $typeChanged) {
+            // Revert the effects of the original journal entry
+            $originalAccount = Account::find($originalAccountId);
+
+            if ($originalAccount) {
+                $this->adjustBalance($originalAccount, $originalType, -$originalAmount);
+            }
+        }
+
+        $newAccount = ($accountChanged) ? Account::find($journalEntry->account_id) : $journalEntry->account;
+
+        if ($newAccount) {
+            $this->adjustBalance($newAccount, $journalEntry->type, $journalEntry->amount);
+        }
+    }
+
+    private function adjustBalance(Account $account, $type, $amount): void
+    {
+        if ($type === 'debit') {
+            $account->debit_balance += $amount;
+        } elseif ($type === 'credit') {
+            $account->credit_balance += $amount;
+        }
+
+        $this->updateEndingBalance($account);
+    }
+
+    /**
+     * Handle the JournalEntry "deleted" event.
+     */
+    public function deleted(JournalEntry $journalEntry): void
+    {
+        $account = $journalEntry->account;
+
+        if ($account) {
+            $this->adjustBalance($account, $journalEntry->type, -$journalEntry->amount);
+        }
+    }
+
+    /**
+     * Handle the JournalEntry "restored" event.
+     */
+    public function restored(JournalEntry $journalEntry): void
+    {
+        //
+    }
+
+    /**
+     * Handle the JournalEntry "force deleted" event.
+     */
+    public function forceDeleted(JournalEntry $journalEntry): void
+    {
+        //
+    }
+}

app/Providers/EventServiceProvider.php

@@ -23,11 +23,13 @@ use App\Listeners\SyncWithCompanyDefaults;
 use App\Listeners\UpdateAccountBalances;
 use App\Listeners\UpdateCurrencyRates;
 use App\Models\Accounting\Account;
+use App\Models\Accounting\JournalEntry;
 use App\Models\Banking\BankAccount;
 use App\Models\Setting\Currency;
 use App\Observers\AccountObserver;
 use App\Observers\BankAccountObserver;
 use App\Observers\CurrencyObserver;
+use App\Observers\JournalEntryObserver;
 use Illuminate\Auth\Events\Registered;
 use Illuminate\Auth\Listeners\SendEmailVerificationNotification;
 use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
@@ -83,6 +85,7 @@ class EventServiceProvider extends ServiceProvider
         Currency::class => [CurrencyObserver::class],
         BankAccount::class => [BankAccountObserver::class],
         Account::class => [AccountObserver::class],
+        JournalEntry::class => [JournalEntryObserver::class],
     ];
 
     /**

app/Services/PlaidService.php

@@ -290,4 +290,16 @@ class PlaidService
 
         return $this->sendRequest('transactions/sync', $data);
     }
+
+    public function getTransactions(string $access_token, string $start_date, string $end_date, array $options = []): object
+    {
+        $data = [
+            'access_token' => $access_token,
+            'start_date' => $start_date,
+            'end_date' => $end_date,
+            'options' => (object) $options,
+        ];
+
+        return $this->sendRequest('transactions/get', $data);
+    }
 }

composer.lock

@@ -1461,16 +1461,16 @@
         },
         {
             "name": "doctrine/inflector",
-            "version": "2.0.9",
+            "version": "2.0.10",
             "source": {
                 "type": "git",
                 "url": "https://github.com/doctrine/inflector.git",
-                "reference": "2930cd5ef353871c821d5c43ed030d39ac8cfe65"
+                "reference": "5817d0659c5b50c9b950feb9af7b9668e2c436bc"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/doctrine/inflector/zipball/2930cd5ef353871c821d5c43ed030d39ac8cfe65",
-                "reference": "2930cd5ef353871c821d5c43ed030d39ac8cfe65",
+                "url": "https://api.github.com/repos/doctrine/inflector/zipball/5817d0659c5b50c9b950feb9af7b9668e2c436bc",
+                "reference": "5817d0659c5b50c9b950feb9af7b9668e2c436bc",
                 "shasum": ""
             },
             "require": {
@@ -1532,7 +1532,7 @@
             ],
             "support": {
                 "issues": "https://github.com/doctrine/inflector/issues",
-                "source": "https://github.com/doctrine/inflector/tree/2.0.9"
+                "source": "https://github.com/doctrine/inflector/tree/2.0.10"
             },
             "funding": [
                 {
@@ -1548,7 +1548,7 @@
                     "type": "tidelift"
                 }
             ],
-            "time": "2024-01-15T18:05:13+00:00"
+            "time": "2024-02-18T20:23:39+00:00"
         },
         {
             "name": "doctrine/lexer",

database/migrations/2023_09_03_100000_create_accounting_tables.php

@@ -49,6 +49,7 @@ return new class extends Migration
             $table->bigInteger('starting_balance')->default(0);
             $table->bigInteger('debit_balance')->default(0);
             $table->bigInteger('credit_balance')->default(0);
+            $table->bigInteger('net_movement')->default(0);
             $table->bigInteger('ending_balance')->default(0);
             $table->text('description')->nullable();
             $table->boolean('active')->default(true);

database/migrations/2024_01_01_234943_create_transactions_table.php

@@ -15,6 +15,7 @@ return new class extends Migration
             $table->id();
             $table->foreignId('company_id')->constrained()->cascadeOnDelete();
             $table->foreignId('category_id')->nullable()->constrained()->nullOnDelete();
+            $table->foreignId('bank_account_id')->nullable()->constrained()->nullOnDelete();
             $table->foreignId('contact_id')->nullable()->constrained()->nullOnDelete();
             $table->string('type'); // income, expense, other
             $table->string('method'); // deposit, withdrawal

package-lock.json

@@ -697,9 +697,9 @@
             }
         },
         "node_modules/caniuse-lite": {
-            "version": "1.0.30001587",
-            "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001587.tgz",
-            "integrity": "sha512-HMFNotUmLXn71BQxg8cijvqxnIAofforZOwGsxyXJ0qugTdspUF4sPSJ2vhgprHCB996tIDzEq1ubumPDV8ULA==",
+            "version": "1.0.30001588",
+            "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001588.tgz",
+            "integrity": "sha512-+hVY9jE44uKLkH0SrUTqxjxqNTOWHsbnQDIKjwkZ3lNTzUUVdBLBGXtj/q5Mp5u98r3droaZAewQuEDzjQdZlQ==",
             "dev": true,
             "funding": [
                 {
@@ -1551,9 +1551,9 @@
             }
         },
         "node_modules/postcss-load-config/node_modules/lilconfig": {
-            "version": "3.1.0",
-            "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.0.tgz",
-            "integrity": "sha512-p3cz0JV5vw/XeouBU3Ldnp+ZkBjE+n8ydJ4mcwBrOiXXPqNlrzGBqWs9X4MWF7f+iKUBu794Y8Hh8yawiJbCjw==",
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.1.tgz",
+            "integrity": "sha512-O18pf7nyvHTckunPWCV1XUNXU1piu01y2b7ATJ0ppkUkk8ocqVWBrYjJBCwHDjD/ZWcfyrA0P4gKhzWGi5EINQ==",
             "dev": true,
             "engines": {
                 "node": ">=14"