@firela/api-types 0.0.0-canary.feeae929 → 0.0.0-canary.ffdf0021

package/src/generated/types.gen.ts

@@ -595,7 +595,7 @@ export type PostingResponseDto = {
    */
   account: string;
   /**
-   * Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.
+   * Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.
    */
   units?: string;
   /**
@@ -830,7 +830,7 @@ export type PostingDetailDto = {
    */
   account: string;
   /**
-   * Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.
+   * Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.
    */
   units?: string;
   /**
@@ -976,6 +976,101 @@ export type flag2 =
  */
 export type status2 = 'ACTIVE' | 'VOIDED' | 'SUPERSEDED';
 
+export type TransactionListItemDto = {
+  /**
+   * Transaction ID
+   */
+  id: string;
+  /**
+   * Transaction date
+   */
+  date: string;
+  /**
+   * Transaction flag
+   */
+  flag?:
+    | 'CLEARED'
+    | 'PENDING'
+    | 'PADDING'
+    | 'SUMMARIZE'
+    | 'TRANSFER'
+    | 'CONVERSIONS';
+  /**
+   * Custom flag (if not using standard flags)
+   */
+  customFlag?: string;
+  /**
+   * Payee name
+   */
+  payee?: string;
+  /**
+   * Transaction narration
+   */
+  narration: string;
+  /**
+   * Transaction tags
+   */
+  tags: Array<string>;
+  /**
+   * Transaction links
+   */
+  links: Array<string>;
+  /**
+   * Transaction metadata
+   */
+  meta?: {
+    [key: string]: unknown;
+  };
+  /**
+   * Transaction status
+   */
+  status: 'ACTIVE' | 'VOIDED' | 'SUPERSEDED';
+  /**
+   * Source type (free-form string from transaction metadata, e.g. import, api)
+   */
+  sourceType?: string;
+  /**
+   * Source platform (e.g., alipay, wechat)
+   */
+  sourcePlatform?: string;
+  /**
+   * Transaction postings
+   */
+  postings: Array<PostingDetailDto>;
+  /**
+   * Created at timestamp
+   */
+  createdAt: string;
+  /**
+   * Voided at timestamp (if voided)
+   */
+  voidedAt?: string;
+  /**
+   * User ID who voided this transaction
+   */
+  voidedBy?: string;
+  /**
+   * Correction reason (if voided or superseded)
+   */
+  correctionReason?: string;
+  /**
+   * ID of the transaction that supersedes this one (set when status=SUPERSEDED)
+   */
+  supersededBy?: string;
+  /**
+   * ID of the transaction this one corrected/replaced (back-link on the replacement)
+   */
+  originalTxn?: string;
+  /**
+   * Per-leg sign-normalized row amount for the category viewpoint (ADR-0126): each posting on the category account set contributes its unitsNumber with Income-root legs negated and Expenses-root legs identity. Positive under normal booking but NOT clamped (explicit negative expense legs and net-flip refund months stay negative). Omitted outside the category viewpoint.
+   */
+  viewpointAmount?: string;
+  /**
+   * Currency of viewpointAmount. A row spanning multiple currencies takes the largest-magnitude currency group (known simplification, ADR-0126). Omitted outside the category viewpoint.
+   */
+  viewpointCurrency?: string;
+};
+
 export type BalanceByCurrencyDto = {
   /**
    * ISO 4217 currency code
@@ -1004,7 +1099,7 @@ export type ExchangeRateWarningDto = {
 
 export type TransactionListSummaryDto = {
   /**
-   * Partial converted total in base currency (rated currencies only, raw Beancount sign). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.
+   * Partial converted total in base currency (rated currencies only). Sign by viewpoint (ADR-0126): account viewpoint keeps the raw Beancount sign (income negative); category viewpoint is per-leg sign-normalized (Income legs negated, Expenses legs identity — positive under normal booking, not clamped). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.
    */
   totalAmount: string;
   /**
@@ -1021,11 +1116,32 @@ export type TransactionListSummaryDto = {
   warnings?: Array<ExchangeRateWarningDto>;
 };
 
+export type TransactionListViewpointDto = {
+  /**
+   * Viewpoint type (only category drill-down carries a viewpoint today)
+   */
+  type: 'category';
+  /**
+   * Flow root the category account set is restricted to
+   */
+  flow: 'income' | 'expense';
+};
+
+/**
+ * Viewpoint type (only category drill-down carries a viewpoint today)
+ */
+export type type2 = 'category';
+
+/**
+ * Flow root the category account set is restricted to
+ */
+export type flow = 'income' | 'expense';
+
 export type TransactionListResponseDto = {
   /**
    * List of transactions
    */
-  data: Array<TransactionDetailDto>;
+  data: Array<TransactionListItemDto>;
   /**
    * Total count of matching transactions
    */
@@ -1042,6 +1158,10 @@ export type TransactionListResponseDto = {
    * Amount summary for the full filtered set (#514). Present only when the request has a single account OR category viewpoint; omitted for search-only / plain-list / dual-perspective requests.
    */
   summary?: TransactionListSummaryDto;
+  /**
+   * Viewpoint metadata (ADR-0126). Present only for a single category filter (category + flow, no accountId); dual-perspective requests are viewpoint-less (raw signs, no viewpointAmount).
+   */
+  viewpoint?: TransactionListViewpointDto;
 };
 
 export type TagSuggestionDto = {
@@ -1253,7 +1373,7 @@ export type ReviewSummaryDto = {
 /**
  * Review type
  */
-export type type2 =
+export type type3 =
   | 'DUPLICATE'
   | 'RULE_MATCH'
   | 'PAYEE_MATCH'
@@ -3016,6 +3136,32 @@ export type DeleteOwnUserDto = {
   accessToken: string;
 };
 
+export type UserSettingsResponseDto = {
+  /**
+   * Base currency (ISO 4217) for net-worth/report aggregation. Independent of region (ADR-0006).
+   */
+  baseCurrency: string | null;
+};
+
+export type UserResponseDto = {
+  /**
+   * User ID
+   */
+  id: string;
+  /**
+   * Assigned user role
+   */
+  role: string;
+  /**
+   * Permission strings
+   */
+  permissions: Array<string>;
+  /**
+   * User settings
+   */
+  settings: UserSettingsResponseDto;
+};
+
 export type SignupDto = {
   /**
    * Cloudflare Turnstile verification token (optional when Turnstile disabled)
@@ -3502,6 +3648,57 @@ export type TestRuleResponseDto = {
   };
 };
 
+export type CategoryCatalogEntryDto = {
+  /**
+   * Category slug (single source-of-truth)
+   */
+  slug: string;
+  /**
+   * Display scenario group (maps to frontend picker _scenario)
+   */
+  scenario:
+    | 'expense'
+    | 'income'
+    | 'investment'
+    | 'banking'
+    | 'transfer'
+    | 'payment';
+  /**
+   * Lucide icon name
+   */
+  icon: string;
+  /**
+   * Applicable regions ('*' = all, 'cn' = CN-only)
+   */
+  regions: Array<string>;
+};
+
+/**
+ * Display scenario group (maps to frontend picker _scenario)
+ */
+export type scenario =
+  | 'expense'
+  | 'income'
+  | 'investment'
+  | 'banking'
+  | 'transfer'
+  | 'payment';
+
+export type CategoryCatalogListResponseDto = {
+  /**
+   * Category entries (region-scoped, query-filtered)
+   */
+  items: Array<CategoryCatalogEntryDto>;
+  /**
+   * Total category entries for the region (before query filtering)
+   */
+  total: number;
+  /**
+   * Region code
+   */
+  region: string;
+};
+
 export type CreateBeanEventDto = {
   /**
    * Life event date (ISO 8601)
@@ -4183,11 +4380,88 @@ export type ParserTelemetryReportDto = unknown;
 
 export type UncoveredFormatMissDto = unknown;
 
+export type ClientParsedDataDto = {
+  /**
+   * Transaction amount
+   */
+  amount?: number;
+  /**
+   * Currency code
+   */
+  currency?: string;
+  /**
+   * Transaction date (ISO 8601)
+   */
+  date?: string;
+  /**
+   * Payee/merchant name
+   */
+  payee?: string;
+  /**
+   * Transaction narration
+   */
+  narration?: string;
+  /**
+   * Category slug
+   */
+  category?: string;
+  /**
+   * Income type
+   */
+  incomeType?: string;
+  /**
+   * Income source
+   */
+  incomeSource?: string;
+  /**
+   * Security symbol code (e.g., 600519, AAPL)
+   */
+  symbol?: string;
+  /**
+   * Quantity of shares/units
+   */
+  quantity?: number;
+  /**
+   * Unit price per share/unit
+   */
+  price?: number;
+  /**
+   * Investment action
+   */
+  investmentAction?: 'buy' | 'sell';
+  /**
+   * Payment source: asset (default) or liability (credit card)
+   */
+  paymentSource?: 'asset' | 'liability';
+  /**
+   * Liability account hint (CreditCard/Huabei/Baitiao)
+   */
+  liabilityHint?: string;
+  /**
+   * Display-only warning from the prior response; accepted but ignored.
+   */
+  warning?: string;
+};
+
+/**
+ * Investment action
+ */
+export type investmentAction = 'buy' | 'sell';
+
+/**
+ * Payment source: asset (default) or liability (credit card)
+ */
+export type paymentSource = 'asset' | 'liability';
+
 export type ProcessNlpDto = {
   /**
-   * Natural language text describing a transaction (Chinese)
+   * Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.
+   */
+  message?: string;
+  /**
+   * Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.
    */
-  message: string;
+  confirm?: boolean;
   /**
    * Session ID for multi-turn conversation (auto-generated if not provided)
    */
@@ -4195,9 +4469,7 @@ export type ProcessNlpDto = {
   /**
    * Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.
    */
-  parsedData?: {
-    [key: string]: unknown;
-  };
+  parsedData?: ClientParsedDataDto;
   /**
    * confirm_rule echo-back: rule id selected from the prior confirm_rule response (matchedRule.id or alternatives[i].ruleId). Applied directly when the session is confirming_rule — no NL re-parse.
    */
@@ -4302,16 +4574,6 @@ export type NlpParsedDataDto = {
   warning?: string;
 };
 
-/**
- * Investment action
- */
-export type investmentAction = 'buy' | 'sell';
-
-/**
- * Payment source: asset (default) or liability (credit card)
- */
-export type paymentSource = 'asset' | 'liability';
-
 export type NlpSourceTransactionDto = {
   /**
    * Transaction date (ISO format)
@@ -4639,7 +4901,12 @@ export type NlpResponseDto = {
   /**
    * Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.
    */
-  assetSubType?: 'transfer' | 'banking' | 'investment';
+  assetSubType?:
+    | 'transfer'
+    | 'banking'
+    | 'investment'
+    | 'lend'
+    | 'lend_collect';
   /**
    * Liability sub-type (only present when intent is "liability"). borrow: borrowing money (Liabilities → Assets), repay: repaying debt (Assets → Liabilities).
    */
@@ -4756,7 +5023,12 @@ export type intent = 'expense' | 'asset' | 'income' | 'liability' | 'equity';
 /**
  * Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.
  */
-export type assetSubType = 'transfer' | 'banking' | 'investment';
+export type assetSubType =
+  | 'transfer'
+  | 'banking'
+  | 'investment'
+  | 'lend'
+  | 'lend_collect';
 
 /**
  * Liability sub-type (only present when intent is "liability"). borrow: borrowing money (Liabilities → Assets), repay: repaying debt (Assets → Liabilities).
@@ -4797,13 +5069,21 @@ export type PlatformListItemDto = {
    */
   canonical: string;
   /**
-   * Suggested path segment — canonical with first char uppercased (ACC_COMP_NAME_RE)
+   * Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")
    */
   suggestedSegment: string;
   /**
    * Logo URL
    */
   logoUrl: string | null;
+  /**
+   * ISO 3166-1 alpha-2 (UPPERCASE); null = global platform
+   */
+  countryCode: string | null;
+  /**
+   * Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.
+   */
+  category: string | null;
   /**
    * Whether user has accounts using this platform
    */
@@ -4813,7 +5093,7 @@ export type PlatformListItemDto = {
 /**
  * Platform type
  */
-export type type3 =
+export type type4 =
   | 'BANK'
   | 'BROKERAGE'
   | 'CRYPTO_EXCHANGE'
@@ -4847,13 +5127,21 @@ export type PlatformMatchResultDto = {
     | 'INSURANCE'
     | 'OTHER';
   /**
-   * Suggested path segment — canonical, already in ACCOUNT_RE format
+   * Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")
    */
   suggestedSegment: string;
   /**
    * Logo URL
    */
   logoUrl: string | null;
+  /**
+   * ISO 3166-1 alpha-2 (UPPERCASE); null = global platform
+   */
+  countryCode: string | null;
+  /**
+   * Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.
+   */
+  category: string | null;
   /**
    * How this row matched: 'exact' > 'prefix' > 'substring'
    */
@@ -5637,7 +5925,7 @@ export type HoldingPnlWarningDto = {
 /**
  * Warning type
  */
-export type type4 =
+export type type5 =
   | 'MISSING_COST_FX_RATE'
   | 'MISSING_MARKET_FX_RATE'
   | 'MISSING_SALE_PRICE'
@@ -5676,6 +5964,123 @@ export type AnonymousLoginResponseDto = {
   authToken: string;
 };
 
+export type ParserContributionMetaDto = {
+  /**
+   * Institution slug (lowercase kebab-case)
+   */
+  institution: string;
+  region:
+    | 'cn'
+    | 'us'
+    | 'de'
+    | 'fr'
+    | 'gb'
+    | 'hk'
+    | 'jp'
+    | 'sg'
+    | 'au'
+    | 'ca'
+    | 'other';
+  accountType: 'checking' | 'savings' | 'credit' | 'debit' | 'investment';
+  format: 'csv' | 'xlsx' | 'pdf' | 'ofx' | 'qif';
+  institutionDisplayName?: string;
+  encoding?: string;
+  /**
+   * CSV delimiter character: ",", ";", "\t" or "|"
+   */
+  delimiter?: string;
+  /**
+   * Header row count; the client omits the field when it is 1
+   */
+  headerRows?: number;
+  notes?: string;
+};
+
+export type region =
+  | 'cn'
+  | 'us'
+  | 'de'
+  | 'fr'
+  | 'gb'
+  | 'hk'
+  | 'jp'
+  | 'sg'
+  | 'au'
+  | 'ca'
+  | 'other';
+
+export type accountType =
+  | 'checking'
+  | 'savings'
+  | 'credit'
+  | 'debit'
+  | 'investment';
+
+export type format = 'csv' | 'xlsx' | 'pdf' | 'ofx' | 'qif';
+
+export type ParserContributionSamplesDto = {
+  /**
+   * Client-sanitized sample rows (key = column name, value = cell)
+   */
+  rows: Array<{
+    [key: string]: unknown;
+  }>;
+  rawHeaders?: Array<string>;
+};
+
+export type FieldHintDto = {
+  columnName: string;
+  /**
+   * Date format, e.g. yyyy-MM-dd HH:mm
+   */
+  format?: string;
+  signConvention?: 'negative-expense' | 'positive-expense' | 'separate-columns';
+  creditColumn?: string;
+  debitColumn?: string;
+};
+
+export type signConvention =
+  | 'negative-expense'
+  | 'positive-expense'
+  | 'separate-columns';
+
+export type ParserContributionFieldHintsDto = {
+  date: FieldHintDto;
+  amount: FieldHintDto;
+  description?: FieldHintDto;
+  balance?: FieldHintDto;
+  payee?: FieldHintDto;
+  reference?: FieldHintDto;
+  category?: FieldHintDto;
+};
+
+export type ExpectedTransactionDto = {
+  date: string;
+  amount: number;
+  description: string;
+  payee?: string;
+  category?: string;
+};
+
+export type ParserContributionExamplesDto = {
+  expectedTransactions: Array<ExpectedTransactionDto>;
+};
+
+export type ParserContributionRequestDto = {
+  meta: ParserContributionMetaDto;
+  samples: ParserContributionSamplesDto;
+  fieldHints: ParserContributionFieldHintsDto;
+  /**
+   * Omitted entirely by the client when empty
+   */
+  examples?: ParserContributionExamplesDto;
+};
+
+export type ParserContributionRelayResponseDto = {
+  issueUrl: string;
+  issueNumber: number;
+};
+
 export type SymbolSearchResultDto = {
   symbol: string;
   name?: {
@@ -6291,7 +6696,7 @@ export type TransactionControllerListData = {
    */
   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
+   * Filter by ADR-0075 functional category (Group segment); matches any posting to an account whose derived Group segment equals this value. Must be accompanied by flow (ADR-0126).
    */
   category?: string;
   /**
@@ -6302,6 +6707,10 @@ export type TransactionControllerListData = {
    * Filter by end date (inclusive), format: YYYY-MM-DD
    */
   dateTo?: string;
+  /**
+   * Required when category is present (400 otherwise) and vice versa (ADR-0126). Restricts the category account set to the flow root (income → Income:, expense → Expenses:) and drives the per-leg sign normalization of row viewpointAmount and the summary. OpenAPI cannot express conditional requiredness — the pairing is enforced at runtime.
+   */
+  flow?: 'income' | 'expense';
   /**
    * Number of items per page (1-100, default: 20)
    */
@@ -8421,7 +8830,7 @@ export type UserControllerGetUserData = {
   acceptLanguage: string;
 };
 
-export type UserControllerGetUserResponse = unknown;
+export type UserControllerGetUserResponse = UserResponseDto;
 
 export type UserControllerSignupUserData = {
   requestBody: SignupDto;
@@ -8893,6 +9302,55 @@ export type TransactionRuleControllerTestData = {
 
 export type TransactionRuleControllerTestResponse = TestRuleResponseDto;
 
+export type CategoryCatalogControllerListData = {
+  /**
+   * Region code for tenant context
+   */
+  region:
+    | 'ad'
+    | 'ae'
+    | 'af'
+    | 'ag'
+    | 'al'
+    | 'am'
+    | 'ao'
+    | 'au'
+    | 'br'
+    | 'ca'
+    | 'cn'
+    | 'de'
+    | 'dz'
+    | 'es'
+    | 'fr'
+    | 'gb'
+    | 'hk'
+    | 'in'
+    | 'it'
+    | 'jp'
+    | 'kr'
+    | 'nl'
+    | 'sg'
+    | 'tw'
+    | 'us';
+  /**
+   * Filter by routeBearing (entity-router route() consumes it)
+   */
+  routeBearing?: boolean;
+  /**
+   * Filter by scenario
+   */
+  scenario?:
+    | 'expense'
+    | 'income'
+    | 'investment'
+    | 'banking'
+    | 'transfer'
+    | 'payment';
+};
+
+export type CategoryCatalogControllerListResponse =
+  CategoryCatalogListResponseDto;
+
 export type EventControllerCreateData = {
   /**
    * Region code for tenant context (decorative for life events)
@@ -10056,6 +10514,13 @@ export type PlatformControllerCreateData = {
 
 export type PlatformControllerCreateResponse = unknown;
 
+export type PlatformControllerGetPlatformListData = {
+  /**
+   * Region code (ISO 3166-1 alpha-2) that biases within-type-bucket ordering (local-region platforms first). Case-insensitive — stored/compared UPPERCASE ("cn" == "CN").
+   */
+  region?: string;
+};
+
 export type PlatformControllerGetPlatformListResponse =
   Array<PlatformListItemDto>;
 
@@ -10065,7 +10530,7 @@ export type PlatformControllerMatchPlatformsData = {
    */
   q: string;
   /**
-   * Region code for category override lookup
+   * Region code (ISO 3166-1 alpha-2) that biases within-tier ordering (local-region platforms first); also the intended categoryOverrides key. Case-insensitive — stored/compared UPPERCASE ("cn" == "CN").
    */
   region?: string;
 };
@@ -10321,6 +10786,42 @@ export type AuthControllerAccessTokenLoginData = {
 
 export type AuthControllerAccessTokenLoginResponse = AnonymousLoginResponseDto;
 
+export type ParserContributionControllerCreateData = {
+  /**
+   * Region code for tenant context (routing only; the institution region rides in the payload meta)
+   */
+  region:
+    | 'ad'
+    | 'ae'
+    | 'af'
+    | 'ag'
+    | 'al'
+    | 'am'
+    | 'ao'
+    | 'au'
+    | 'br'
+    | 'ca'
+    | 'cn'
+    | 'de'
+    | 'dz'
+    | 'es'
+    | 'fr'
+    | 'gb'
+    | 'hk'
+    | 'in'
+    | 'it'
+    | 'jp'
+    | 'kr'
+    | 'nl'
+    | 'sg'
+    | 'tw'
+    | 'us';
+  requestBody: ParserContributionRequestDto;
+};
+
+export type ParserContributionControllerCreateResponse =
+  ParserContributionRelayResponseDto;
+
 export type CacheControllerFlushCacheResponse = unknown;
 
 export type ExchangeRateControllerGetExchangeRateData = {
@@ -11547,7 +12048,7 @@ export type $OpenApiTs = {
         /**
          * User retrieved successfully
          */
-        200: unknown;
+        200: UserResponseDto;
       };
     };
     post: {
@@ -11921,6 +12422,17 @@ export type $OpenApiTs = {
       };
     };
   };
+  '/api/v1/{region}/bean/categories': {
+    get: {
+      req: CategoryCatalogControllerListData;
+      res: {
+        /**
+         * Category catalog retrieved successfully
+         */
+        200: CategoryCatalogListResponseDto;
+      };
+    };
+  };
   '/api/v1/{region}/bean/events': {
     post: {
       req: EventControllerCreateData;
@@ -12460,6 +12972,7 @@ export type $OpenApiTs = {
   };
   '/api/v1/bean/platforms/list': {
     get: {
+      req: PlatformControllerGetPlatformListData;
       res: {
         /**
          * List of platforms with user binding status
@@ -12626,6 +13139,37 @@ export type $OpenApiTs = {
       };
     };
   };
+  '/api/v1/{region}/community/parser-contributions': {
+    post: {
+      req: ParserContributionControllerCreateData;
+      res: {
+        /**
+         * Issue created by the bot
+         */
+        201: ParserContributionRelayResponseDto;
+        /**
+         * Unauthorized
+         */
+        401: ApiProblemResponseDto;
+        /**
+         * Validation failed (institution slug, empty samples, row/cell size limits)
+         */
+        422: ApiProblemResponseDto;
+        /**
+         * Rate limited (5 submissions per user per hour)
+         */
+        429: ApiProblemResponseDto;
+        /**
+         * Relay not configured on this deployment — clients fall back to the clipboard flow
+         */
+        501: ApiProblemResponseDto;
+        /**
+         * GitHub bot failure (upstream), safe to retry
+         */
+        502: ApiProblemResponseDto;
+      };
+    };
+  };
   '/api/v1/cache/flush': {
     post: {
       res: {