@firela/api-types 0.0.0-canary.792fa5f1 → 0.0.0-canary.7a8f5374

package/src/generated/types.gen.ts

@@ -442,6 +442,25 @@ export type CreateTransactionDto = {
  */
 export type flag = '*' | '!';
 
+export type CostDetailDto = {
+  /**
+   * Per-unit cost basis (mirrors engine Cost.number)
+   */
+  number?: string;
+  /**
+   * Cost currency
+   */
+  currency?: string;
+  /**
+   * Lot acquisition date (ISO yyyy-mm-dd)
+   */
+  date?: string;
+  /**
+   * Lot label
+   */
+  label?: string;
+};
+
 export type PostingResponseDto = {
   /**
    * Account name
@@ -455,6 +474,10 @@ export type PostingResponseDto = {
    * Currency
    */
   currency?: string;
+  /**
+   * Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.
+   */
+  cost?: CostDetailDto;
 };
 
 export type RecurringSuggestionDto = {
@@ -698,6 +721,10 @@ export type PostingDetailDto = {
    * Cost date
    */
   costDate?: string;
+  /**
+   * Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.
+   */
+  cost?: CostDetailDto;
   /**
    * Price amount
    */
@@ -1297,17 +1324,17 @@ export type ResolveResultDto = {
     [key: string]: string;
   };
   /**
-   * Resolution ID for undo
+   * Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).
    */
-  resolutionId: string;
+  resolutionId?: string;
   /**
    * Whether this decision can be undone
    */
-  canUndo: boolean;
+  canUndo?: boolean;
   /**
    * Deadline for undo (24h from resolution)
    */
-  undoDeadline: string;
+  undoDeadline?: string;
   /**
    * Rule ID if learning was triggered (ACCEPT_AND_LEARN actions). Use this to deep-link to the rule management page.
    */
@@ -3002,6 +3029,96 @@ export type UpdatePropertyDto = {
   value: string;
 };
 
+export type CreateBeanEventDto = {
+  /**
+   * Life event date (ISO 8601)
+   */
+  date: string;
+  /**
+   * Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer
+   */
+  type: string;
+  /**
+   * Life event description. Empty string is a VALID value (distinct from absence).
+   */
+  description: string;
+  /**
+   * Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)
+   */
+  meta?: {
+    [key: string]: unknown;
+  };
+};
+
+export type EventResponseDto = {
+  /**
+   * Unique identifier
+   */
+  id: string;
+  /**
+   * User ID (owner of the life event)
+   */
+  userId: string;
+  /**
+   * Life event date (ISO 8601 format)
+   */
+  date: string;
+  /**
+   * Life event type (user-defined, e.g., "employer", "location")
+   */
+  type: string;
+  /**
+   * Life event description. May be an empty string (a valid value distinct from absence).
+   */
+  description: string;
+  /**
+   * Product-side metadata (free-form JSON)
+   */
+  meta: {
+    [key: string]: unknown;
+  };
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+  /**
+   * Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.
+   */
+  updatedAt: string;
+};
+
+export type EventListResponseDto = {
+  /**
+   * List of life events
+   */
+  items: Array<EventResponseDto>;
+  /**
+   * Total number of life events matching the query
+   */
+  total: number;
+};
+
+export type UpdateBeanEventDto = {
+  /**
+   * Life event date (ISO 8601)
+   */
+  date?: string;
+  /**
+   * Life event type (user-defined)
+   */
+  type?: string;
+  /**
+   * Life event description. Empty string is a VALID value (distinct from absence).
+   */
+  description?: string;
+  /**
+   * Product-side metadata (free-form JSON)
+   */
+  meta?: {
+    [key: string]: unknown;
+  };
+};
+
 export type FileImportDto = {
   /**
    * Bill file to import (CSV, PDF, OFX, etc.)
@@ -4502,6 +4619,63 @@ export type CashFlowResponseDto = {
   warnings?: Array<ExchangeRateWarningDto>;
 };
 
+export type CategoryGroupDto = {
+  /**
+   * Functional category (account-path Group segment); regional and universal account paths merge under it
+   */
+  category: string;
+  /**
+   * Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)
+   */
+  totalExpense: string;
+  /**
+   * Share of grand total (0-100); 0 when grand total is 0
+   */
+  sharePct: number;
+  /**
+   * Raw (unconverted) expense per currency
+   */
+  balanceByCurrency: Array<BalanceByCurrencyDto>;
+  /**
+   * Converted total in base currency (omitted when FX missing for all currencies in this category)
+   */
+  convertedBalance?: string;
+};
+
+export type ExpensesByCategorySummaryDto = {
+  /**
+   * Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income
+   */
+  totalExpense: string;
+  /**
+   * Number of categories
+   */
+  categoryCount: number;
+};
+
+export type ExpensesByCategoryResponseDto = {
+  /**
+   * Period requested
+   */
+  period: string;
+  /**
+   * Base currency for converted values
+   */
+  baseCurrency: string;
+  /**
+   * Expense groups by functional category, sorted by converted total desc
+   */
+  groups: Array<CategoryGroupDto>;
+  /**
+   * Summary statistics
+   */
+  summary: ExpensesByCategorySummaryDto;
+  /**
+   * Exchange rate warnings (e.g. missing rate for a currency)
+   */
+  warnings?: Array<ExchangeRateWarningDto>;
+};
+
 export type MonetaryDto = {
   /**
    * Amount (Decimal string)
@@ -4825,6 +4999,14 @@ export type TimeSeriesPointDto = {
   change?: {
     [key: string]: unknown;
   };
+  /**
+   * Total assets at this date (in base currency)
+   */
+  assets?: string;
+  /**
+   * Total liabilities at this date (in base currency)
+   */
+  liabilities?: string;
   /**
    * Multi-currency breakdown for this point
    */
@@ -4892,6 +5074,71 @@ export type PortfolioTrendsResponseDto = {
   warnings?: Array<ExchangeRateWarningDto>;
 };
 
+export type CashFlowPointDto = {
+  /**
+   * Month key (YYYY-MM)
+   */
+  month: string;
+  /**
+   * Income in base currency (absolute, converted)
+   */
+  income: string;
+  /**
+   * Expense in base currency (absolute, converted)
+   */
+  expense: string;
+  /**
+   * netSavings = income − expense (savings positive)
+   */
+  netSavings: string;
+};
+
+export type CashFlowTrendSummaryDto = {
+  /**
+   * Total income across the period
+   */
+  totalIncome: string;
+  /**
+   * Total expense across the period
+   */
+  totalExpense: string;
+  /**
+   * income − expense across the period
+   */
+  totalNetSavings: string;
+  /**
+   * totalNetSavings divided by the window length (N months, incl. zero-filled)
+   */
+  averageMonthlyNetSavings: string;
+};
+
+export type CashFlowTrendsResponseDto = {
+  /**
+   * Monthly cash-flow series (fixed N-month window, zero-filled)
+   */
+  series: Array<CashFlowPointDto>;
+  /**
+   * Period totals
+   */
+  summary: CashFlowTrendSummaryDto;
+  /**
+   * Period requested
+   */
+  period: string;
+  /**
+   * Data granularity (v1 returns month buckets)
+   */
+  granularity: string;
+  /**
+   * Base currency for converted values
+   */
+  currency: string;
+  /**
+   * Exchange rate warnings (e.g. missing rate for a currency)
+   */
+  warnings?: Array<ExchangeRateWarningDto>;
+};
+
 export type GenerateSnapshotBody = unknown;
 
 export type GenerateSnapshotResponse = unknown;
@@ -5078,6 +5325,10 @@ export type TransactionControllerListData = {
    * Filter by account ID (transactions with postings to this account)
    */
   accountId?: string;
+  /**
+   * Filter by ADR-0075 functional category (Group segment); matches any posting to an Expenses/Income account whose derived Group segment equals this value
+   */
+  category?: string;
   /**
    * Filter by start date (inclusive), format: YYYY-MM-DD
    */
@@ -6069,6 +6320,104 @@ export type PropertyControllerDeleteData = {
 
 export type PropertyControllerDeleteResponse = void;
 
+export type EventControllerCreateData = {
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+  requestBody: CreateBeanEventDto;
+};
+
+export type EventControllerCreateResponse = EventResponseDto;
+
+export type EventControllerFindAllData = {
+  /**
+   * Filter life events from this date (ISO 8601 format)
+   */
+  from?: string;
+  /**
+   * Number of items per page (default: 20, max: 100)
+   */
+  limit?: number;
+  /**
+   * Page number for pagination (default: 1)
+   */
+  page?: number;
+  /**
+   * Search term for description (case-insensitive partial match)
+   */
+  q?: string;
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+  /**
+   * Filter life events to this date (ISO 8601 format)
+   */
+  to?: string;
+  /**
+   * Filter by life event type (exact match)
+   */
+  type?: string;
+};
+
+export type EventControllerFindAllResponse = EventListResponseDto;
+
+export type EventControllerFindOneData = {
+  /**
+   * Life event ID
+   */
+  id: string;
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+};
+
+export type EventControllerFindOneResponse = EventResponseDto;
+
+export type EventControllerUpdateData = {
+  /**
+   * Life event ID
+   */
+  id: string;
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+  requestBody: UpdateBeanEventDto;
+};
+
+export type EventControllerUpdateResponse = EventResponseDto;
+
+export type EventControllerDeleteData = {
+  /**
+   * Life event ID
+   */
+  id: string;
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+};
+
+export type EventControllerDeleteResponse = void;
+
+export type EventControllerGetSliceData = {
+  accountPattern: string;
+  granularity: string;
+  /**
+   * Life event ID
+   */
+  id: string;
+  /**
+   * Region code for tenant context (decorative for life events)
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+};
+
+export type EventControllerGetSliceResponse = unknown;
+
 export type ExportControllerExportBeancountResponse = unknown;
 
 export type FileImportControllerImportFileData = {
@@ -6374,6 +6723,28 @@ export type DashboardControllerGetCashFlowData = {
 
 export type DashboardControllerGetCashFlowResponse = CashFlowResponseDto;
 
+export type DashboardControllerGetExpensesData = {
+  /**
+   * Account root to aggregate (expense → ^Expenses:, income → ^Income:)
+   */
+  flow?: 'expense' | 'income';
+  /**
+   * Grouping strategy
+   */
+  groupBy?: 'category';
+  /**
+   * Time window (1m = current calendar month)
+   */
+  period?: '1m' | '3m' | '6m' | '1y';
+  /**
+   * Region code for tenant context
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+};
+
+export type DashboardControllerGetExpensesResponse =
+  ExpensesByCategoryResponseDto;
+
 export type HoldingPnlControllerGetHoldingPnlData = {
   /**
    * Scope to a single account
@@ -6510,6 +6881,24 @@ export type ReportingControllerGetPortfolioTrendsData = {
 export type ReportingControllerGetPortfolioTrendsResponse =
   PortfolioTrendsResponseDto;
 
+export type ReportingControllerGetCashFlowTrendsData = {
+  /**
+   * Data granularity (accepted for API symmetry; v1 returns month buckets)
+   */
+  granularity?: 'day' | 'week' | 'month';
+  /**
+   * Time period
+   */
+  period?: '1m' | '3m' | '6m' | '1y';
+  /**
+   * Region code for tenant context
+   */
+  region: 'cn' | 'us' | 'de' | 'gb';
+};
+
+export type ReportingControllerGetCashFlowTrendsResponse =
+  CashFlowTrendsResponseDto;
+
 export type ReportingControllerGenerateSnapshotData = {
   /**
    * Region code for tenant context
@@ -7941,6 +8330,102 @@ export type $OpenApiTs = {
       };
     };
   };
+  '/api/v1/{region}/bean/events': {
+    post: {
+      req: EventControllerCreateData;
+      res: {
+        /**
+         * Life event created successfully
+         */
+        201: EventResponseDto;
+        /**
+         * Life event already exists for this (userId, type, date) combination
+         */
+        409: unknown;
+      };
+    };
+    get: {
+      req: EventControllerFindAllData;
+      res: {
+        /**
+         * Life events retrieved successfully
+         */
+        200: EventListResponseDto;
+      };
+    };
+  };
+  '/api/v1/{region}/bean/events/{id}': {
+    get: {
+      req: EventControllerFindOneData;
+      res: {
+        /**
+         * Life event retrieved successfully
+         */
+        200: EventResponseDto;
+        /**
+         * Life event not found
+         */
+        404: unknown;
+      };
+    };
+    put: {
+      req: EventControllerUpdateData;
+      res: {
+        /**
+         * Life event updated successfully
+         */
+        200: EventResponseDto;
+        /**
+         * If-Match header is not a valid ISO 8601 date
+         */
+        400: unknown;
+        /**
+         * Life event not found
+         */
+        404: unknown;
+        /**
+         * Updated event conflicts with an existing (userId, type, date) combination
+         */
+        409: unknown;
+        /**
+         * If-Match precondition failed (updatedAt mismatch)
+         */
+        412: unknown;
+      };
+    };
+    delete: {
+      req: EventControllerDeleteData;
+      res: {
+        /**
+         * Life event deleted successfully
+         */
+        204: void;
+        /**
+         * Life event not found
+         */
+        404: unknown;
+      };
+    };
+  };
+  '/api/v1/{region}/bean/events/{id}/slice': {
+    get: {
+      req: EventControllerGetSliceData;
+      res: {
+        /**
+         * Time-series sliced by the life event range
+         */
+        200: unknown;
+        /**
+         * accountPattern query param is empty
+         */
+        400: unknown;
+        /**
+         * Life event not found
+         */
+        404: unknown;
+      };
+    };
+  };
   '/api/v1/{region}/bean/export/beancount': {
     get: {
       res: {
@@ -8356,6 +8841,25 @@ export type $OpenApiTs = {
       };
     };
   };
+  '/api/v1/{region}/dashboard/expenses': {
+    get: {
+      req: DashboardControllerGetExpensesData;
+      res: {
+        /**
+         * Expenses retrieved successfully
+         */
+        200: ExpensesByCategoryResponseDto;
+        /**
+         * Invalid groupBy or period
+         */
+        400: unknown;
+        /**
+         * User not authenticated
+         */
+        401: unknown;
+      };
+    };
+  };
   '/api/v1/{region}/investment/holdings/pnl': {
     get: {
       req: HoldingPnlControllerGetHoldingPnlData;
@@ -8474,6 +8978,21 @@ export type $OpenApiTs = {
       };
     };
   };
+  '/api/v1/{region}/reporting/cash-flow/trends': {
+    get: {
+      req: ReportingControllerGetCashFlowTrendsData;
+      res: {
+        /**
+         * Cash-flow trends retrieved successfully
+         */
+        200: CashFlowTrendsResponseDto;
+        /**
+         * User not authenticated
+         */
+        401: unknown;
+      };
+    };
+  };
   '/api/v1/{region}/reporting/snapshots/generate': {
     post: {
       req: ReportingControllerGenerateSnapshotData;