@firela/api-types 0.0.0-canary.688167dd → 0.0.0-canary.69a6df79

package/src/generated/schemas.gen.ts

@@ -124,6 +124,8 @@ export const $AccountResponseDto = {
         'STUDENT_LOAN',
         'CREDIT_CARD',
         'PERSONAL_LOAN',
+        'ACCOUNTS_PAYABLE',
+        'TAX_PAYABLE',
         'OTHER'
       ],
       nullable: true,
@@ -395,9 +397,47 @@ export const $AccountStandardResponseDto = {
       type: 'string',
       description: 'Icon identifier for UI display',
       example: 'bank-icbc'
+    },
+    productCategory: {
+      type: 'string',
+      description:
+        'Onboarding product category (coarse grouping derived from assetSubClass)',
+      enum: [
+        'cash',
+        'investment',
+        'credit_card',
+        'loan',
+        'payable_tax',
+        'other'
+      ],
+      example: 'investment'
+    },
+    assetClass: {
+      type: 'string',
+      description:
+        'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
+      enum: [
+        'LIQUIDITY',
+        'EQUITY',
+        'FIXED_INCOME',
+        'PRECIOUS_METALS',
+        'COMMODITY',
+        'INSURANCE',
+        'ALTERNATIVE_INVESTMENT',
+        'PERSONAL_ASSETS',
+        'LIABILITY',
+        'REAL_ESTATE',
+        'INDEX'
+      ]
+    },
+    assetSubClass: {
+      type: 'string',
+      description:
+        'Asset sub-class (product type, derived at read time from classification rules)',
+      example: 'STOCK'
     }
   },
-  required: ['path', 'type', 'description', 'tags', 'icon']
+  required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
 } as const;
 
 export const $AccountStandardListResponseDto = {
@@ -736,7 +776,7 @@ export const $PostingResponseDto = {
     units: {
       type: 'string',
       description:
-        '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.',
       example: '100.50'
     },
     currency: {
@@ -1102,7 +1142,7 @@ export const $PostingDetailDto = {
     units: {
       type: 'string',
       description:
-        '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.',
       example: '100.50'
     },
     currency: {
@@ -1286,6 +1326,147 @@ export const $TransactionDetailDto = {
   ]
 } as const;
 
+export const $TransactionListItemDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Transaction ID',
+      example: 'clh1234567890abcdef'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date',
+      example: '2024-11-28'
+    },
+    flag: {
+      type: 'string',
+      description: 'Transaction flag',
+      enum: [
+        'CLEARED',
+        'PENDING',
+        'PADDING',
+        'SUMMARIZE',
+        'TRANSFER',
+        'CONVERSIONS'
+      ],
+      example: 'CLEARED'
+    },
+    customFlag: {
+      type: 'string',
+      description: 'Custom flag (if not using standard flags)',
+      example: 'R'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration',
+      example: 'Grocery shopping'
+    },
+    tags: {
+      description: 'Transaction tags',
+      example: ['groceries'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    links: {
+      description: 'Transaction links',
+      example: ['invoice-2024-001'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction metadata'
+    },
+    status: {
+      type: 'string',
+      description: 'Transaction status',
+      enum: ['ACTIVE', 'VOIDED', 'SUPERSEDED'],
+      example: 'ACTIVE'
+    },
+    sourceType: {
+      type: 'string',
+      description:
+        'Source type (free-form string from transaction metadata, e.g. import, api)'
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)',
+      example: 'alipay'
+    },
+    postings: {
+      description: 'Transaction postings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PostingDetailDto'
+      }
+    },
+    createdAt: {
+      type: 'string',
+      description: 'Created at timestamp',
+      example: '2024-11-28T10:30:00.000Z'
+    },
+    voidedAt: {
+      type: 'string',
+      description: 'Voided at timestamp (if voided)',
+      example: '2024-11-29T15:00:00.000Z'
+    },
+    voidedBy: {
+      type: 'string',
+      description: 'User ID who voided this transaction',
+      example: 'clh1234567890abcdef'
+    },
+    correctionReason: {
+      type: 'string',
+      description: 'Correction reason (if voided or superseded)',
+      example: 'Duplicate entry'
+    },
+    supersededBy: {
+      type: 'string',
+      description:
+        'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
+      example: 'clh1234567890abcdef'
+    },
+    originalTxn: {
+      type: 'string',
+      description:
+        'ID of the transaction this one corrected/replaced (back-link on the replacement)',
+      example: 'clh1234567890abcdef'
+    },
+    viewpointAmount: {
+      type: 'string',
+      description:
+        '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.',
+      example: '10000.00'
+    },
+    viewpointCurrency: {
+      type: 'string',
+      description:
+        'Currency of viewpointAmount. A row spanning multiple currencies takes the largest-magnitude currency group (known simplification, ADR-0126).',
+      example: 'CNY'
+    }
+  },
+  required: [
+    'id',
+    'date',
+    'narration',
+    'tags',
+    'links',
+    'status',
+    'postings',
+    'createdAt'
+  ]
+} as const;
+
 export const $BalanceByCurrencyDto = {
   type: 'object',
   properties: {
@@ -1331,7 +1512,7 @@ export const $TransactionListSummaryDto = {
     totalAmount: {
       type: 'string',
       description:
-        '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.',
       example: '-6000.00'
     },
     currency: {
@@ -1357,6 +1538,26 @@ export const $TransactionListSummaryDto = {
   required: ['totalAmount', 'currency', 'balanceByCurrency']
 } as const;
 
+export const $TransactionListViewpointDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description:
+        'Viewpoint type (only category drill-down carries a viewpoint today)',
+      enum: ['category'],
+      example: 'category'
+    },
+    flow: {
+      type: 'string',
+      description: 'Flow root the category account set is restricted to',
+      enum: ['income', 'expense'],
+      example: 'expense'
+    }
+  },
+  required: ['type', 'flow']
+} as const;
+
 export const $TransactionListResponseDto = {
   type: 'object',
   properties: {
@@ -1364,7 +1565,7 @@ export const $TransactionListResponseDto = {
       description: 'List of transactions',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/TransactionDetailDto'
+        $ref: '#/components/schemas/TransactionListItemDto'
       }
     },
     total: {
@@ -1390,6 +1591,15 @@ export const $TransactionListResponseDto = {
           $ref: '#/components/schemas/TransactionListSummaryDto'
         }
       ]
+    },
+    viewpoint: {
+      description:
+        '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).',
+      allOf: [
+        {
+          $ref: '#/components/schemas/TransactionListViewpointDto'
+        }
+      ]
     }
   },
   required: ['data', 'total', 'limit', 'offset']
@@ -4083,6 +4293,50 @@ export const $DeleteOwnUserDto = {
   required: ['accessToken']
 } as const;
 
+export const $UserSettingsResponseDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description:
+        'Base currency (ISO 4217) for net-worth/report aggregation. Independent of region (ADR-0006).',
+      example: 'USD',
+      nullable: true
+    }
+  },
+  required: ['baseCurrency']
+} as const;
+
+export const $UserResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'User ID'
+    },
+    role: {
+      type: 'string',
+      description: 'Assigned user role'
+    },
+    permissions: {
+      description: 'Permission strings',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    settings: {
+      description: 'User settings',
+      allOf: [
+        {
+          $ref: '#/components/schemas/UserSettingsResponseDto'
+        }
+      ]
+    }
+  },
+  required: ['id', 'role', 'permissions', 'settings']
+} as const;
+
 export const $SignupDto = {
   type: 'object',
   properties: {
@@ -4888,6 +5142,69 @@ export const $TestRuleResponseDto = {
   required: ['ruleId', 'matches', 'confidence', 'matchDetails']
 } as const;
 
+export const $CategoryCatalogEntryDto = {
+  type: 'object',
+  properties: {
+    slug: {
+      type: 'string',
+      description: 'Category slug (single source-of-truth)',
+      example: 'food'
+    },
+    scenario: {
+      type: 'string',
+      description: 'Display scenario group (maps to frontend picker _scenario)',
+      enum: [
+        'expense',
+        'income',
+        'investment',
+        'banking',
+        'transfer',
+        'payment'
+      ],
+      example: 'expense'
+    },
+    icon: {
+      type: 'string',
+      description: 'Lucide icon name',
+      example: 'utensils'
+    },
+    regions: {
+      description: "Applicable regions ('*' = all, 'cn' = CN-only)",
+      example: ['*'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['slug', 'scenario', 'icon', 'regions']
+} as const;
+
+export const $CategoryCatalogListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'Category entries (region-scoped, query-filtered)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CategoryCatalogEntryDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description:
+        'Total category entries for the region (before query filtering)',
+      example: 30
+    },
+    region: {
+      type: 'string',
+      description: 'Region code',
+      example: 'cn'
+    }
+  },
+  required: ['items', 'total', 'region']
+} as const;
+
 export const $CreateBeanEventDto = {
   type: 'object',
   properties: {
@@ -5630,7 +5947,8 @@ export const $UpdateMapperDefaultsDto = {
       type: 'string',
       description: 'Source account for transactions (Beancount format)',
       example: 'Assets:CN:Alipay:Balance',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
     currency: {
       type: 'string',
@@ -5644,13 +5962,15 @@ export const $UpdateMapperDefaultsDto = {
       type: 'string',
       description: 'Default expense account (optional)',
       example: 'Expenses:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
     incomeAccount: {
       type: 'string',
       description: 'Default income account (optional)',
       example: 'Income:Unknown',
-      pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
+      pattern:
+        '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
     },
     methodAccountMapping: {
       type: 'object',
@@ -5707,12 +6027,14 @@ export const $ProviderSyncConfigDto = {
     },
     defaultExpenseAccount: {
       type: 'string',
-      description: 'Default expense account for the second posting',
+      description:
+        'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
       example: 'Expenses:Unknown'
     },
     defaultIncomeAccount: {
       type: 'string',
-      description: 'Default income account for the second posting',
+      description:
+        'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
       example: 'Income:Unknown'
     },
     filterPending: {
@@ -5727,12 +6049,7 @@ export const $ProviderSyncConfigDto = {
       example: 'acc_gocardless_001'
     }
   },
-  required: [
-    'sourceAccount',
-    'defaultCurrency',
-    'defaultExpenseAccount',
-    'defaultIncomeAccount'
-  ]
+  required: ['sourceAccount', 'defaultCurrency']
 } as const;
 
 export const $ProviderSyncDto = {
@@ -5942,15 +6259,105 @@ export const $UncoveredFormatMissDto = {
   properties: {}
 } as const;
 
+export const $ClientParsedDataDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'number',
+      description: 'Transaction amount',
+      example: 35
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO 8601)',
+      example: '2026-08-15'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee/merchant name',
+      example: 'Starbucks'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    category: {
+      type: 'string',
+      description: 'Category slug',
+      example: 'food_restaurant'
+    },
+    incomeType: {
+      type: 'string',
+      description: 'Income type',
+      example: 'Salary'
+    },
+    incomeSource: {
+      type: 'string',
+      description: 'Income source',
+      example: 'Anthropic Inc.'
+    },
+    symbol: {
+      type: 'string',
+      description: 'Security symbol code (e.g., 600519, AAPL)',
+      example: 'AAPL'
+    },
+    quantity: {
+      type: 'number',
+      description: 'Quantity of shares/units',
+      example: 100
+    },
+    price: {
+      type: 'number',
+      description: 'Unit price per share/unit',
+      example: 1900
+    },
+    investmentAction: {
+      type: 'string',
+      description: 'Investment action',
+      enum: ['buy', 'sell'],
+      example: 'buy'
+    },
+    paymentSource: {
+      type: 'string',
+      description: 'Payment source: asset (default) or liability (credit card)',
+      enum: ['asset', 'liability'],
+      example: 'asset'
+    },
+    liabilityHint: {
+      type: 'string',
+      description: 'Liability account hint (CreditCard/Huabei/Baitiao)',
+      example: 'CreditCard'
+    },
+    warning: {
+      type: 'string',
+      description:
+        'Display-only warning from the prior response; accepted but ignored.',
+      example: 'Cross-currency settlement applies.'
+    }
+  }
+} as const;
+
 export const $ProcessNlpDto = {
   type: 'object',
   properties: {
     message: {
       type: 'string',
-      description: 'Natural language text describing a transaction (Chinese)',
-      example: 'yesterday Starbucks spent 35 yuan',
+      description:
+        'Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.',
+      example: 'Starbucks 35',
       maxLength: 500
     },
+    confirm: {
+      type: 'boolean',
+      description:
+        'Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.',
+      example: true
+    },
     sessionId: {
       type: 'string',
       description:
@@ -5958,14 +6365,18 @@ export const $ProcessNlpDto = {
       example: 'session_abc123'
     },
     parsedData: {
-      type: 'object',
       description:
         'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
       example: {
         amount: 35,
         currency: 'CNY',
         payee: 'Starbucks'
-      }
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/ClientParsedDataDto'
+        }
+      ]
     },
     selectedRuleId: {
       type: 'string',
@@ -5976,11 +6387,10 @@ export const $ProcessNlpDto = {
     selectedAccount: {
       type: 'string',
       description:
-        '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.',
       example: 'Expenses:Food:Coffee'
     }
-  },
-  required: ['message']
+  }
 } as const;
 
 export const $NlpTransactionInfoDto = {
@@ -6292,6 +6702,24 @@ export const $NlpRuleConfirmationDataDto = {
   ]
 } as const;
 
+export const $NlpAccountCandidateDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Canonical beancount account path (echo back on selection)',
+      example: 'Expenses:Food:Dining'
+    },
+    name: {
+      type: 'string',
+      description:
+        'Localized display name (ADR-0114 read-time projection, user locale)',
+      example: '餐饮'
+    }
+  },
+  required: ['path', 'name']
+} as const;
+
 export const $NlpAccountConfirmationDataDto = {
   type: 'object',
   properties: {
@@ -6307,10 +6735,11 @@ export const $NlpAccountConfirmationDataDto = {
       example: 'Expenses:Food:Drinks'
     },
     similarAccounts: {
-      description: 'Similar accounts for user selection',
+      description:
+        'Similar accounts for user selection (path + localized name, #680)',
       type: 'array',
       items: {
-        type: 'string'
+        $ref: '#/components/schemas/NlpAccountCandidateDto'
       }
     },
     errorMessage: {
@@ -6598,7 +7027,7 @@ export const $NlpResponseDto = {
       type: 'string',
       description:
         'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
-      enum: ['transfer', 'banking', 'investment'],
+      enum: ['transfer', 'banking', 'investment', 'lend', 'lend_collect'],
       example: 'investment'
     },
     liabilitySubType: {
@@ -6801,13 +7230,26 @@ export const $PlatformListItemDto = {
     suggestedSegment: {
       type: 'string',
       description:
-        '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")'
     },
     logoUrl: {
       type: 'string',
       description: 'Logo URL',
       nullable: true
     },
+    countryCode: {
+      type: 'string',
+      description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
+      example: 'CN',
+      nullable: true
+    },
+    category: {
+      type: 'string',
+      description:
+        'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
+      nullable: true,
+      example: 'DigitalWallet'
+    },
     isBound: {
       type: 'boolean',
       description: 'Whether user has accounts using this platform'
@@ -6821,6 +7263,8 @@ export const $PlatformListItemDto = {
     'canonical',
     'suggestedSegment',
     'logoUrl',
+    'countryCode',
+    'category',
     'isBound'
   ]
 } as const;
@@ -6856,13 +7300,26 @@ export const $PlatformMatchResultDto = {
     suggestedSegment: {
       type: 'string',
       description:
-        'Suggested path segment — canonical, already in ACCOUNT_RE format'
+        'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
     },
     logoUrl: {
       type: 'string',
       description: 'Logo URL',
       nullable: true
     },
+    countryCode: {
+      type: 'string',
+      description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
+      example: 'CN',
+      nullable: true
+    },
+    category: {
+      type: 'string',
+      description:
+        'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
+      nullable: true,
+      example: 'DigitalWallet'
+    },
     matchType: {
       type: 'string',
       description: "How this row matched: 'exact' > 'prefix' > 'substring'",
@@ -6876,6 +7333,8 @@ export const $PlatformMatchResultDto = {
     'type',
     'suggestedSegment',
     'logoUrl',
+    'countryCode',
+    'category',
     'matchType'
   ]
 } as const;
@@ -8125,6 +8584,216 @@ export const $AnonymousLoginResponseDto = {
   required: ['authToken']
 } as const;
 
+export const $ParserContributionMetaDto = {
+  type: 'object',
+  properties: {
+    institution: {
+      type: 'string',
+      description: 'Institution slug (lowercase kebab-case)',
+      pattern: '^[a-z0-9]+(-[a-z0-9]+)*$',
+      example: 'icbc'
+    },
+    region: {
+      type: 'string',
+      enum: [
+        'cn',
+        'us',
+        'de',
+        'fr',
+        'gb',
+        'hk',
+        'jp',
+        'sg',
+        'au',
+        'ca',
+        'other'
+      ]
+    },
+    accountType: {
+      type: 'string',
+      enum: ['checking', 'savings', 'credit', 'debit', 'investment']
+    },
+    format: {
+      type: 'string',
+      enum: ['csv', 'xlsx', 'pdf', 'ofx', 'qif']
+    },
+    institutionDisplayName: {
+      type: 'string',
+      example: '中国工商银行'
+    },
+    encoding: {
+      type: 'string',
+      example: 'utf-8'
+    },
+    delimiter: {
+      type: 'string',
+      description: 'CSV delimiter character: ",", ";", "\\t" or "|"'
+    },
+    headerRows: {
+      type: 'number',
+      default: 1,
+      description: 'Header row count; the client omits the field when it is 1'
+    },
+    notes: {
+      type: 'string',
+      maxLength: 2000
+    }
+  },
+  required: ['institution', 'region', 'accountType', 'format']
+} as const;
+
+export const $ParserContributionSamplesDto = {
+  type: 'object',
+  properties: {
+    rows: {
+      description:
+        'Client-sanitized sample rows (key = column name, value = cell)',
+      type: 'array',
+      items: {
+        type: 'object'
+      }
+    },
+    rawHeaders: {
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['rows']
+} as const;
+
+export const $FieldHintDto = {
+  type: 'object',
+  properties: {
+    columnName: {
+      type: 'string',
+      example: '交易日期'
+    },
+    format: {
+      type: 'string',
+      description: 'Date format, e.g. yyyy-MM-dd HH:mm',
+      example: 'yyyy-MM-dd'
+    },
+    signConvention: {
+      type: 'string',
+      enum: ['negative-expense', 'positive-expense', 'separate-columns']
+    },
+    creditColumn: {
+      type: 'string'
+    },
+    debitColumn: {
+      type: 'string'
+    }
+  },
+  required: ['columnName']
+} as const;
+
+export const $ParserContributionFieldHintsDto = {
+  type: 'object',
+  properties: {
+    date: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    amount: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    description: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    balance: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    payee: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    reference: {
+      $ref: '#/components/schemas/FieldHintDto'
+    },
+    category: {
+      $ref: '#/components/schemas/FieldHintDto'
+    }
+  },
+  required: ['date', 'amount']
+} as const;
+
+export const $ExpectedTransactionDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      example: '2026-08-01'
+    },
+    amount: {
+      type: 'number',
+      example: -45.5
+    },
+    description: {
+      type: 'string',
+      example: '星巴克-***店'
+    },
+    payee: {
+      type: 'string'
+    },
+    category: {
+      type: 'string'
+    }
+  },
+  required: ['date', 'amount', 'description']
+} as const;
+
+export const $ParserContributionExamplesDto = {
+  type: 'object',
+  properties: {
+    expectedTransactions: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExpectedTransactionDto'
+      }
+    }
+  },
+  required: ['expectedTransactions']
+} as const;
+
+export const $ParserContributionRequestDto = {
+  type: 'object',
+  properties: {
+    meta: {
+      $ref: '#/components/schemas/ParserContributionMetaDto'
+    },
+    samples: {
+      $ref: '#/components/schemas/ParserContributionSamplesDto'
+    },
+    fieldHints: {
+      $ref: '#/components/schemas/ParserContributionFieldHintsDto'
+    },
+    examples: {
+      description: 'Omitted entirely by the client when empty',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ParserContributionExamplesDto'
+        }
+      ]
+    }
+  },
+  required: ['meta', 'samples', 'fieldHints']
+} as const;
+
+export const $ParserContributionRelayResponseDto = {
+  type: 'object',
+  properties: {
+    issueUrl: {
+      type: 'string',
+      example: 'https://github.com/fire-zu/firela-vlt/issues/42'
+    },
+    issueNumber: {
+      type: 'number',
+      example: 42
+    }
+  },
+  required: ['issueUrl', 'issueNumber']
+} as const;
+
 export const $SymbolSearchResultDto = {
   type: 'object',
   properties: {