@actual-app/api 6.9.0 → 24.10.0

package/@types/loot-core/types/api-handlers.d.ts

@@ -63,13 +63,24 @@ export interface ApiHandlers {
     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;
   }) => Promise<unknown>;
 
-  'api/transactions-import': (arg: { accountId; transactions }) => Promise<{
+  'api/transactions-import': (arg: {
+    accountId;
+    transactions;
+    isPreview?;
+  }) => Promise<{
     errors?: { message: string }[];
     added;
     updated;
@@ -95,7 +106,7 @@ export interface ApiHandlers {
 
   'api/transaction-delete': (arg: {
     id;
-  }) => Promise<Awaited<ReturnType<typeof batchUpdateTransactions>>['updated']>;
+  }) => Promise<Awaited<ReturnType<typeof batchUpdateTransactions>>['deleted']>;
 
   'api/sync': () => Promise<void>;
 
@@ -169,5 +180,5 @@ export interface ApiHandlers {
 
   'api/rule-update': (arg: { rule: RuleEntity }) => Promise<RuleEntity>;
 
-  'api/rule-delete': (arg: { id: string }) => Promise<boolean>;
+  'api/rule-delete': (id: string) => Promise<boolean>;
 }

package/@types/loot-core/types/handlers.d.ts

@@ -1,6 +1,8 @@
 import type { BudgetHandlers } from '../server/budget/types/handlers';
+import type { DashboardHandlers } from '../server/dashboard/types/handlers';
 import type { FiltersHandlers } from '../server/filters/types/handlers';
 import type { NotesHandlers } from '../server/notes/types/handlers';
+import type { PreferencesHandlers } from '../server/preferences/types/handlers';
 import type { ReportsHandlers } from '../server/reports/types/handlers';
 import type { RulesHandlers } from '../server/rules/types/handlers';
 import type { SchedulesHandlers } from '../server/schedules/types/handlers';
@@ -13,8 +15,10 @@ export interface Handlers
   extends ServerHandlers,
     ApiHandlers,
     BudgetHandlers,
+    DashboardHandlers,
     FiltersHandlers,
     NotesHandlers,
+    PreferencesHandlers,
     ReportsHandlers,
     RulesHandlers,
     SchedulesHandlers,

package/@types/loot-core/types/models/category-group.d.ts

@@ -1,11 +1,15 @@
 import { CategoryEntity } from './category';
 
-export interface CategoryGroupEntity {
-  id?: string;
+export interface NewCategoryGroupEntity {
   name: string;
   is_income?: boolean;
   sort_order?: number;
   tombstone?: boolean;
   hidden?: boolean;
+  categories?: Omit<CategoryEntity, 'id'>[];
+}
+
+export interface CategoryGroupEntity extends NewCategoryGroupEntity {
+  id: string;
   categories?: CategoryEntity[];
 }

package/@types/loot-core/types/models/category.d.ts

@@ -1,8 +1,10 @@
+import { CategoryGroupEntity } from './category-group';
+
 export interface CategoryEntity {
-  id?: string;
+  id: string;
   name: string;
   is_income?: boolean;
-  cat_group?: string;
+  cat_group?: CategoryGroupEntity['id'];
   sort_order?: number;
   tombstone?: boolean;
   hidden?: boolean;

package/@types/loot-core/types/models/dashboard.d.ts

@@ -0,0 +1,89 @@
+import { type CustomReportEntity } from './reports';
+import { type RuleConditionEntity } from './rule';
+
+export type TimeFrame = {
+  start: string;
+  end: string;
+  mode: 'sliding-window' | 'static' | 'full';
+};
+
+type AbstractWidget<
+  T extends string,
+  Meta extends Record<string, unknown> = null,
+> = {
+  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;
+  } | null
+>;
+export type CashFlowWidget = AbstractWidget<
+  'cash-flow-card',
+  {
+    name?: string;
+    conditions?: RuleConditionEntity[];
+    conditionsOp?: 'and' | 'or';
+    timeFrame?: TimeFrame;
+  } | 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 CustomReportWidget = AbstractWidget<
+  'custom-report',
+  { id: string }
+>;
+export type MarkdownWidget = AbstractWidget<
+  'markdown-card',
+  { content: string; text_align?: 'left' | 'right' | 'center' }
+>;
+
+type SpecializedWidget =
+  | NetWorthWidget
+  | CashFlowWidget
+  | SpendingWidget
+  | MarkdownWidget;
+export type Widget = SpecializedWidget | CustomReportWidget;
+export type NewWidget = Omit<Widget, 'id' | 'tombstone'>;
+
+// 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[];
+};

package/@types/loot-core/types/models/index.d.ts

@@ -1,6 +1,7 @@
 export type * from './account';
 export type * from './category';
 export type * from './category-group';
+export type * from './dashboard';
 export type * from './gocardless';
 export type * from './simplefin';
 export type * from './note';

package/@types/loot-core/types/models/payee.d.ts

@@ -1,11 +1,9 @@
-export interface NewPayeeEntity {
-  id?: string;
+import { AccountEntity } from './account';
+
+export interface PayeeEntity {
+  id: string;
   name: string;
-  transfer_acct?: string;
+  transfer_acct?: AccountEntity['id'];
   favorite?: boolean;
   tombstone?: boolean;
 }
-
-export interface PayeeEntity extends NewPayeeEntity {
-  id: string;
-}

package/@types/loot-core/types/models/reports.d.ts

@@ -1,4 +1,3 @@
-import { CategoryEntity } from './category';
 import { type RuleConditionEntity } from './rule';
 
 export interface CustomReportEntity {
@@ -17,10 +16,9 @@ export interface CustomReportEntity {
   showHiddenCategories: boolean;
   includeCurrentInterval: boolean;
   showUncategorized: boolean;
-  selectedCategories?: CategoryEntity[];
   graphType: string;
   conditions?: RuleConditionEntity[];
-  conditionsOp: string;
+  conditionsOp: 'and' | 'or';
   data?: GroupedEntity;
   tombstone?: boolean;
 }
@@ -32,14 +30,6 @@ export type balanceTypeOpType =
   | 'netAssets'
   | 'netDebts';
 
-export type spendingReportTimeType =
-  | 'average'
-  | 'thisMonth'
-  | 'lastMonth'
-  | 'twoMonthsPrevious'
-  | 'lastYear'
-  | 'lastYearPrevious';
-
 export type SpendingMonthEntity = Record<
   string | number,
   {
@@ -63,11 +53,9 @@ export interface SpendingEntity {
     months: SpendingMonthEntity;
     day: string;
     average: number;
-    thisMonth: number;
-    lastMonth: number;
-    twoMonthsPrevious: number;
-    lastYear: number;
-    lastYearPrevious: number;
+    compare: number;
+    compareTo: number;
+    budget: number;
   }[];
   startDate?: string;
   endDate?: string;
@@ -140,10 +128,9 @@ export interface CustomReportData {
   show_hidden: number;
   include_current: number;
   show_uncategorized: number;
-  selected_categories?: CategoryEntity[];
   graph_type: string;
   conditions?: RuleConditionEntity[];
-  conditions_op: string;
+  conditions_op: 'and' | 'or';
   metadata?: GroupedEntity;
   interval: string;
   color_scheme?: string;

package/@types/loot-core/types/models/rule.d.ts

@@ -25,12 +25,31 @@ export type RuleConditionOp =
   | 'lte'
   | 'contains'
   | 'doesNotContain'
+  | 'hasTags'
   | 'matches';
 
-export interface RuleConditionEntity {
-  field?: string;
-  op?: RuleConditionOp;
-  value?: string | string[] | number | boolean;
+type FieldValueTypes = {
+  account: string;
+  amount: number;
+  category: string;
+  date: string;
+  notes: string;
+  payee: string;
+  imported_payee: string;
+  saved: string;
+  cleared: boolean;
+  reconciled: boolean;
+};
+
+type BaseConditionEntity<
+  Field extends keyof FieldValueTypes,
+  Op extends RuleConditionOp,
+> = {
+  field: Field;
+  op: Op;
+  value: Op extends 'oneOf' | 'notOneOf'
+    ? Array<FieldValueTypes[Field]>
+    : FieldValueTypes[Field];
   options?: {
     inflow?: boolean;
     outflow?: boolean;
@@ -38,14 +57,81 @@ export interface RuleConditionEntity {
     year?: boolean;
   };
   conditionsOp?: string;
-  type?: string;
+  type?: 'id' | 'boolean' | 'date' | 'number' | 'string';
   customName?: string;
-}
+  queryFilter?: Record<string, { $oneof: string[] }>;
+};
+
+export type RuleConditionEntity =
+  | BaseConditionEntity<
+      'account',
+      | 'is'
+      | 'isNot'
+      | 'oneOf'
+      | 'notOneOf'
+      | 'contains'
+      | 'doesNotContain'
+      | 'matches'
+    >
+  | BaseConditionEntity<
+      'category',
+      | 'is'
+      | 'isNot'
+      | 'oneOf'
+      | 'notOneOf'
+      | 'contains'
+      | 'doesNotContain'
+      | 'matches'
+    >
+  | BaseConditionEntity<
+      'amount',
+      'is' | 'isapprox' | 'isbetween' | 'gt' | 'gte' | 'lt' | 'lte'
+    >
+  | BaseConditionEntity<
+      'date',
+      'is' | 'isapprox' | 'isbetween' | 'gt' | 'gte' | 'lt' | 'lte'
+    >
+  | BaseConditionEntity<
+      'notes',
+      | 'is'
+      | 'isNot'
+      | 'oneOf'
+      | 'notOneOf'
+      | 'contains'
+      | 'doesNotContain'
+      | 'matches'
+      | 'hasTags'
+    >
+  | BaseConditionEntity<
+      'payee',
+      | 'is'
+      | 'isNot'
+      | 'oneOf'
+      | 'notOneOf'
+      | 'contains'
+      | 'doesNotContain'
+      | 'matches'
+    >
+  | BaseConditionEntity<
+      'imported_payee',
+      | 'is'
+      | 'isNot'
+      | 'oneOf'
+      | 'notOneOf'
+      | 'contains'
+      | 'doesNotContain'
+      | 'matches'
+    >
+  | BaseConditionEntity<'saved', 'is'>
+  | BaseConditionEntity<'cleared', 'is'>
+  | BaseConditionEntity<'reconciled', 'is'>;
 
 export type RuleActionEntity =
   | SetRuleActionEntity
   | SetSplitAmountRuleActionEntity
-  | LinkScheduleRuleActionEntity;
+  | LinkScheduleRuleActionEntity
+  | PrependNoteRuleActionEntity
+  | AppendNoteRuleActionEntity;
 
 export interface SetRuleActionEntity {
   field: string;
@@ -70,3 +156,13 @@ export interface LinkScheduleRuleActionEntity {
   op: 'link-schedule';
   value: ScheduleEntity;
 }
+
+export interface PrependNoteRuleActionEntity {
+  op: 'prepend-notes';
+  value: string;
+}
+
+export interface AppendNoteRuleActionEntity {
+  op: 'append-notes';
+  value: string;
+}

package/@types/loot-core/types/models/schedule.d.ts

@@ -2,6 +2,23 @@ import type { AccountEntity } from './account';
 import type { PayeeEntity } from './payee';
 import type { RuleEntity } from './rule';
 
+export interface RecurPattern {
+  value: number;
+  type: 'SU' | 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'day';
+}
+
+export interface RecurConfig {
+  frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+  interval: number;
+  patterns?: RecurPattern[];
+  skipWeekend?: boolean;
+  start: string;
+  endMode: 'never' | 'after_n_occurrences' | 'on_date';
+  endOccurrences?: number;
+  endDate?: string;
+  weekendSolveMode?: 'before' | 'after';
+}
+
 export interface ScheduleEntity {
   id: string;
   name?: string;
@@ -17,20 +34,7 @@ export interface ScheduleEntity {
   _account: AccountEntity['id'];
   _amount: unknown;
   _amountOp: string;
-  _date: {
-    interval: number;
-    patterns: {
-      value: number;
-      type: 'SU' | 'MO' | 'TU' | 'WE' | 'TH' | 'FR' | 'SA' | 'day';
-    }[];
-    skipWeekend: boolean;
-    start: string;
-    endMode: 'never' | 'after_n_occurrences' | 'on_date';
-    endOccurrences: number;
-    endDate: string;
-    weekendSolveMode: 'before' | 'after';
-    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
-  };
+  _date: RecurConfig;
   _conditions: unknown;
   _actions: unknown;
 }

package/@types/loot-core/types/models/transaction-filter.d.ts

@@ -1,7 +1,9 @@
+import { type RuleConditionEntity } from './rule';
+
 export interface TransactionFilterEntity {
   id: string;
   name: string;
-  conditions_op: string;
-  conditions: unknown;
+  conditionsOp: 'and' | 'or';
+  conditions: RuleConditionEntity[];
   tombstone: boolean;
 }

package/@types/loot-core/types/models/transaction.d.ts

@@ -1,40 +1,29 @@
-import type { AccountEntity } from './account';
-import type { CategoryEntity } from './category';
-import type { PayeeEntity } from './payee';
-import type { ScheduleEntity } from './schedule';
+import { AccountEntity } from './account';
+import { CategoryEntity } from './category';
+import { PayeeEntity } from './payee';
+import { ScheduleEntity } from './schedule';
 
-export interface NewTransactionEntity {
-  id?: string;
+export interface TransactionEntity {
+  id: string;
   is_parent?: boolean;
   is_child?: boolean;
-  parent_id?: string;
-  account: string;
-  category?: string;
+  parent_id?: TransactionEntity['id'];
+  account: AccountEntity['id'];
+  category?: CategoryEntity['id'];
   amount: number;
-  payee?: string;
+  payee?: PayeeEntity['id'];
   notes?: string;
   date: string;
   imported_id?: string;
   imported_payee?: string;
   starting_balance_flag?: boolean;
-  transfer_id?: string;
+  transfer_id?: TransactionEntity['id'];
   sort_order?: number;
   cleared?: boolean;
   reconciled?: boolean;
   tombstone?: boolean;
-  schedule?: string;
-  subtransactions?: Omit<NewTransactionEntity, 'account' | 'date'>[];
-}
-
-export interface TransactionEntity
-  extends Omit<
-    NewTransactionEntity,
-    'account' | 'category' | 'payee' | 'schedule' | 'subtransactions'
-  > {
-  id: string;
-  account: AccountEntity;
-  category?: CategoryEntity;
-  payee?: PayeeEntity;
-  schedule?: ScheduleEntity;
+  schedule?: ScheduleEntity['id'];
   subtransactions?: TransactionEntity[];
+  _unmatched?: boolean;
+  _deleted?: boolean;
 }

package/@types/loot-core/types/prefs.d.ts

@@ -1,70 +1,80 @@
-import { type numberFormats } from '../shared/util';
-
-import { spendingReportTimeType } from './models/reports';
-
 export type FeatureFlag =
+  | 'dashboards'
   | 'reportBudget'
   | 'goalTemplatesEnabled'
-  | 'spendingReport'
-  | 'simpleFinSync'
-  | 'iterableTopologicalSort';
+  | 'spendingReport';
 
-export type LocalPrefs = Partial<
-  {
-    firstDayOfWeekIdx: `${0 | 1 | 2 | 3 | 4 | 5 | 6}`;
-    dateFormat:
-      | 'MM/dd/yyyy'
-      | 'dd/MM/yyyy'
-      | 'yyyy-MM-dd'
-      | 'MM.dd.yyyy'
-      | 'dd.MM.yyyy';
-    numberFormat: (typeof numberFormats)[number]['value'];
-    hideFraction: boolean;
-    isPrivacyEnabled: boolean;
-    budgetName: string;
-    'ui.showClosedAccounts': boolean;
-    'expand-splits': boolean;
-    [key: `show-extra-balances-${string}`]: boolean;
-    [key: `hide-cleared-${string}`]: boolean;
-    [key: `hide-reconciled-${string}`]: boolean;
-    'budget.collapsed': string[];
-    'budget.summaryCollapsed': boolean;
-    'budget.showHiddenCategories': boolean;
-    'budget.startMonth': string;
+/**
+ * Cross-device preferences. These sync across devices when they are changed.
+ */
+export type SyncedPrefs = Partial<
+  Record<
+    | 'budgetType'
+    | 'firstDayOfWeekIdx'
+    | 'dateFormat'
+    | 'numberFormat'
+    | 'hideFraction'
+    | 'isPrivacyEnabled'
+    | `show-balances-${string}`
+    | `show-extra-balances-${string}`
+    | `hide-cleared-${string}`
+    | `hide-reconciled-${string}`
     // TODO: pull from src/components/modals/ImportTransactions.js
-    [key: `parse-date-${string}-${'csv' | 'qif'}`]: string;
-    [key: `csv-mappings-${string}`]: string;
-    [key: `csv-delimiter-${string}`]: ',' | ';' | '\t';
-    [key: `csv-has-header-${string}`]: boolean;
-    [key: `ofx-fallback-missing-payee-${string}`]: boolean;
-    [key: `flip-amount-${string}-${'csv' | 'qif'}`]: boolean;
-    'flags.updateNotificationShownForVersion': string;
-    id: string;
-    lastUploaded: string;
-    cloudFileId: string;
-    groupId: string;
-    budgetType: 'report' | 'rollover';
-    encryptKeyId: string;
-    lastSyncedTimestamp: string;
-    userId: string;
-    resetClock: boolean;
-    lastScheduleRun: string;
-    reportsViewLegend: boolean;
-    reportsViewSummary: boolean;
-    reportsViewLabel: boolean;
-    spendingReportFilter: string;
-    spendingReportTime: spendingReportTimeType;
-    spendingReportCompare: spendingReportTimeType;
-    sidebarWidth: number;
-    'mobile.showSpentColumn': boolean;
-  } & Record<`flags.${FeatureFlag}`, boolean>
+    | `parse-date-${string}-${'csv' | 'qif'}`
+    | `csv-mappings-${string}`
+    | `csv-delimiter-${string}`
+    | `csv-skip-lines-${string}`
+    | `csv-has-header-${string}`
+    | `ofx-fallback-missing-payee-${string}`
+    | `flip-amount-${string}-${'csv' | 'qif'}`
+    | `flags.${FeatureFlag}`,
+    string
+  >
 >;
 
+/**
+ * Preferences that are stored in the `metadata.json` file along with the
+ * core database.
+ */
+export type MetadataPrefs = Partial<{
+  budgetName: string;
+  id: string;
+  lastUploaded: string;
+  cloudFileId: string;
+  groupId: string;
+  encryptKeyId: string;
+  lastSyncedTimestamp: string;
+  resetClock: boolean;
+  lastScheduleRun: string;
+  userId: string; // TODO: delete this (unused)
+}>;
+
+/**
+ * Local preferences applicable to a single device. Stored in local storage.
+ */
+export type LocalPrefs = Partial<{
+  'ui.showClosedAccounts': boolean;
+  'expand-splits': boolean;
+  'budget.collapsed': string[];
+  'budget.summaryCollapsed': boolean;
+  'budget.showHiddenCategories': boolean;
+  'budget.startMonth': string;
+  'flags.updateNotificationShownForVersion': string;
+  reportsViewLegend: boolean;
+  reportsViewSummary: boolean;
+  reportsViewLabel: boolean;
+  sidebarWidth: number;
+  'mobile.showSpentColumn': boolean;
+}>;
+
 export type Theme = 'light' | 'dark' | 'auto' | 'midnight' | 'development';
+export type DarkTheme = 'dark' | 'midnight';
 export type GlobalPrefs = Partial<{
   floatingSidebar: boolean;
   maxMonths: number;
   keyId?: string;
   theme: Theme;
+  preferredDarkTheme: DarkTheme;
   documentDir: string; // Electron only
+  serverSelfSignedCert: string; // Electron only
 }>;

package/@types/loot-core/types/server-events.d.ts

@@ -18,4 +18,5 @@ export interface ServerEvents {
   'start-load': unknown;
   'sync-event': { type; subtype; meta; tables; syncDisabled };
   'undo-event': UndoState;
+  'api-fetch-redirected': unknown;
 }