@firela/api-types 0.0.0-canary.3ed455fd → 0.0.0-canary.45a6cc23

package/src/generated/schemas.gen.ts

@@ -1855,7 +1855,8 @@ export const $ResolveResultDto = {
     },
     resolutionId: {
       type: 'string',
-      description: 'Resolution ID for undo'
+      description:
+        'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
     },
     canUndo: {
       type: 'boolean',
@@ -1873,7 +1874,7 @@ export const $ResolveResultDto = {
       example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
     }
   },
-  required: ['success', 'resolutionId', 'canUndo', 'undoDeadline']
+  required: ['success']
 } as const;
 
 export const $UndoResultDto = {
@@ -4311,6 +4312,144 @@ export const $UpdatePropertyDto = {
   required: ['value']
 } as const;
 
+export const $CreateBeanEventDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)',
+      example: '2024-03-15'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
+      example: {
+        note: 'Promotion'
+      }
+    }
+  },
+  required: ['date', 'type', 'description']
+} as const;
+
+export const $EventResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the life event)',
+      example: 'user-123'
+    },
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601 format)',
+      example: '2024-03-15',
+      format: 'date'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (user-defined, e.g., "employer", "location")',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. May be an empty string (a valid value distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)',
+      example: {
+        note: 'Promotion'
+      }
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-03-15T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description:
+        'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
+      example: '2024-03-15T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'date',
+    'type',
+    'description',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $EventListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of life events',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/EventResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of life events matching the query',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateBeanEventDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)'
+    },
+    type: {
+      type: 'string',
+      description: 'Life event type (user-defined)'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)'
+    }
+  }
+} as const;
+
 export const $FileImportDto = {
   type: 'object',
   properties: {
@@ -6483,6 +6622,100 @@ export const $CashFlowResponseDto = {
   ]
 } as const;
 
+export const $CategoryGroupDto = {
+  type: 'object',
+  properties: {
+    category: {
+      type: 'string',
+      description:
+        'Functional category (account-path Group segment); regional and universal account paths merge under it',
+      example: 'Food'
+    },
+    totalExpense: {
+      type: 'string',
+      description: 'Converted total expense in base currency',
+      example: '1200.00'
+    },
+    sharePct: {
+      type: 'number',
+      description: 'Share of grand total (0-100); 0 when grand total is 0',
+      example: 42.5
+    },
+    balanceByCurrency: {
+      description: 'Raw (unconverted) expense per currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    convertedBalance: {
+      type: 'string',
+      description:
+        'Converted total in base currency (omitted when FX missing for all currencies in this category)',
+      example: '1200.00'
+    }
+  },
+  required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
+} as const;
+
+export const $ExpensesByCategorySummaryDto = {
+  type: 'object',
+  properties: {
+    totalExpense: {
+      type: 'string',
+      description:
+        'Total expense across all categories (converted; convertible categories only)',
+      example: '5000.00'
+    },
+    categoryCount: {
+      type: 'number',
+      description: 'Number of categories',
+      example: 8
+    }
+  },
+  required: ['totalExpense', 'categoryCount']
+} as const;
+
+export const $ExpensesByCategoryResponseDto = {
+  type: 'object',
+  properties: {
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '1m'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    groups: {
+      description:
+        'Expense groups by functional category, sorted by converted total desc',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CategoryGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
+        }
+      ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['period', 'baseCurrency', 'groups', 'summary']
+} as const;
+
 export const $MonetaryDto = {
   type: 'object',
   properties: {
@@ -6964,6 +7197,16 @@ export const $TimeSeriesPointDto = {
       description: 'Change from previous point',
       example: '5000.00'
     },
+    assets: {
+      type: 'string',
+      description: 'Total assets at this date (in base currency)',
+      example: '494338.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Total liabilities at this date (in base currency)',
+      example: '310098.00'
+    },
     byCurrency: {
       description: 'Multi-currency breakdown for this point',
       type: 'array',
@@ -7073,6 +7316,111 @@ export const $PortfolioTrendsResponseDto = {
   required: ['series', 'summary', 'period', 'granularity', 'currency']
 } as const;
 
+export const $CashFlowPointDto = {
+  type: 'object',
+  properties: {
+    month: {
+      type: 'string',
+      description: 'Month key (YYYY-MM)',
+      example: '2024-03'
+    },
+    income: {
+      type: 'string',
+      description: 'Income in base currency (absolute, converted)',
+      example: '10000.00'
+    },
+    expense: {
+      type: 'string',
+      description: 'Expense in base currency (absolute, converted)',
+      example: '5000.00'
+    },
+    netSavings: {
+      type: 'string',
+      description: 'netSavings = income − expense (savings positive)',
+      example: '5000.00'
+    }
+  },
+  required: ['month', 'income', 'expense', 'netSavings']
+} as const;
+
+export const $CashFlowTrendSummaryDto = {
+  type: 'object',
+  properties: {
+    totalIncome: {
+      type: 'string',
+      description: 'Total income across the period',
+      example: '60000.00'
+    },
+    totalExpense: {
+      type: 'string',
+      description: 'Total expense across the period',
+      example: '30000.00'
+    },
+    totalNetSavings: {
+      type: 'string',
+      description: 'income − expense across the period',
+      example: '30000.00'
+    },
+    averageMonthlyNetSavings: {
+      type: 'string',
+      description:
+        'totalNetSavings divided by the window length (N months, incl. zero-filled)',
+      example: '5000.00'
+    }
+  },
+  required: [
+    'totalIncome',
+    'totalExpense',
+    'totalNetSavings',
+    'averageMonthlyNetSavings'
+  ]
+} as const;
+
+export const $CashFlowTrendsResponseDto = {
+  type: 'object',
+  properties: {
+    series: {
+      description:
+        'Monthly cash-flow series (fixed N-month window, zero-filled)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CashFlowPointDto'
+      }
+    },
+    summary: {
+      description: 'Period totals',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CashFlowTrendSummaryDto'
+        }
+      ]
+    },
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '6m'
+    },
+    granularity: {
+      type: 'string',
+      description: 'Data granularity (v1 returns month buckets)',
+      example: 'month'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['series', 'summary', 'period', 'granularity', 'currency']
+} as const;
+
 export const $GenerateSnapshotBody = {
   type: 'object',
   properties: {}

package/src/generated/services.gen.ts

@@ -171,6 +171,18 @@ import type {
   PropertyControllerUpdateResponse,
   PropertyControllerDeleteData,
   PropertyControllerDeleteResponse,
+  EventControllerCreateData,
+  EventControllerCreateResponse,
+  EventControllerFindAllData,
+  EventControllerFindAllResponse,
+  EventControllerFindOneData,
+  EventControllerFindOneResponse,
+  EventControllerUpdateData,
+  EventControllerUpdateResponse,
+  EventControllerDeleteData,
+  EventControllerDeleteResponse,
+  EventControllerGetSliceData,
+  EventControllerGetSliceResponse,
   ExportControllerExportBeancountResponse,
   FileImportControllerImportFileData,
   FileImportControllerImportFileResponse,
@@ -218,6 +230,8 @@ import type {
   DashboardControllerGetAccountsResponse,
   DashboardControllerGetCashFlowData,
   DashboardControllerGetCashFlowResponse,
+  DashboardControllerGetExpensesData,
+  DashboardControllerGetExpensesResponse,
   HoldingPnlControllerGetHoldingPnlData,
   HoldingPnlControllerGetHoldingPnlResponse,
   PriceControllerCreateData,
@@ -234,6 +248,8 @@ import type {
   PriceControllerBulkCreateResponse,
   ReportingControllerGetPortfolioTrendsData,
   ReportingControllerGetPortfolioTrendsResponse,
+  ReportingControllerGetCashFlowTrendsData,
+  ReportingControllerGetCashFlowTrendsResponse,
   ReportingControllerGenerateSnapshotData,
   ReportingControllerGenerateSnapshotResponse,
   ReportingControllerBackfillSnapshotsData,
@@ -569,6 +585,7 @@ export class BeanTransactionsService {
    * @param data.status Filter by transaction status
    * @param data.search Search in narration and payee fields (max 200 chars)
    * @param data.accountId Filter by account ID (transactions with postings to this account)
+   * @param data.category Filter by ADR-0075 functional category (Group segment); matches any posting to an Expenses/Income account whose derived Group segment equals this value
    * @returns TransactionListResponseDto Transaction list
    * @throws ApiError
    */
@@ -588,7 +605,8 @@ export class BeanTransactionsService {
         dateTo: data.dateTo,
         status: data.status,
         search: data.search,
-        accountId: data.accountId
+        accountId: data.accountId,
+        category: data.category
       },
       errors: {
         400: 'Validation failed',
@@ -2460,6 +2478,181 @@ export class PropertiesService {
   }
 }
 
+export class LifeEventsService {
+  /**
+   * Create a new life event
+   * Creates a new life event entry for the authenticated user. Returns ETag header carrying the row updatedAt.
+   * @param data The data for the request.
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @param data.requestBody
+   * @returns EventResponseDto Life event created successfully
+   * @throws ApiError
+   */
+  public static eventControllerCreate(
+    data: EventControllerCreateData
+  ): CancelablePromise<EventControllerCreateResponse> {
+    return __request(OpenAPI, {
+      method: 'POST',
+      url: '/api/v1/{region}/bean/events',
+      path: {
+        region: data.region
+      },
+      body: data.requestBody,
+      mediaType: 'application/json',
+      errors: {
+        409: 'Life event already exists for this (userId, type, date) combination'
+      }
+    });
+  }
+
+  /**
+   * List user life events
+   * Returns life events for the authenticated user with optional filtering by type, description search, and date range.
+   * @param data The data for the request.
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @param data.type Filter by life event type (exact match)
+   * @param data.q Search term for description (case-insensitive partial match)
+   * @param data.from Filter life events from this date (ISO 8601 format)
+   * @param data.to Filter life events to this date (ISO 8601 format)
+   * @param data.page Page number for pagination (default: 1)
+   * @param data.limit Number of items per page (default: 20, max: 100)
+   * @returns EventListResponseDto Life events retrieved successfully
+   * @throws ApiError
+   */
+  public static eventControllerFindAll(
+    data: EventControllerFindAllData
+  ): CancelablePromise<EventControllerFindAllResponse> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/{region}/bean/events',
+      path: {
+        region: data.region
+      },
+      query: {
+        type: data.type,
+        q: data.q,
+        from: data.from,
+        to: data.to,
+        page: data.page,
+        limit: data.limit
+      }
+    });
+  }
+
+  /**
+   * Get life event by ID
+   * Returns a single life event by its ID. Returns ETag header.
+   * @param data The data for the request.
+   * @param data.id Life event ID
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @returns EventResponseDto Life event retrieved successfully
+   * @throws ApiError
+   */
+  public static eventControllerFindOne(
+    data: EventControllerFindOneData
+  ): CancelablePromise<EventControllerFindOneResponse> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/{region}/bean/events/{id}',
+      path: {
+        id: data.id,
+        region: data.region
+      },
+      errors: {
+        404: 'Life event not found'
+      }
+    });
+  }
+
+  /**
+   * Update a life event
+   * Updates an existing life event. If If-Match header is provided, performs optimistic concurrency check; mismatched updatedAt returns 412.
+   * @param data The data for the request.
+   * @param data.id Life event ID
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @param data.requestBody
+   * @returns EventResponseDto Life event updated successfully
+   * @throws ApiError
+   */
+  public static eventControllerUpdate(
+    data: EventControllerUpdateData
+  ): CancelablePromise<EventControllerUpdateResponse> {
+    return __request(OpenAPI, {
+      method: 'PUT',
+      url: '/api/v1/{region}/bean/events/{id}',
+      path: {
+        id: data.id,
+        region: data.region
+      },
+      body: data.requestBody,
+      mediaType: 'application/json',
+      errors: {
+        400: 'If-Match header is not a valid ISO 8601 date',
+        404: 'Life event not found',
+        409: 'Updated event conflicts with an existing (userId, type, date) combination',
+        412: 'If-Match precondition failed (updatedAt mismatch)'
+      }
+    });
+  }
+
+  /**
+   * Delete a life event
+   * Deletes a life event entry (hard delete). Returns 204.
+   * @param data The data for the request.
+   * @param data.id Life event ID
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @returns void Life event deleted successfully
+   * @throws ApiError
+   */
+  public static eventControllerDelete(
+    data: EventControllerDeleteData
+  ): CancelablePromise<EventControllerDeleteResponse> {
+    return __request(OpenAPI, {
+      method: 'DELETE',
+      url: '/api/v1/{region}/bean/events/{id}',
+      path: {
+        id: data.id,
+        region: data.region
+      },
+      errors: {
+        404: 'Life event not found'
+      }
+    });
+  }
+
+  /**
+   * Slice time-series by a life event (Phase 79)
+   * Returns aggregated time-series for postings matching accountPattern within the half-open date range of the given life event.
+   * @param data The data for the request.
+   * @param data.id Life event ID
+   * @param data.accountPattern
+   * @param data.granularity
+   * @param data.region Region code for tenant context (decorative for life events)
+   * @returns unknown Time-series sliced by the life event range
+   * @throws ApiError
+   */
+  public static eventControllerGetSlice(
+    data: EventControllerGetSliceData
+  ): CancelablePromise<EventControllerGetSliceResponse> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/{region}/bean/events/{id}/slice',
+      path: {
+        id: data.id,
+        region: data.region
+      },
+      query: {
+        accountPattern: data.accountPattern,
+        granularity: data.granularity
+      },
+      errors: {
+        400: 'accountPattern query param is empty',
+        404: 'Life event not found'
+      }
+    });
+  }
+}
+
 export class BeanExportService {
   /**
    * Export Beancount ledger as ZIP
@@ -3097,6 +3290,36 @@ export class DashboardService {
       }
     });
   }
+
+  /**
+   * Get expenses grouped by functional category
+   * Returns expenses pre-aggregated by functional category (account-path Group segment) with server-side multi-currency conversion
+   * @param data The data for the request.
+   * @param data.region Region code for tenant context
+   * @param data.groupBy Grouping strategy
+   * @param data.period Time window (1m = current calendar month)
+   * @returns ExpensesByCategoryResponseDto Expenses retrieved successfully
+   * @throws ApiError
+   */
+  public static dashboardControllerGetExpenses(
+    data: DashboardControllerGetExpensesData
+  ): CancelablePromise<DashboardControllerGetExpensesResponse> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/{region}/dashboard/expenses',
+      path: {
+        region: data.region
+      },
+      query: {
+        groupBy: data.groupBy,
+        period: data.period
+      },
+      errors: {
+        400: 'Invalid groupBy or period',
+        401: 'User not authenticated'
+      }
+    });
+  }
 }
 
 export class InvestmentService {
@@ -3341,6 +3564,42 @@ export class ReportingService {
     });
   }
 
+  /**
+   * Get cash-flow trends
+   *
+   * Monthly income / expense / netSavings over a fixed N-month window
+   * (current month + N−1 prior). Missing months are zero-filled (flow metric).
+   *
+   * **Parameters:**
+   * - `period`: 1m | 3m | 6m | 1y (default 6m)
+   * - `granularity`: accepted for API symmetry; v1 returns month buckets
+   *
+   * @param data The data for the request.
+   * @param data.region Region code for tenant context
+   * @param data.period Time period
+   * @param data.granularity Data granularity (accepted for API symmetry; v1 returns month buckets)
+   * @returns CashFlowTrendsResponseDto Cash-flow trends retrieved successfully
+   * @throws ApiError
+   */
+  public static reportingControllerGetCashFlowTrends(
+    data: ReportingControllerGetCashFlowTrendsData
+  ): CancelablePromise<ReportingControllerGetCashFlowTrendsResponse> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/{region}/reporting/cash-flow/trends',
+      path: {
+        region: data.region
+      },
+      query: {
+        period: data.period,
+        granularity: data.granularity
+      },
+      errors: {
+        401: 'User not authenticated'
+      }
+    });
+  }
+
   /**
    * Generate portfolio snapshot
    *