@firela/api-types 0.0.0-canary.693e8bdf → 0.0.0-canary.69a6df79

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;
+  /**
+   * Row amount under the request viewpoint (ADR-0126). Category viewpoint (category + flow): per-leg sign-normalized sum over the category account set (Income-root legs negated, Expenses-root identity) — positive under normal booking but NOT clamped (explicit negative expense legs and net-flip refund months stay negative). No viewpoint (plain list / search, no accountId): wallet money-flow net = raw-sign sum over cost-less Assets/Liabilities legs (income positive, expenses negative, transfers net ~0); color cue is the wallet sign (net < 0 = wealth-decreasing). Status-orthogonal: audit views match too (ADR-0128 amount-as-matching-key). Omitted under the account viewpoint (incl. dual) and for rows with no wallet leg.
+   */
+  viewpointAmount?: string;
+  /**
+   * Currency of viewpointAmount. A row spanning multiple currencies takes the largest-magnitude currency group (known simplification, ADR-0126).
+   */
+  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'
@@ -4355,7 +4475,7 @@ export type ProcessNlpDto = {
    */
   selectedRuleId?: string;
   /**
-   * confirm_account echo-back: account path selected from the prior confirm_account response (suggestedAccount, similarAccounts[i], or a typed path). Applied directly when the session is confirming_account — no NL re-parse.
+   * confirm_account echo-back: account path selected from the prior confirm_account response (suggestedAccount, similarAccounts[i].path, or a typed path). Applied directly when the session is confirming_account — no NL re-parse.
    */
   selectedAccount?: string;
 };
@@ -4585,6 +4705,17 @@ export type NlpRuleConfirmationDataDto = {
   reasons: Array<string>;
 };
 
+export type NlpAccountCandidateDto = {
+  /**
+   * Canonical beancount account path (echo back on selection)
+   */
+  path: string;
+  /**
+   * Localized display name (ADR-0114 read-time projection, user locale)
+   */
+  name: string;
+};
+
 export type NlpAccountConfirmationDataDto = {
   /**
    * The invalid account name
@@ -4595,9 +4726,9 @@ export type NlpAccountConfirmationDataDto = {
    */
   suggestedAccount?: string;
   /**
-   * Similar accounts for user selection
+   * Similar accounts for user selection (path + localized name, #680)
    */
-  similarAccounts: Array<string>;
+  similarAccounts: Array<NlpAccountCandidateDto>;
   /**
    * Error message explaining the issue
    */
@@ -4973,7 +5104,7 @@ export type PlatformListItemDto = {
 /**
  * Platform type
  */
-export type type3 =
+export type type4 =
   | 'BANK'
   | 'BROKERAGE'
   | 'CRYPTO_EXCHANGE'
@@ -5805,7 +5936,7 @@ export type HoldingPnlWarningDto = {
 /**
  * Warning type
  */
-export type type4 =
+export type type5 =
   | 'MISSING_COST_FX_RATE'
   | 'MISSING_MARKET_FX_RATE'
   | 'MISSING_SALE_PRICE'
@@ -5844,6 +5975,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?: {
@@ -6459,7 +6707,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;
   /**
@@ -6470,6 +6718,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)
    */
@@ -6512,9 +6764,9 @@ export type TransactionControllerListData = {
    */
   search?: string;
   /**
-   * Filter by transaction status
+   * Filter by transaction status: single value, comma-separated multi-value (e.g. VOIDED,SUPERSEDED), or ALL to include audit rows. Defaults to ACTIVE-only (ADR-0128; previously unfiltered — breaking change).
    */
-  status?: 'ACTIVE' | 'VOIDED' | 'SUPERSEDED';
+  status?: 'ACTIVE' | 'VOIDED' | 'SUPERSEDED' | 'ALL';
 };
 
 export type TransactionControllerListResponse = TransactionListResponseDto;
@@ -10545,6 +10797,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 = {
@@ -12862,6 +13150,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: {