@mx-cartographer/experiences 4.0.13 → 4.0.14-alpha.JB1

package/src/transactions/stores/TransactionStore.ts

@@ -0,0 +1,327 @@
+import { makeAutoObservable, runInAction } from 'mobx'
+import { getUnixTime } from 'date-fns/getUnixTime'
+import { endOfToday } from 'date-fns/endOfToday'
+import { formatISO } from 'date-fns/formatISO'
+import { fromUnixTime } from 'date-fns/fromUnixTime'
+import { isBefore } from 'date-fns/isBefore'
+import { startOfMonth } from 'date-fns/startOfMonth'
+import { startOfToday } from 'date-fns/startOfToday'
+import { subDays } from 'date-fns/subDays'
+
+import { TABLE_CONST } from '../../common/constants/Table'
+
+import { BeatApi } from '../../common'
+import type { Beat, GlobalStore, Tag, Tagging, Transaction, TransactionRule } from '../../common'
+
+import { buildDetailedTransactions } from '../utils/buildDetailedTransactions'
+import { onAnalyticEvent } from '../analytics'
+import { TransactionApi } from '../api/TransactionApi'
+import { COLUMN_NAMES } from '../constants/TransactionsTable'
+import { sortAndFilterTransactions } from '../utils/sortAndFilterTransactions'
+import { UiStore } from './UiStore'
+
+export type TransactionFilter = {
+  accounts?: string[]
+  dateRange?: { start: Date; end: Date }
+  custom?: (value: Transaction) => boolean
+  searchTerm?: string
+}
+
+export class TransactionStore {
+  api = new TransactionApi('/', '')
+  beatApi = new BeatApi('/', '')
+
+  globalStore: GlobalStore
+  uiStore: UiStore
+
+  isLoading = true
+  taggings: Tagging[] = []
+  tags: Tag[] = []
+  transactionRules: TransactionRule[] = []
+  transactions: Transaction[] = []
+
+  associatedBeats: Beat[] = []
+
+  cachedStartDate: Date = subDays(startOfToday(), 90)
+
+  onAnalyticEvent = onAnalyticEvent
+  sortColumn = COLUMN_NAMES.DATE
+  sortDirection = TABLE_CONST.DESC
+
+  filter: TransactionFilter = {}
+
+  constructor(globalStore: GlobalStore) {
+    this.globalStore = globalStore
+    this.uiStore = new UiStore()
+
+    makeAutoObservable(this)
+  }
+
+  initialize = async (endpoint: string, token: string) => {
+    this.api = new TransactionApi(endpoint, token)
+    this.beatApi = new BeatApi(endpoint, token)
+
+    Promise.all([
+      this.loadAssociatedBeats(startOfMonth(new Date())),
+      this.loadTags(),
+      this.loadTaggings(),
+      this.loadTransactionRules(),
+      // By default loads 90 days of transactions
+      this.loadTransactions(),
+    ]).then(() => this.uiStore.setIsInitialized(true))
+  }
+
+  get sortedTransactions(): Transaction[] {
+    return sortAndFilterTransactions(
+      this.filter,
+      this.uiStore.expandedSplits,
+      this.sortColumn,
+      this.sortDirection,
+      this.tags,
+      this.transactions,
+    )
+  }
+
+  addTag = async (name: string) => {
+    await this.api.addTag({ name } as Tag)
+    await this.loadTags()
+  }
+
+  addTagging = async (tagGuid: string, transactionGuid: string) => {
+    await this.api.addTagging({
+      tag_guid: tagGuid,
+      transaction_guid: transactionGuid,
+    } as Tagging)
+  }
+
+  addOrUpdateTransactionRule = async (categoryGuid: string, transaction: Transaction) => {
+    const existingRule = this.transactionRules.find(
+      (rule: TransactionRule) => rule.guid === transaction.user_transaction_rule_guid,
+    ) as TransactionRule | undefined
+
+    if (existingRule) {
+      await this.api.updateTransactionRule({
+        ...existingRule,
+        category_guid: categoryGuid,
+        description: transaction.description,
+      } as TransactionRule)
+    } else {
+      await this.api.addTransactionRule({
+        category_guid: categoryGuid,
+        description: transaction.description,
+        match_description: transaction.description,
+      } as TransactionRule)
+    }
+    await this.loadTransactionRules()
+  }
+
+  addTransaction = async (transaction: Transaction) => {
+    const newTransaction = await this.api.addTransaction(transaction)
+
+    if (newTransaction) {
+      runInAction(
+        () =>
+          (this.transactions = this.augmentTransactions([newTransaction, ...this.transactions])),
+      )
+    }
+  }
+
+  augmentTransactions = (transactions: Transaction[]) => {
+    return buildDetailedTransactions(
+      transactions,
+      this.globalStore.accountStore.accounts,
+      this.globalStore.categoryStore.categories,
+      this.taggings,
+    )
+  }
+
+  loadAssociatedBeats = async (fromDate?: Date) => {
+    const fromDateISO = fromDate ? formatISO(fromDate, { representation: 'date' }) : undefined
+    const beats = await this.beatApi.getBeatsWithAssociatedTransaction(fromDateISO)
+    runInAction(() => (this.associatedBeats = beats))
+  }
+
+  loadTags = async () => {
+    const tags = await this.api.getTags()
+    runInAction(() => (this.tags = tags))
+  }
+
+  loadTaggings = async () => {
+    const taggings = await this.api.getTaggings()
+    runInAction(() => (this.taggings = taggings))
+  }
+
+  loadTransactionRules = async () => {
+    const transactionRules = await this.api.getTransactionRules()
+    runInAction(() => (this.transactionRules = transactionRules))
+  }
+
+  loadTransactions = async (
+    startDate: Date = this.cachedStartDate,
+    endDate: Date = endOfToday(),
+  ) => {
+    this.setIsLoading(true)
+    this.transactions = []
+
+    try {
+      const transactions = await this.api.getTransactionsByDateRange(
+        getUnixTime(startDate),
+        getUnixTime(endDate),
+      )
+      runInAction(() => {
+        this.transactions = this.augmentTransactions(transactions)
+      })
+    } catch (error) {
+      console.error(`Error occurred while loading transactions: ${error}`)
+    }
+    this.setIsLoading(false)
+  }
+
+  // DEPRECATED
+  loadTransactionsByDateRange = async (endDate: number, startDate: number) => {
+    console.warn('DEPRECATED: loadTransactionsByDateRange will be removed')
+    this.setFilter({
+      ...this.filter,
+      dateRange: { start: fromUnixTime(startDate), end: fromUnixTime(endDate) },
+    })
+  }
+
+  removeTag = async (tagGuid: string) => {
+    await this.api.removeTag(tagGuid)
+    await this.loadTags()
+  }
+
+  removeTagging = async (taggingGuid: string) => {
+    await this.api.removeTagging(taggingGuid)
+  }
+
+  removeTransaction = async (transactionGuid: string) => {
+    await this.api.removeTransaction(transactionGuid)
+
+    const index = this.transactions.findIndex((t: Transaction) => t.guid === transactionGuid)
+
+    if (index >= 0) {
+      const updatedTransactions = [...this.transactions]
+      updatedTransactions.splice(index, 1)
+      runInAction(() => (this.transactions = updatedTransactions))
+    }
+  }
+
+  setFilter = (filter: TransactionFilter) => {
+    this.filter = filter
+
+    // Only reload transactions if new start date is prior to the current cached start date
+    // Cached date range end date is always today
+    if (filter.dateRange && isBefore(filter.dateRange.start, this.cachedStartDate)) {
+      this.loadTransactions(filter.dateRange.start, endOfToday()).then(() => {
+        if (filter.dateRange) {
+          this.cachedStartDate = filter.dateRange.start
+        }
+      })
+    }
+  }
+
+  setIsLoading = (isLoading: boolean) => (this.isLoading = isLoading)
+
+  setSortData = (sortColumn: string, sortDirection: string) => {
+    this.sortColumn = sortColumn
+    this.sortDirection = sortDirection
+  }
+
+  splitTransaction = async (transaction: Transaction, splits: Transaction[]) => {
+    const updatedTransaction = await this.api.updateTransaction(transaction)
+    const children = [] as Transaction[]
+
+    for (let i = 0; i < splits.length; i++) {
+      const child = await this.api.addTransaction(splits[i])
+      children.push(child)
+    }
+
+    const index = this.transactions.findIndex((t: Transaction) => t.guid === transaction.guid)
+
+    if (index >= 0) {
+      runInAction(
+        () =>
+          (this.transactions = this.augmentTransactions([
+            ...this.transactions.slice(0, index),
+            updatedTransaction,
+            ...this.transactions.slice(index + 1),
+            ...children,
+          ])),
+      )
+    }
+  }
+
+  unSplitTransaction = async (guid: string) => {
+    const children = this.transactions.filter((t) => t.parent_guid === guid)
+
+    await this.api.removeTransactionSplit(guid)
+
+    // Remove children
+    const transactions = [...this.transactions]
+    children.forEach((child) => {
+      const index = transactions.findIndex((t) => t.guid === child.guid)
+
+      if (index >= 0) {
+        transactions.splice(index, 1)
+      }
+    })
+
+    // Update parent
+    const index = transactions.findIndex((t) => t.guid === guid)
+    const transaction = transactions[index]
+    transaction.has_been_split = false
+    if (index >= 0) {
+      runInAction(
+        () =>
+          (this.transactions = [
+            ...transactions.slice(0, index),
+            transaction,
+            ...transactions.slice(index + 1),
+          ]),
+      )
+    }
+  }
+
+  updateTaggings = async (tagGuids: string[], transactionGuid: string) => {
+    // Add tags that don't current exist in taggings
+    for (let i = 0; i < tagGuids.length; i++) {
+      const tagGuid = tagGuids[i]
+      if (!this.taggings.some((tagging: Tagging) => tagging.tag_guid === tagGuid)) {
+        await this.addTagging(tagGuid, transactionGuid)
+      }
+    }
+
+    // Remove tags that are in taggings but not in tagGuids
+    for (let i = 0; i < this.taggings.length; i++) {
+      const tagging = this.taggings[i]
+      if (!tagGuids.includes(tagging.tag_guid)) {
+        await this.removeTagging(tagging.guid)
+      }
+    }
+
+    await this.loadTaggings()
+  }
+
+  updateTag = async (tag: Tag) => {
+    await this.api.updateTag(tag)
+    await this.loadTags()
+  }
+
+  updateTransaction = async (transaction: Transaction) => {
+    const updatedTransaction = await this.api.updateTransaction(transaction)
+
+    const index = this.transactions.findIndex((t: Transaction) => t.guid === transaction.guid)
+
+    if (index >= 0) {
+      runInAction(
+        () =>
+          (this.transactions = this.augmentTransactions([
+            ...this.transactions.slice(0, index),
+            updatedTransaction,
+            ...this.transactions.slice(index + 1),
+          ])),
+      )
+    }
+  }
+}

package/src/transactions/stores/UiStore.ts

@@ -0,0 +1,72 @@
+import { makeAutoObservable } from 'mobx'
+import { startOfMonth } from 'date-fns/startOfMonth'
+import { endOfMonth } from 'date-fns/endOfMonth'
+
+import type { Transaction } from '../../common'
+
+import { DEFAULT_TRANSACTION } from '../constants/Transaction'
+
+export class UiStore {
+  beginDate = startOfMonth(new Date())
+  endDate = endOfMonth(new Date())
+
+  expandedSplits = [] as string[]
+  isInitialized = false
+  height = 550
+  width = 1000
+  shouldDisableDrawerScroll = false
+
+  searchValue = ''
+  selectedAccountGuids = [] as string[]
+
+  manualTransaction: Transaction = DEFAULT_TRANSACTION
+  isAmountValid = false
+
+  showInsights = false
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  setDateRange = (beginDate: Date, endDate: Date) => {
+    this.beginDate = beginDate
+    this.endDate = endDate
+  }
+
+  setIsInitialized = (isInitialized: boolean) => (this.isInitialized = isInitialized)
+
+  setIsAmountValid = (valid: boolean) => (this.isAmountValid = valid)
+
+  setSearchValue = (searchValue: string) => (this.searchValue = searchValue)
+
+  setSelectedAccountGuids = (accountGuids: string[]) => (this.selectedAccountGuids = accountGuids)
+
+  setShouldDisableDrawerScroll = (shouldDisable: boolean) =>
+    (this.shouldDisableDrawerScroll = shouldDisable)
+
+  setShowInsights = (showInsights: boolean) => {
+    this.showInsights = showInsights
+  }
+
+  setSize = (height: number, width: number) => {
+    this.height = height
+    this.width = width
+  }
+
+  toggleSplit = (guid: string) => {
+    const expandedSplits = [...this.expandedSplits]
+    const index = this.expandedSplits.findIndex((splitGuid) => splitGuid === guid)
+
+    if (index >= 0) {
+      expandedSplits.splice(index, 1)
+    } else {
+      expandedSplits.push(guid)
+    }
+
+    this.expandedSplits = expandedSplits
+  }
+
+  updateManualTransaction = (manualTransaction: Transaction) => {
+    this.manualTransaction = manualTransaction
+  }
+}

package/src/transactions/stores/__tests__/TransactionStore.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, vi } from 'vitest'
+import { GlobalStore, Transaction } from '../../../common'
+import { endOfToday } from 'date-fns/endOfToday'
+import { startOfToday } from 'date-fns/startOfToday'
+import { subDays } from 'date-fns/subDays'
+
+vi.mock('../../api/TransactionApi')
+vi.mock('../../../common/api/AccountApi')
+vi.mock('../../../common/api/CategoryApi')
+vi.mock('../../../common/api/ScheduledPaymentsApi')
+
+const globalStore = new GlobalStore()
+
+describe('Testing TransactionStore', () => {
+  beforeEach(async () => {
+    await globalStore.initialize('/', '')
+  })
+
+  it('should initialize all transaction related data', async () => {
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001', 'ACT-002'],
+      dateRange: { start: subDays(startOfToday(), 30), end: endOfToday() },
+    })
+
+    // Should be 2 since we initially pull the last 90 days of transactions
+    expect(globalStore.transactionStore.transactions.length).toBe(2)
+
+    // Should be 1 since date range is set to 30 days
+    expect(globalStore.transactionStore.sortedTransactions.length).toBe(1)
+  })
+
+  it('should test the ability to filter data by account and date', async () => {
+    await globalStore.transactionStore.initialize('/', '')
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001', 'ACT-002'],
+      dateRange: { start: subDays(startOfToday(), 30), end: endOfToday() },
+    })
+
+    // Should be 2 since we initially pull the last 90 days of transactions
+    expect(globalStore.transactionStore.transactions.length).toBe(2)
+
+    // Should be 1 since default date range is 30 days
+    expect(globalStore.transactionStore.sortedTransactions.length).toBe(1)
+
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001', 'ACT-002'],
+      dateRange: { start: subDays(startOfToday(), 90), end: endOfToday() },
+    })
+    // Should be 2 since the new date range is 90 days
+    expect(globalStore.transactionStore.sortedTransactions.length).toBe(2)
+
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001'],
+      dateRange: { start: subDays(startOfToday(), 90), end: endOfToday() },
+    })
+    // Should be 1 since when only include one account
+    expect(globalStore.transactionStore.sortedTransactions.length).toBe(1)
+  })
+
+  it('should test the ability to apply a custom filter', async () => {
+    await globalStore.transactionStore.initialize('/', '')
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001', 'ACT-002'],
+      dateRange: { start: subDays(startOfToday(), 90), end: endOfToday() },
+    })
+
+    expect(globalStore.transactionStore.transactions.length).toBe(2)
+
+    const categoryGuid = 'CAT-bf5c9cca-c96b-b50d-440d-38d9adfda5b0' // Education
+
+    globalStore.transactionStore.setFilter({
+      accounts: ['ACT-001', 'ACT-002'],
+      dateRange: { start: subDays(startOfToday(), 90), end: endOfToday() },
+      custom: (t: Transaction) => t.category_guid === categoryGuid,
+    })
+
+    // Should be 1 since when only one transactions is categorized as Education
+    expect(globalStore.transactionStore.sortedTransactions.length).toBe(1)
+  })
+})

package/src/transactions/utils/Filters.ts

@@ -0,0 +1,35 @@
+import { CategoryGuids, type Transaction, TransactionType } from '../../common'
+
+// Returns true if the transaction is not income
+export const expenseFilter = (t: Transaction) =>
+  t.top_level_category_guid !== CategoryGuids.INCOME && t.transaction_type === TransactionType.DEBIT
+
+// Returns true if the transaction is an expense and it matches the search string
+export const expenseFilterSearch = (t: Transaction, searchValue: string) => {
+  if (expenseFilter(t)) {
+    return (
+      t.payee?.toLowerCase().includes(searchValue.toLowerCase()) ||
+      t.description.toLowerCase().includes(searchValue.toLowerCase()) ||
+      t.feed_description.toLowerCase().includes(searchValue.toLowerCase())
+    )
+  }
+  return false
+}
+
+// Returns true if the transaction is income
+export const incomeFilter = (t: Transaction) =>
+  t.top_level_category_guid === CategoryGuids.INCOME ||
+  (t.top_level_category_guid === CategoryGuids.TRANSFER &&
+    t.transaction_type === TransactionType.CREDIT)
+
+// Returns true if the transaction is income and it matches the search string
+export const incomeFilterSearch = (t: Transaction, searchValue: string) => {
+  if (incomeFilter(t)) {
+    return (
+      t.payee?.toLowerCase().includes(searchValue.toLowerCase()) ||
+      t.description?.toLowerCase().includes(searchValue.toLowerCase()) ||
+      t.feed_description?.toLowerCase().includes(searchValue.toLowerCase())
+    )
+  }
+  return false
+}

package/src/transactions/utils/Transactions.ts

@@ -0,0 +1,22 @@
+import { fromUnixTime } from 'date-fns/fromUnixTime'
+import { isSameDay } from 'date-fns/isSameDay'
+
+import { Transaction } from '../../common'
+
+export const sortByDate = (a: Transaction, b: Transaction) => {
+  return b.date - a.date
+}
+
+export const shouldShowDate = (index: number, transactions: Transaction[]) => {
+  const currentDate = fromUnixTime(transactions[index].date)
+  const previousDate = fromUnixTime(transactions[index - 1]?.date)
+
+  return !isSameDay(currentDate, previousDate)
+}
+
+export const hasInsetBorder = (index: number, transactions: Transaction[]) => {
+  const currentDate = fromUnixTime(transactions[index].date)
+  const nextDate = fromUnixTime(transactions[index + 1]?.date)
+
+  return isSameDay(currentDate, nextDate)
+}

package/src/transactions/utils/buildDetailedTransactions.ts

@@ -0,0 +1,66 @@
+import { CategoryGuids, TransactionStatus } from '../../common'
+
+import type { Account, Category, Tagging, Transaction } from '../../common'
+
+interface AccountsMap {
+  [key: string]: Account
+}
+
+interface CategoriesMap {
+  [key: string]: Category
+}
+
+interface TaggingsMap {
+  [key: string]: string[]
+}
+
+export const buildDetailedTransactions = (
+  transactions: Transaction[],
+  accounts: Account[],
+  categories: Category[],
+  taggings: Tagging[] = [],
+) => {
+  const accountsMap = accounts.reduce((acc: AccountsMap, account: Account) => {
+    return { ...acc, [account.guid]: account }
+  }, {})
+
+  const categoriesMap = categories.reduce((acc: CategoriesMap, category: Category) => {
+    return { ...acc, [category.guid]: category }
+  }, {})
+
+  const taggingsMap = taggings.reduce((acc: TaggingsMap, tagging: Tagging) => {
+    const { transaction_guid, tag_guid } = tagging
+
+    if (!acc[transaction_guid]) {
+      return {
+        ...acc,
+        [transaction_guid]: [tag_guid],
+      }
+    }
+    const tags = [...acc[transaction_guid], tag_guid] as string[]
+
+    return {
+      ...acc,
+      [transaction_guid]: tags,
+    }
+  }, {})
+
+  return transactions.map((transaction: Transaction) => {
+    const account = accountsMap[transaction.account_guid]
+    const category = transaction.category_guid ? categoriesMap[transaction.category_guid] : null
+    const tags = taggingsMap[transaction.guid] ?? []
+
+    return {
+      ...transaction,
+      account: account?.user_name || 'Unknown',
+      accountIsClosed: account?.is_closed,
+      accountIsHidden: account?.is_hidden,
+      category: category?.name || 'Uncategorized',
+      isIncome: transaction.top_level_category_guid === CategoryGuids.INCOME,
+      isPending: transaction.feed_status === TransactionStatus.PENDING,
+      number: account?.account_number || '',
+      payee: transaction.description,
+      tags,
+    }
+  })
+}

package/src/transactions/utils/exportTransactionsToCSV.ts

@@ -0,0 +1,85 @@
+import { format } from 'date-fns/format'
+import { fromUnixTime } from 'date-fns/fromUnixTime'
+
+import { CategoryGuidToName } from '../../common'
+import type { Tag, Transaction } from '../../common'
+
+// TODO: Change the way formatting data is exported in order to handle localization
+type FormattedTransaction = {
+  Date: string
+  Description: string
+  'Original Description': string
+  Amount: string
+  'Parent Category': string
+  Category: string
+  Account: string
+  Tags: string
+  Memo: string
+}
+
+export const exportTransactionsToCSV = (transactions: Transaction[], tags: Tag[]) => {
+  const csvContent = structureCSVData(formatTransactions(transactions, tags))
+  const uriEncodedData = encodeURIComponent(csvContent)
+  const link = document.createElement('a')
+
+  link.href = `data:attachment/csv;charset=utf-8,${uriEncodedData}`
+  link.download = 'transactions.csv'
+
+  document.body.appendChild(link)
+  link.click()
+  document.body.removeChild(link)
+}
+
+/**
+ * Formats a list of transactions into a list that will be used when
+ * downloaded to a CSV file.
+ */
+const formatTransactions = (transactions: Transaction[], tags: Tag[]) => {
+  return transactions.map((transaction) => ({
+    // TODO: Data format should be localized
+    Date: format(fromUnixTime(transaction.date), 'MM/dd/yy'),
+    Description: getDescription(transaction),
+    'Original Description': transaction.feed_description,
+    Amount: `${transaction.amount}`,
+    'Parent Category': CategoryGuidToName[transaction.top_level_category_guid || ''],
+    Category: transaction.category,
+    Account: transaction.account,
+    Tags: getTags(transaction, tags),
+    Memo: transaction.memo,
+  })) as FormattedTransaction[]
+}
+
+/**
+ * Structures the CSV file data using the formatted transactions
+ */
+const structureCSVData = (formattedTransactions: FormattedTransaction[]) => {
+  const csvHeader = Object.keys(formattedTransactions[0]).join(',').concat('\r\n')
+  const csvRows = formattedTransactions
+    .map((transaction) => Object.values(transaction).join(','))
+    .join('\r\n')
+
+  return csvHeader + csvRows
+}
+
+/**
+ * Get the description for a transaction that will be used within the CSV copy.
+ * We want to highlight that split transactions are a split as well as
+ * hidden transactions are hidden.
+ */
+const getDescription = (transaction: Transaction) => {
+  let description = transaction.parent_guid ? 'Split: ' : ''
+  description += transaction.is_hidden ? '(Excluded) ' : ''
+  description += transaction.description
+
+  return description
+}
+
+const getTags = (transaction: Transaction, tags: Tag[]) => {
+  return transaction.tags
+    .map((tagGuid) => {
+      const tag = tags.filter((t) => t.guid === tagGuid)[0]
+
+      return tag?.name ?? ''
+    })
+    .join(' ')
+}