@actual-app/core 26.3.0

package/src/types/api-handlers.ts

@@ -0,0 +1,287 @@
+// @ts-strict-ignore
+import type { ImportTransactionsResult } from '../server/accounts/app';
+import type {
+  APIAccountEntity,
+  APICategoryEntity,
+  APICategoryGroupEntity,
+  APIFileEntity,
+  APIPayeeEntity,
+  APIScheduleEntity,
+  APITagEntity,
+} from '../server/api-models';
+import type { BudgetFileHandlers } from '../server/budgetfiles/app';
+import type { batchUpdateTransactions } from '../server/transactions';
+import type { QueryState } from '../shared/query';
+
+import type {
+  ImportTransactionEntity,
+  NearbyPayeeEntity,
+  NewRuleEntity,
+  PayeeLocationEntity,
+  RuleEntity,
+  ScheduleEntity,
+  TransactionEntity,
+} from './models';
+
+export type ImportTransactionsOpts = {
+  defaultCleared?: boolean;
+  dryRun?: boolean;
+};
+
+export type ApiHandlers = {
+  'api/batch-budget-start': () => Promise<void>;
+
+  'api/batch-budget-end': () => Promise<void>;
+
+  'api/load-budget': (
+    ...args: Parameters<BudgetFileHandlers['load-budget']>
+  ) => Promise<void>;
+
+  'api/download-budget': (arg: {
+    syncId: string;
+    password?: string;
+  }) => Promise<void>;
+
+  'api/get-budgets': () => Promise<APIFileEntity[]>;
+
+  'api/start-import': (arg: { budgetName: string }) => Promise<void>;
+
+  'api/finish-import': () => Promise<void>;
+
+  'api/abort-import': () => Promise<void>;
+
+  'api/query': (arg: { query: QueryState }) => Promise<unknown>;
+
+  'api/budget-months': () => Promise<string[]>;
+
+  'api/budget-month': (arg: { month: string }) => Promise<{
+    month: string;
+    incomeAvailable: number;
+    lastMonthOverspent: number;
+    forNextMonth: number;
+    totalBudgeted: number;
+    toBudget: number;
+
+    fromLastMonth: number;
+    totalIncome: number;
+    totalSpent: number;
+    totalBalance: number;
+    categoryGroups: Record<string, unknown>[];
+  }>;
+
+  'api/budget-set-amount': (arg: {
+    month: string;
+    categoryId: string;
+    amount: number;
+  }) => Promise<void>;
+
+  'api/budget-set-carryover': (arg: {
+    month: string;
+    categoryId: string;
+    flag: boolean;
+  }) => Promise<void>;
+
+  'api/budget-hold-for-next-month': (arg: {
+    month: string;
+    amount: number;
+  }) => Promise<boolean>;
+
+  'api/budget-reset-hold': (arg: { month: string }) => Promise<void>;
+
+  'api/transactions-export': (arg: {
+    transactions;
+    categoryGroups;
+    payees;
+    accounts;
+  }) => Promise<unknown>;
+
+  'api/transactions-import': (arg: {
+    accountId: APIAccountEntity['id'];
+    transactions: ImportTransactionEntity[];
+    isPreview?: boolean;
+    opts?: ImportTransactionsOpts;
+  }) => Promise<ImportTransactionsResult>;
+
+  'api/transactions-add': (arg: {
+    accountId: APIAccountEntity['id'];
+    transactions: Omit<ImportTransactionEntity, 'account'>[];
+    runTransfers?: boolean;
+    learnCategories?: boolean;
+  }) => Promise<'ok'>;
+
+  'api/transactions-get': (arg: {
+    accountId?: APIAccountEntity['id'];
+    startDate?: string;
+    endDate?: string;
+  }) => Promise<TransactionEntity[]>;
+
+  'api/transaction-update': (arg: {
+    id: TransactionEntity['id'];
+    fields;
+    // TODO: fix me
+    // fields: Partial<TransactionEntity>;
+  }) => Promise<Awaited<ReturnType<typeof batchUpdateTransactions>>['updated']>;
+
+  'api/transaction-delete': (arg: {
+    id: TransactionEntity['id'];
+  }) => Promise<Awaited<ReturnType<typeof batchUpdateTransactions>>['deleted']>;
+
+  'api/sync': () => Promise<void>;
+
+  'api/bank-sync': (arg?: {
+    accountId: APIAccountEntity['id'];
+  }) => Promise<void>;
+
+  'api/accounts-get': () => Promise<APIAccountEntity[]>;
+
+  'api/account-create': (arg: {
+    account: Omit<APIAccountEntity, 'id'>;
+    initialBalance?: number;
+  }) => Promise<string>;
+
+  'api/account-update': (arg: {
+    id: APIAccountEntity['id'];
+    fields;
+    // TODO: fix me
+    // fields: Partial<APIAccountEntity>;
+  }) => Promise<void>;
+
+  'api/account-close': (arg: {
+    id: APIAccountEntity['id'];
+    transferAccountId?: APIAccountEntity['id'];
+    transferCategoryId?: APICategoryEntity['id'];
+  }) => Promise<void>;
+
+  'api/account-reopen': (arg: { id: APIAccountEntity['id'] }) => Promise<void>;
+
+  'api/account-delete': (arg: { id: APIAccountEntity['id'] }) => Promise<void>;
+
+  'api/account-balance': (arg: {
+    id: APIAccountEntity['id'];
+    cutoff?: Date;
+  }) => Promise<number>;
+
+  'api/categories-get': (arg: {
+    grouped?: boolean;
+  }) => Promise<Array<APICategoryGroupEntity | APICategoryEntity>>;
+
+  'api/category-groups-get': () => Promise<APICategoryGroupEntity[]>;
+
+  'api/category-group-create': (arg: {
+    group: Omit<APICategoryGroupEntity, 'id'>;
+  }) => Promise<APICategoryGroupEntity['id']>;
+
+  'api/category-group-update': (arg: {
+    id: APICategoryGroupEntity['id'];
+    fields;
+    // TODO: fix me
+    // fields: Partial<APICategoryGroupEntity>;
+  }) => Promise<void>;
+
+  'api/category-group-delete': (arg: {
+    id: APICategoryGroupEntity['id'];
+    transferCategoryId?: APICategoryEntity['id'];
+  }) => Promise<void>;
+
+  'api/category-create': (arg: {
+    category: Omit<APICategoryEntity, 'id'>;
+  }) => Promise<APICategoryEntity['id']>;
+
+  'api/category-update': (arg: {
+    id: APICategoryEntity['id'];
+    fields;
+    // TODO: fix me
+    // fields: Partial<APICategoryEntity>;
+  }) => Promise<void>;
+
+  'api/category-delete': (arg: {
+    id: APICategoryEntity['id'];
+    transferCategoryId?: APICategoryEntity['id'];
+  }) => Promise<void>;
+
+  'api/payees-get': () => Promise<APIPayeeEntity[]>;
+
+  'api/common-payees-get': () => Promise<APIPayeeEntity[]>;
+
+  'api/payee-create': (arg: {
+    payee: Omit<APIPayeeEntity, 'id'>;
+  }) => Promise<APIPayeeEntity['id']>;
+
+  'api/payee-update': (arg: {
+    id: APIPayeeEntity['id'];
+    fields;
+    // TODO: fix me
+    // fields: Partial<APIPayeeEntity>;
+  }) => Promise<void>;
+
+  'api/payee-delete': (arg: { id: APIPayeeEntity['id'] }) => Promise<void>;
+
+  'api/payees-merge': (arg: {
+    targetId: APIPayeeEntity['id'];
+    mergeIds: string[];
+  }) => Promise<void>;
+
+  'api/tags-get': () => Promise<APITagEntity[]>;
+
+  'api/tag-create': (arg: {
+    tag: Omit<APITagEntity, 'id'>;
+  }) => Promise<APITagEntity['id']>;
+
+  'api/tag-update': (arg: {
+    id: APITagEntity['id'];
+    fields: Partial<Omit<APITagEntity, 'id'>>;
+  }) => Promise<void>;
+
+  'api/tag-delete': (arg: { id: APITagEntity['id'] }) => Promise<void>;
+
+  'api/payee-location-create': (arg: {
+    payeeId: string;
+    latitude: number;
+    longitude: number;
+  }) => Promise<string>;
+
+  'api/payee-locations-get': (arg: {
+    payeeId: string;
+  }) => Promise<PayeeLocationEntity[]>;
+
+  'api/payee-location-delete': (arg: { id: string }) => Promise<void>;
+
+  'api/payees-get-nearby': (arg: {
+    latitude: number;
+    longitude: number;
+    maxDistance?: number;
+  }) => Promise<NearbyPayeeEntity[]>;
+
+  'api/rules-get': () => Promise<RuleEntity[]>;
+
+  'api/payee-rules-get': (arg: {
+    id: APIPayeeEntity['id'];
+  }) => Promise<RuleEntity[]>;
+
+  'api/rule-create': (arg: { rule: NewRuleEntity }) => Promise<RuleEntity>;
+
+  'api/rule-update': (arg: { rule: RuleEntity }) => Promise<RuleEntity>;
+
+  'api/rule-delete': (id: RuleEntity['id']) => Promise<boolean>;
+
+  'api/schedule-create': (
+    schedule: Omit<APIScheduleEntity, 'id'>,
+  ) => Promise<ScheduleEntity['id']>;
+
+  'api/schedule-update': (arg: {
+    id: ScheduleEntity['id'];
+    fields: Partial<APIScheduleEntity>;
+    resetNextDate?: boolean;
+  }) => Promise<ScheduleEntity['id']>;
+
+  'api/schedule-delete': (id: string) => Promise<void>;
+
+  'api/schedules-get': () => Promise<APIScheduleEntity[]>;
+  'api/get-id-by-name': (arg: {
+    type: string;
+    name: string;
+  }) => Promise<string>;
+  'api/get-server-version': () => Promise<
+    { error: 'no-server' } | { error: 'network-failure' } | { version: string }
+  >;
+};

package/src/types/budget.ts

@@ -0,0 +1,8 @@
+export type Budget = {
+  id: string;
+  cloudFileId?: string;
+  encryptKeyId?: string;
+  groupId?: string;
+  name: string;
+  owner?: string;
+};

package/src/types/file.ts

@@ -0,0 +1,47 @@
+import type { UsersWithAccess } from '../server/cloud-storage';
+
+import type { Budget } from './budget';
+
+export type FileState =
+  | 'local'
+  | 'remote'
+  | 'synced'
+  | 'detached'
+  | 'broken'
+  | 'unknown';
+
+export type LocalFile = Omit<Budget, 'cloudFileId' | 'groupId'> & {
+  state: 'local';
+  hasKey: boolean;
+};
+
+export type SyncableLocalFile = Budget & {
+  cloudFileId: string;
+  groupId: string;
+  state: 'broken' | 'unknown';
+  hasKey: boolean;
+  owner: string;
+};
+
+export type SyncedLocalFile = Budget & {
+  cloudFileId: string;
+  groupId: string;
+  encryptKeyId?: string;
+  hasKey: boolean;
+  state: 'synced' | 'detached';
+  owner: string;
+  usersWithAccess: UsersWithAccess[];
+};
+
+export type RemoteFile = {
+  cloudFileId: string;
+  groupId: string;
+  name: string;
+  encryptKeyId?: string;
+  hasKey: boolean;
+  state: 'remote';
+  owner: string;
+  usersWithAccess: UsersWithAccess[];
+};
+
+export type File = LocalFile | SyncableLocalFile | SyncedLocalFile | RemoteFile;

package/src/types/handlers.ts

@@ -0,0 +1,46 @@
+import type { AccountHandlers } from '../server/accounts/app';
+import type { AdminHandlers } from '../server/admin/app';
+import type { AuthHandlers } from '../server/auth/app';
+import type { BudgetHandlers } from '../server/budget/app';
+import type { BudgetFileHandlers } from '../server/budgetfiles/app';
+import type { DashboardHandlers } from '../server/dashboard/app';
+import type { EncryptionHandlers } from '../server/encryption/app';
+import type { FiltersHandlers } from '../server/filters/app';
+import type { NotesHandlers } from '../server/notes/app';
+import type { PayeesHandlers } from '../server/payees/app';
+import type { PreferencesHandlers } from '../server/preferences/app';
+import type { ReportsHandlers } from '../server/reports/app';
+import type { RulesHandlers } from '../server/rules/app';
+import type { SchedulesHandlers } from '../server/schedules/app';
+import type { SpreadsheetHandlers } from '../server/spreadsheet/app';
+import type { SyncHandlers } from '../server/sync/app';
+import type { TagsHandlers } from '../server/tags/app';
+import type { ToolsHandlers } from '../server/tools/app';
+import type { TransactionHandlers } from '../server/transactions/app';
+
+import type { ApiHandlers } from './api-handlers';
+import type { ServerHandlers } from './server-handlers';
+
+export type Handlers = {} & ServerHandlers &
+  ApiHandlers &
+  BudgetHandlers &
+  DashboardHandlers &
+  FiltersHandlers &
+  NotesHandlers &
+  PreferencesHandlers &
+  ReportsHandlers &
+  RulesHandlers &
+  SchedulesHandlers &
+  TransactionHandlers &
+  AdminHandlers &
+  ToolsHandlers &
+  AccountHandlers &
+  PayeesHandlers &
+  SpreadsheetHandlers &
+  SyncHandlers &
+  BudgetFileHandlers &
+  EncryptionHandlers &
+  TagsHandlers &
+  AuthHandlers;
+
+export type HandlerFunctions = Handlers[keyof Handlers];

package/src/types/models/account.ts

@@ -0,0 +1,24 @@
+export type AccountEntity = {
+  id: string;
+  name: string;
+  offbudget: 0 | 1;
+  closed: 0 | 1;
+  sort_order: number;
+  last_reconciled: string | null;
+  tombstone: 0 | 1;
+
+  // Sync fields
+  account_id: string | null;
+  bank: string | null;
+  bankName: string | null;
+  bankId: string | null;
+  mask: string | null; // end of bank account number
+  official_name: string | null;
+  balance_current: number | null;
+  balance_available: number | null;
+  balance_limit: number | null;
+  account_sync_source: AccountSyncSource | null;
+  last_sync: string | null;
+};
+
+export type AccountSyncSource = 'simpleFin' | 'goCardless' | 'pluggyai';

package/src/types/models/bank-sync.ts

@@ -0,0 +1,23 @@
+import type {
+  GoCardlessAmount,
+  GoCardlessBalance,
+  GoCardlessTransaction,
+} from './gocardless';
+
+export type BankSyncBalance = GoCardlessBalance;
+export type BankSyncAmount = GoCardlessAmount;
+export type BankSyncTransaction = GoCardlessTransaction;
+
+export type BankSyncResponse = {
+  transactions: {
+    all: BankSyncTransaction[];
+    booked: BankSyncTransaction[];
+    pending: BankSyncTransaction[];
+  };
+  balances: BankSyncBalance[];
+  startingBalance: number;
+  error_type: string;
+  error_code: string;
+};
+
+export type BankSyncProviders = 'goCardless' | 'simpleFin' | 'pluggyai';

package/src/types/models/bank.ts

@@ -0,0 +1,6 @@
+export type BankEntity = {
+  id: string;
+  name: string;
+  bank_id: string;
+  tombstone: 0 | 1;
+};

package/src/types/models/category-group.ts

@@ -0,0 +1,11 @@
+import type { CategoryEntity } from './category';
+
+export type CategoryGroupEntity = {
+  id: string;
+  name: string;
+  is_income?: boolean;
+  sort_order?: number;
+  tombstone?: boolean;
+  hidden?: boolean;
+  categories?: CategoryEntity[];
+};

package/src/types/models/category.ts

@@ -0,0 +1,13 @@
+import type { CategoryGroupEntity } from './category-group';
+
+export type CategoryEntity = {
+  id: string;
+  name: string;
+  is_income?: boolean;
+  group: CategoryGroupEntity['id'];
+  goal_def?: string;
+  template_settings?: { source: 'notes' | 'ui' };
+  sort_order?: number;
+  tombstone?: boolean;
+  hidden?: boolean;
+};

package/src/types/models/dashboard.ts

@@ -0,0 +1,199 @@
+import type { CustomReportEntity } from './reports';
+import type { RuleConditionEntity } from './rule';
+
+export type DashboardPageEntity = {
+  id: string;
+  name: string;
+  tombstone: boolean;
+};
+
+export type TimeFrame = {
+  start: string;
+  end: string;
+  mode:
+    | 'sliding-window'
+    | 'static'
+    | 'full'
+    | 'lastMonth'
+    | 'lastYear'
+    | 'yearToDate'
+    | 'priorYearToDate';
+};
+
+type AbstractWidget<
+  T extends string,
+  Meta extends Record<string, unknown> | null = null,
+> = {
+  id: string;
+  dashboard_page_id: string;
+  type: T;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  meta: Meta;
+  tombstone: boolean;
+};
+
+export type NetWorthWidget = AbstractWidget<
+  'net-worth-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+    interval?: 'Daily' | 'Weekly' | 'Monthly' | 'Yearly';
+    mode?: 'trend' | 'stacked';
+  } | null
+>;
+
+export type CashFlowWidget = AbstractWidget<
+  'cash-flow-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+    showBalance?: boolean;
+  } | null
+>;
+export type SpendingWidget = AbstractWidget<
+  'spending-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    compare?: string;
+    compareTo?: string;
+    isLive?: boolean;
+    mode?: 'single-month' | 'budget' | 'average';
+  } | null
+>;
+export type BudgetAnalysisWidget = AbstractWidget<
+  'budget-analysis-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+    interval?: 'Daily' | 'Weekly' | 'Monthly' | 'Yearly';
+    graphType?: 'Line' | 'Bar';
+    showBalance?: boolean;
+  } | null
+>;
+export type CustomReportWidget = AbstractWidget<
+  'custom-report',
+  { id: string }
+>;
+export type CrossoverWidget = AbstractWidget<
+  'crossover-card',
+  {
+    name?: string;
+    expenseCategoryIds?: string[];
+    incomeAccountIds?: string[];
+    timeFrame?: TimeFrame;
+    safeWithdrawalRate?: number; // 0.04 default
+    estimatedReturn?: number | null; // annual
+    expectedContribution?: number | null; // monthly dollar amount
+    projectionType?: 'hampel' | 'median' | 'mean'; // expense projection method
+    showHiddenCategories?: boolean; // show hidden categories in selector
+    expenseAdjustmentFactor?: number; // multiplier for expenses (default 1.0)
+  } | null
+>;
+export type MarkdownWidget = AbstractWidget<
+  'markdown-card',
+  { content: string; text_align?: 'left' | 'right' | 'center' }
+>;
+
+type SpecializedWidget =
+  | NetWorthWidget
+  | CashFlowWidget
+  | SpendingWidget
+  | BudgetAnalysisWidget
+  | CrossoverWidget
+  | MarkdownWidget
+  | SummaryWidget
+  | CalendarWidget
+  | FormulaWidget;
+export type DashboardWidgetEntity = SpecializedWidget | CustomReportWidget;
+export type NewDashboardWidgetEntity = Omit<
+  DashboardWidgetEntity,
+  'id' | 'tombstone' | 'dashboard_page_id'
+>;
+
+// Exported/imported (json) widget definition
+export type ExportImportCustomReportWidget = Omit<
+  CustomReportWidget,
+  'id' | 'meta' | 'tombstone'
+> & {
+  meta: Omit<CustomReportEntity, 'tombstone'>;
+};
+export type ExportImportDashboardWidget = Omit<
+  ExportImportCustomReportWidget | SpecializedWidget,
+  'tombstone'
+>;
+
+export type ExportImportDashboard = {
+  // Dashboard exports can be versioned; currently we support
+  // only a single version, but lets account for multiple
+  // future versions
+  version: 1;
+  widgets: ExportImportDashboardWidget[];
+};
+
+export type SummaryWidget = AbstractWidget<
+  'summary-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+    content?: string;
+  } | null
+>;
+
+export type BaseSummaryContent = {
+  type: 'sum' | 'avgPerMonth' | 'avgPerYear' | 'avgPerTransact';
+  fontSize?: number;
+};
+
+export type PercentageSummaryContent = {
+  type: 'percentage';
+  divisorConditions: RuleConditionEntity[];
+  divisorConditionsOp: 'and' | 'or';
+  divisorAllTimeDateRange?: boolean;
+  fontSize?: number;
+};
+
+export type SummaryContent = BaseSummaryContent | PercentageSummaryContent;
+
+export type CalendarWidget = AbstractWidget<
+  'calendar-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+  } | null
+>;
+
+export type FormulaWidget = AbstractWidget<
+  'formula-card',
+  {
+    name?: string;
+    formula?: string;
+    fontSize?: number;
+    fontSizeMode?: 'dynamic' | 'static';
+    staticFontSize?: number;
+    colorFormula?: string;
+    queriesVersion?: number;
+    queries?: Record<
+      string,
+      {
+        conditions?: RuleConditionEntity[];
+        conditionsOp?: 'and' | 'or';
+        timeFrame?: TimeFrame;
+      }
+    >;
+  } | null
+>;