Investments tracking

package.json

@@ -70,6 +70,8 @@
     "jsonwebtoken": "9.0.2",
     "locale": "0.1.0",
     "morgan": "1.10.0",
+    "@polygon.io/client-js": "^7.3.2",
+    "lodash": "^4.17.21",
     "p-queue": "6.6.2",
     "passport": "0.6.0",
     "passport-jwt": "4.0.1",
@@ -80,7 +82,7 @@
     "sequelize-cli": "6.6.2",
     "sequelize-typescript": "2.1.6",
     "ts-node": "10.9.2",
-    "typescript": "5.4.5",
+    "typescript": "5.6.2",
     "uuid": "9.0.1",
     "winston": "3.13.0",
     "zod": "^3.23.8"
@@ -109,7 +111,8 @@
     "nodemon": "3.1.0",
     "prettier": "3.2.5",
     "supertest": "6.3.4",
-    "ts-jest": "29.1.2",
-    "tslint": "6.1.3"
+    "ts-jest": "29.2.5",
+    "tslint": "6.1.3",
+    "@types/sequelize": "^4.28.20"
   }
 }

shared-types/api/api.ts

@@ -12,6 +12,7 @@ export enum API_ERROR_CODES {
   conflict = 'CONFLICT',
   forbidden = 'FORBIDDEN',
   BadRequest = 'BAD_REQUEST',
+  locked = 'LOCKED',
 
   // auth
   unauthorized = 'UNAUTHENTICATED',

shared-types/models/index.ts

@@ -132,3 +132,247 @@ export interface UserExchangeRatesModel extends ExchangeRatesModel {
   userId: number;
   custom?: boolean;
 }
+
+export enum SECURITY_PROVIDER {
+  polygon = 'polygon',
+  other = 'other',
+}
+
+export enum ASSET_CLASS {
+  cash = 'cash',
+  crypto = 'crypto',
+  fixed_income = 'fixed_income',
+  options = 'options',
+  stocks = 'stocks',
+  other = 'other',
+}
+
+export interface SecurityModel {
+  id: number;
+  /**
+   * The name of the security, typically the official name of the stock, bond,
+   * or other financial instrument.
+   */
+  name?: string;
+
+  /**
+   * The trading symbol or ticker associated with the security, used to uniquely
+   * identify it on stock exchanges.
+   */
+  symbol?: string;
+
+  /**
+   * The CUSIP number (Committee on Uniform Securities Identification Procedures) is a unique identifier
+   * assigned to U.S. and Canadian securities for the purposes of facilitating clearing and settlement of trades.
+   */
+  cusip?: string;
+
+  /**
+   * The ISIN number (International Securities Identification Number) is a unique code assigned to securities
+   * internationally for uniform identification, which helps in reducing the risk of ambiguities in international trading.
+   */
+  isin?: string;
+
+  /**
+   * (Applicable for derivative securities) The number of shares or units
+   * represented by a single contract, commonly used in options and futures trading.
+   */
+  sharesPerContract?: string;
+
+  /**
+   * The ISO currency code representing the currency in which the transactions
+   * will be conducted. For cryptocurrencies, this code refers to
+   * the specific currency linked to it (e.g., USD for BTC-USD, EUR for BTC-EUR).
+   */
+  currencyCode: string;
+
+  /**
+   * Crypto currency code for crypto securities. Since ticker represents not
+   * just a crypto token, but an actual pair, we need to store symbol separately
+   * (e.g., BTC for BTC-USD, BTC for BTC-EUR).
+   */
+  cryptoCurrencyCode?: string;
+
+  /**
+   * The timestamp indicating the last time the pricing information for this
+   * security was updated.
+   */
+  pricingLastSyncedAt?: Date;
+
+  /**
+   * A flag indicating whether the security is considered as cash within a brokerage account.
+   * This is often used for cash management in investment portfolios.
+   */
+  isBrokerageCash: boolean;
+
+  /**
+   * The acronym or shorthand for the exchange where this security is traded,
+   * which provides an easy reference to identify the trading platform.
+   *
+   * Example:
+   * NYSE –	New York Stock Exchange
+   */
+  exchangeAcronym?: string;
+
+  /**
+   * The Market Identifier Code (MIC) as per ISO standard, representing the exchange where the security is traded.
+   * MIC is a unique identification code used to identify securities trading exchanges and market platforms globally.
+   * Read more: https://www.investopedia.com/terms/m/mic.asp
+   */
+  exchangeMic?: string;
+
+  /**
+   * The full name of the exchange where the security is listed and traded.
+   * This helps in clearly identifying the specific market platform.
+   */
+  exchangeName?: string;
+
+  /**
+   * The name of the data provider or the source from which the security's information is obtained.
+   * Enumerated values represent various recognized data providers.
+   *
+   * Useful for next cases:
+   * 1. If more providers will be added and table will be expanded, by this field
+   * we can identify provider-specific fields and features.
+   * 2. Easy to refresh data when multiple providers exists.
+   * 3. Service price, licensing, auditing, data source verification – help for
+   * any legal cases
+   */
+  providerName: SECURITY_PROVIDER;
+
+  /**
+   * The category of assets to which this security belongs.
+   * Enumerated values represent different classes of assets such as stocks, bonds, etc.
+   */
+  assetClass: ASSET_CLASS;
+  createdAt: Date;
+  updatedAt: Date;
+
+  holdings?: HoldingModel[];
+  investmentTransactions?: InvestmentTransactionModel[];
+  pricing?: SecurityPricingModel[];
+}
+
+export interface HoldingModel {
+  accountId: number;
+  securityId: number;
+  value: string;
+  refValue: string;
+  quantity: string;
+  costBasis: string;
+  refCostBasis: string;
+  currencyCode: string;
+  excluded: boolean;
+  account?: AccountModel;
+  security?: SecurityModel;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export enum INVESTMENT_TRANSACTION_CATEGORY {
+  buy = 'buy',
+  sell = 'sell',
+  dividend = 'dividend',
+  transfer = 'transfer',
+  tax = 'tax',
+  fee = 'fee',
+  cancel = 'cancel',
+  other = 'other',
+}
+
+export interface InvestmentTransactionModel {
+  id: number;
+  /**
+   * The identifier of the account associated with this transaction.
+   * It links the transaction to a specific investment account.
+   */
+  accountId: number;
+  securityId: number;
+  transactionType: TRANSACTION_TYPES;
+  date: string;
+  /**
+   * A descriptive name or title for the investment transaction, providing a
+   * quick overview of the transaction's nature. Same as `note` in `Transactions`
+   */
+  name: string | null;
+  /**
+   * The monetary value involved in the transaction. Depending on the context,
+   * this could represent the cost, sale proceeds, or other financial values
+   * associated with the transaction. Basically quantity * price
+   */
+  amount: string;
+  refAmount: string;
+
+  fees: string;
+  refFees: string;
+
+  /**
+   * * The quantity of the security involved in the transaction. This is crucial
+   * for tracking the changes in holdings as a result of the transaction.
+   */
+  quantity: string;
+
+  /**
+   * The price per unit of the security at the time of the transaction.
+   * This is used to calculate the total transaction amount and update the cost
+   * basis of the holding.
+   */
+  price: string;
+  refPrice: string;
+
+  /**
+   * The ISO currency code or standard cryptocurrency code representing the currency
+   * in which the transaction was conducted. For cryptocurrencies, this code refers to
+   * the specific cryptocurrency involved (e.g., BTC for Bitcoin, ETH for Ethereum).
+   */
+  currencyCode: string;
+  /**
+   * A category that classifies the nature of the investment transaction.
+   * This could include types like 'buy', 'sell', 'dividend', 'interest', etc.,
+   * providing a clear context for the transaction's purpose and impact on the investment portfolio.
+   */
+  category: INVESTMENT_TRANSACTION_CATEGORY;
+  /**
+   * "transferNature" and "transferId" are used to move funds between different
+   * accounts and don't affect income/expense stats.
+   */
+  transferNature: TRANSACTION_TRANSFER_NATURE;
+  // (hash, used to connect two transactions)
+  transferId: string;
+  updatedAt: Date;
+  createdAt: Date;
+
+  security?: SecurityModel;
+  account?: AccountModel;
+}
+
+export interface SecurityPricingModel {
+  securityId: number;
+  /**
+   * The date for which this pricing information is applicable. This field is crucial for tracking
+   * the historical prices of securities and allows for analysis of price trends over time.
+   * dd-mm-yyyy
+   */
+  date: Date;
+  /**
+   * The closing price of the security on the specified date. Closing prices are typically used in
+   * financial analysis and reporting as they represent the final price at which the security was traded
+   * during the trading session.
+   */
+  priceClose: string;
+  /**
+   * (Optional) The timestamp indicating the specific time the priceClose was recorded. This is particularly
+   * useful when multiple price updates occur within a single day or for real-time price tracking.
+   */
+  priceAsOf: Date;
+  /**
+   * (Optional) A field indicating the source of the pricing information. This could be the name of the
+   * data provider or the market/exchange from which the price was obtained. This field helps in
+   * tracking the reliability and origin of the data.
+   */
+  source: string;
+
+  updatedAt: Date;
+  createdAt: Date;
+  security?: SecurityModel;
+}

shared-types/routes/transactions.ts

@@ -3,11 +3,6 @@ import { QueryPayload } from './index';
 
 export interface GetTransactionsQuery extends QueryPayload {
   sort?: SORT_DIRECTIONS;
-  includeUser?: boolean;
-  includeAccount?: boolean;
-  includeCategory?: boolean;
-  includeAll?: boolean;
-  nestedInclude?: boolean;
   limit?: number;
   from?: number;
   type?: TRANSACTION_TYPES;

src/app.ts

@@ -23,6 +23,7 @@ import modelsCurrenciesRoutes from './routes/currencies.route';
 import monobankRoutes from './routes/banks/monobank.route';
 import binanceRoutes from './routes/crypto/binance.route';
 import statsRoutes from './routes/stats.route';
+import investmentsRoutes from './routes/investments.route';
 
 import { supportedLocales } from './translations';
 
@@ -78,6 +79,7 @@ app.use(`${apiPrefix}/models/currencies`, modelsCurrenciesRoutes);
 app.use(`${apiPrefix}/banks/monobank`, monobankRoutes);
 app.use(`${apiPrefix}/crypto/binance`, binanceRoutes);
 app.use(`${apiPrefix}/stats`, statsRoutes);
+app.use(`${apiPrefix}/investing`, investmentsRoutes);
 
 // Cause some tests can be parallelized, the port might be in use, so we need to allow dynamic port
 export const serverInstance = app.listen(

src/common/helpers.ts

@@ -7,8 +7,13 @@ export const getQueryBooleanValue = (value: string): boolean => {
 // To wait until `fn` returns true
 export const until = async <T>(
   fn: () => Promise<T> | T,
-  timeout: number = 30_000,
-  interval: number = 500,
+  {
+    timeout = 30_000,
+    interval = 500,
+  }: {
+    timeout?: number;
+    interval?: number;
+  } = {},
 ): Promise<void> => {
   const startTime = Date.now();