@firela/api-types 0.0.0-canary.8cbdced0 → 0.0.0-canary.9d0af796

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,
@@ -234,6 +246,8 @@ import type {
   PriceControllerBulkCreateResponse,
   ReportingControllerGetPortfolioTrendsData,
   ReportingControllerGetPortfolioTrendsResponse,
+  ReportingControllerGetCashFlowTrendsData,
+  ReportingControllerGetCashFlowTrendsResponse,
   ReportingControllerGenerateSnapshotData,
   ReportingControllerGenerateSnapshotResponse,
   ReportingControllerBackfillSnapshotsData,
@@ -257,10 +271,12 @@ import type {
 
 export class BeanAccountsService {
   /**
+   * Create a new account
+   * Creates a new account (Beancount Open directive)
    * @param data The data for the request.
    * @param data.region Region code for tenant context
    * @param data.requestBody
-   * @returns unknown
+   * @returns AccountResponseDto Account created successfully
    * @throws ApiError
    */
   public static accountControllerCreate(
@@ -273,7 +289,10 @@ export class BeanAccountsService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        409: 'Account already exists'
+      }
     });
   }
 
@@ -337,11 +356,13 @@ export class BeanAccountsService {
   }
 
   /**
+   * Update account
+   * Updates account metadata (path cannot be changed)
    * @param data The data for the request.
-   * @param data.id
+   * @param data.id Account UUID
    * @param data.region Region code for tenant context
    * @param data.requestBody
-   * @returns unknown
+   * @returns AccountResponseDto Account updated successfully
    * @throws ApiError
    */
   public static accountControllerUpdate(
@@ -355,15 +376,20 @@ export class BeanAccountsService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        404: 'Account not found'
+      }
     });
   }
 
   /**
+   * Delete account
+   * Deletes an account (only if no transactions)
    * @param data The data for the request.
-   * @param data.id
+   * @param data.id Account UUID
    * @param data.region Region code for tenant context
-   * @returns unknown
+   * @returns void Account deleted successfully
    * @throws ApiError
    */
   public static accountControllerDelete(
@@ -375,16 +401,22 @@ export class BeanAccountsService {
       path: {
         id: data.id,
         region: data.region
+      },
+      errors: {
+        404: 'Account not found',
+        409: 'Account has transactions and cannot be deleted'
       }
     });
   }
 
   /**
+   * Close account
+   * Closes an account (Beancount Close directive)
    * @param data The data for the request.
-   * @param data.id
+   * @param data.id Account UUID
    * @param data.region Region code for tenant context
    * @param data.requestBody
-   * @returns unknown
+   * @returns AccountResponseDto Account closed successfully
    * @throws ApiError
    */
   public static accountControllerClose(
@@ -398,16 +430,22 @@ export class BeanAccountsService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        400: 'Account is already closed',
+        404: 'Account not found'
+      }
     });
   }
 
   /**
+   * Reopen account
+   * Reopens a previously closed account
    * @param data The data for the request.
-   * @param data.id
+   * @param data.id Account UUID
    * @param data.region Region code for tenant context
    * @param data.requestBody
-   * @returns unknown
+   * @returns AccountResponseDto Account reopened successfully
    * @throws ApiError
    */
   public static accountControllerReopen(
@@ -421,7 +459,11 @@ export class BeanAccountsService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        400: 'Account is not closed',
+        404: 'Account not found'
+      }
     });
   }
 }
@@ -2432,6 +2474,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
@@ -2504,9 +2721,12 @@ export class BeanImportService {
   }
 
   /**
+   * Import a Beancount file in community format
+   * Upload a .beancount file to import. The system parses community-format paths, converts to internal format using category metadata, auto-creates accounts, and imports transactions with deduplication. Maximum file size: 50MB. Only 1 import per user at a time.
    * @param data The data for the request.
    * @param data.region Region code for tenant context
-   * @returns unknown
+   * @param data.formData Beancount file to import
+   * @returns unknown Beancount file imported successfully
    * @throws ApiError
    */
   public static fileImportControllerImportBeancount(
@@ -2517,6 +2737,11 @@ export class BeanImportService {
       url: '/api/v1/{region}/bean/import/beancount',
       path: {
         region: data.region
+      },
+      formData: data.formData,
+      mediaType: 'multipart/form-data',
+      errors: {
+        400: 'Bad request - invalid file or no file uploaded'
       }
     });
   }
@@ -2719,11 +2944,33 @@ export class BeanPlatformsService {
 
 export class ProviderSyncService {
   /**
+   * Sync transactions from financial data provider
+   *
+   * Accepts raw transactions from external financial data providers, transforms them to Beancount format, and processes them through the ingestion pipeline.
+   *
+   * **Supported Providers:**
+   * - **plaid**: Plaid API (US, Canada, Europe)
+   * - **teller**: Teller API (US)
+   * - **truelayer**: TrueLayer Open Banking (UK, Europe)
+   * - **gocardless**: GoCardless Bank Account Data (Europe)
+   * - **simplefin**: SimpleFIN (Self-hosted)
+   * - **yodlee**: Yodlee (Global)
+   * - **beancount-direct**: Beancount format transactions
+   * - **parsed-bill**: Client-side parsed bill transactions
+   *
+   * **Processing Flow:**
+   * 1. Transform raw data via provider adapter
+   * 2. Validate transaction format
+   * 3. Deduplicate using originalId
+   * 4. Classify using rule engine
+   * 5. Route low-confidence to Review Center
+   * 6. Persist validated transactions
+   *
    * @param data The data for the request.
-   * @param data.providerName
+   * @param data.providerName Provider name
    * @param data.region Region code for tenant context
    * @param data.requestBody
-   * @returns unknown
+   * @returns ProviderSyncResponseDto Sync completed successfully
    * @throws ApiError
    */
   public static providerSyncControllerSync(
@@ -2737,7 +2984,12 @@ export class ProviderSyncService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        400: 'Invalid request data',
+        401: 'Missing or invalid authentication',
+        404: 'Provider not supported'
+      }
     });
   }
 
@@ -2867,10 +3119,12 @@ export class ImportTelemetryService {
 
 export class BeanNlpService {
   /**
+   * Process natural language input
+   * Parse natural language text (Chinese/English) describing a transaction. Supports multi-turn dialogue for collecting missing information. When confidence < 0.75, returns "confirm" action requiring user verification. User can reply with confirmation words (确认/yes/ok) or provide corrections. Examples: "yesterday Starbucks spent 35 yuan", "today lunch 28 yuan", "spent $50 at Walmart"
    * @param data The data for the request.
    * @param data.region Region code for tenant context
-   * @param data.requestBody
-   * @returns unknown
+   * @param data.requestBody Natural language transaction input with optional session ID
+   * @returns NlpResponseDto NLP processing result - either created transaction or asking for more info
    * @throws ApiError
    */
   public static nlpControllerProcessNaturalLanguage(
@@ -2883,7 +3137,11 @@ export class BeanNlpService {
         region: data.region
       },
       body: data.requestBody,
-      mediaType: 'application/json'
+      mediaType: 'application/json',
+      errors: {
+        400: 'Invalid input',
+        401: 'Unauthorized'
+      }
     });
   }
 
@@ -3272,6 +3530,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
    *