@firela/api-types 0.0.0-canary.52154bb3 → 0.0.0-canary.55cba54a

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/dist/index.d.mts +4104 -2796
  2. package/dist/index.d.ts +4104 -2796
  3. package/dist/index.js +33 -5
  4. package/dist/index.mjs +33 -5
  5. package/package.json +1 -1
  6. package/src/generated/schemas.gen.ts +2402 -1118
  7. package/src/generated/services.gen.ts +1339 -739
  8. package/src/generated/types.gen.ts +7332 -3197
package/src/generated/schemas.gen.ts CHANGED
@@ -6,18 +6,12 @@ export const $CreateAccountDto = {
6
6
  path: {
7
7
  type: 'string',
8
8
  description: 'Account path (hierarchical, colon-separated)',
9
- example: 'Assets:CN:Bank:ICBC:Checking'
10
- },
11
- displayName: {
12
- type: 'string',
13
- description:
14
- 'Display name to distinguish accounts at the same path (default: "")',
15
- example: '工资卡'
9
+ example: 'Assets:CN:ICBC:Checking'
16
10
  },
17
11
  openDate: {
18
12
  format: 'date-time',
19
13
  type: 'string',
20
- description: 'Account open date',
14
+ description: 'Account open date (server defaults to today)',
21
15
  example: '2024-01-01'
22
16
  },
23
17
  currencies: {
@@ -45,26 +39,22 @@ export const $CreateAccountDto = {
45
39
  templatePath: {
46
40
  type: 'string',
47
41
  description: 'Reference to account-standards template path',
48
- example: 'Assets:CN:Bank:ICBC:Checking'
42
+ example: 'Assets:CN:Checking'
49
43
  },
50
44
  isCustom: {
51
45
  type: 'boolean',
52
46
  description: 'Whether this is a custom (user-created) account',
53
47
  default: false
54
48
  },
55
- i18nKey: {
56
- type: 'string',
57
- description: 'i18n key for display name (overrides template)',
58
- example: 'account.custom.mybank'
59
- },
60
49
  icon: {
61
50
  type: 'string',
62
51
  description: 'Icon identifier (overrides template)',
63
52
  example: 'bank-custom'
64
53
  },
65
- openMeta: {
54
+ openDirectiveMeta: {
66
55
  type: 'object',
67
- description: 'Additional metadata',
56
+ description:
57
+ 'Open directive metadata (NOT an opening-balance amount — use the opening-balance endpoint)',
68
58
  example: {
69
59
  branch: 'Downtown',
70
60
  accountNumber: '1234'
@@ -76,7 +66,7 @@ export const $CreateAccountDto = {
76
66
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
77
67
  }
78
68
  },
79
- required: ['path', 'openDate']
69
+ required: ['path']
80
70
  } as const;
81
71
 
82
72
  export const $AccountResponseDto = {
@@ -90,13 +80,7 @@ export const $AccountResponseDto = {
90
80
  path: {
91
81
  type: 'string',
92
82
  description: 'Account path (hierarchical, colon-separated)',
93
- example: 'Assets:CN:Bank:ICBC:Checking'
94
- },
95
- displayName: {
96
- type: 'string',
97
- description:
98
- 'Display name distinguishing multiple accounts at the same path',
99
- example: '工资卡'
83
+ example: 'Assets:CN:ICBC:Checking'
100
84
  },
101
85
  type: {
102
86
  type: 'string',
@@ -104,6 +88,49 @@ export const $AccountResponseDto = {
104
88
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
105
89
  example: 'Assets'
106
90
  },
91
+ assetSubClass: {
92
+ type: 'string',
93
+ description:
94
+ 'Account-level asset sub-class (product type, e.g. STOCK/DEPOSIT/CREDIT_CARD/PERSONAL_LOAN). Computed from the account path via the asset-classifier (ADR-0077). Null for non-asset accounts (Income/Expenses/Equity) or unmatched paths.',
95
+ enum: [
96
+ 'DEPOSIT',
97
+ 'CASH',
98
+ 'MONEY_MARKET_FUND',
99
+ 'STOCK',
100
+ 'ETF',
101
+ 'MUTUAL_FUND',
102
+ 'EQUITY_COMPENSATION',
103
+ 'GOVERNMENT_BOND',
104
+ 'CORPORATE_BOND',
105
+ 'BOND_FUND',
106
+ 'PRIMARY_RESIDENCE',
107
+ 'INVESTMENT_PROPERTY',
108
+ 'REIT',
109
+ 'GOLD',
110
+ 'SILVER',
111
+ 'PRECIOUS_METAL',
112
+ 'PRECIOUS_METAL_FUND',
113
+ 'COMMODITY',
114
+ 'COMMODITY_FUND',
115
+ 'CRYPTOCURRENCY',
116
+ 'RETIREMENT_ACCOUNT',
117
+ 'HEALTH_ACCOUNT',
118
+ 'EDUCATION_ACCOUNT',
119
+ 'INSURANCE',
120
+ 'PRIVATE_EQUITY',
121
+ 'HEDGE_FUND',
122
+ 'COLLECTIBLES',
123
+ 'MORTGAGE',
124
+ 'STUDENT_LOAN',
125
+ 'CREDIT_CARD',
126
+ 'PERSONAL_LOAN',
127
+ 'ACCOUNTS_PAYABLE',
128
+ 'TAX_PAYABLE',
129
+ 'OTHER'
130
+ ],
131
+ nullable: true,
132
+ example: 'STOCK'
133
+ },
107
134
  status: {
108
135
  type: 'string',
109
136
  description: 'Account status',
@@ -145,26 +172,26 @@ export const $AccountResponseDto = {
145
172
  templatePath: {
146
173
  type: 'string',
147
174
  description: 'Template path reference',
148
- example: 'Assets:CN:Bank:ICBC:Checking'
175
+ example: 'Assets:CN:Checking'
149
176
  },
150
177
  isCustom: {
151
178
  type: 'boolean',
152
179
  description: 'Whether this is a custom (user-created) account',
153
180
  example: false
154
181
  },
155
- i18nKey: {
182
+ displayName: {
156
183
  type: 'string',
157
- description: 'i18n key for display name',
158
- example: 'account.assets.cn.bank.icbc.checking'
184
+ description: 'Localized display name (ADR-0114, read-time projection)',
185
+ example: 'Checking'
159
186
  },
160
187
  icon: {
161
188
  type: 'string',
162
189
  description: 'Icon identifier',
163
190
  example: 'bank-icbc'
164
191
  },
165
- openMeta: {
192
+ openDirectiveMeta: {
166
193
  type: 'object',
167
- description: 'Account metadata',
194
+ description: 'Open directive metadata (ADR-0115 Decision 9)',
168
195
  example: {
169
196
  branch: 'Downtown'
170
197
  }
@@ -192,7 +219,6 @@ export const $AccountResponseDto = {
192
219
  required: [
193
220
  'id',
194
221
  'path',
195
- 'displayName',
196
222
  'type',
197
223
  'status',
198
224
  'openDate',
@@ -225,11 +251,6 @@ export const $AccountListResponseDto = {
225
251
  export const $UpdateAccountDto = {
226
252
  type: 'object',
227
253
  properties: {
228
- displayName: {
229
- type: 'string',
230
- description: 'Display name to distinguish accounts at the same path',
231
- example: '招行工资卡'
232
- },
233
254
  currencies: {
234
255
  description: 'Allowed currencies (null = no restriction)',
235
256
  example: ['CNY', 'USD'],
@@ -251,19 +272,15 @@ export const $UpdateAccountDto = {
251
272
  'NONE'
252
273
  ]
253
274
  },
254
- i18nKey: {
255
- type: 'string',
256
- description: 'i18n key for display name',
257
- example: 'account.custom.mybank'
258
- },
259
275
  icon: {
260
276
  type: 'string',
261
277
  description: 'Icon identifier',
262
278
  example: 'bank-custom'
263
279
  },
264
- openMeta: {
280
+ openDirectiveMeta: {
265
281
  type: 'object',
266
- description: 'Additional metadata (merged with existing)',
282
+ description:
283
+ 'Open directive metadata (merged with existing; NOT an opening-balance amount)',
267
284
  example: {
268
285
  branch: 'Uptown'
269
286
  }
@@ -310,13 +327,47 @@ export const $ReopenAccountDto = {
310
327
  }
311
328
  } as const;
312
329
 
330
+ export const $CreateOpeningBalanceDto = {
331
+ type: 'object',
332
+ properties: {
333
+ amount: {
334
+ type: 'number',
335
+ description: 'Opening balance amount (non-negative)',
336
+ example: 1000
337
+ },
338
+ currency: {
339
+ type: 'string',
340
+ description: 'Currency code',
341
+ example: 'CNY'
342
+ },
343
+ date: {
344
+ format: 'date-time',
345
+ type: 'string',
346
+ description: 'Opening-balance date (defaults to now)',
347
+ example: '2024-01-01'
348
+ }
349
+ },
350
+ required: ['amount', 'currency']
351
+ } as const;
352
+
353
+ export const $OpeningBalanceResultDto = {
354
+ type: 'object',
355
+ properties: {
356
+ transactionId: {
357
+ type: 'string',
358
+ description: 'Created opening-balance transaction id.'
359
+ }
360
+ },
361
+ required: ['transactionId']
362
+ } as const;
363
+
313
364
  export const $AccountStandardResponseDto = {
314
365
  type: 'object',
315
366
  properties: {
316
367
  path: {
317
368
  type: 'string',
318
369
  description: 'Account path (hierarchical, colon-separated)',
319
- example: 'Assets:CN:Bank:ICBC:Checking'
370
+ example: 'Assets:CN:Checking'
320
371
  },
321
372
  type: {
322
373
  type: 'string',
@@ -324,11 +375,6 @@ export const $AccountStandardResponseDto = {
324
375
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
325
376
  example: 'Assets'
326
377
  },
327
- i18nKey: {
328
- type: 'string',
329
- description: 'i18n key for localized display name',
330
- example: 'account.assets.cn.bank.icbc.checking'
331
- },
332
378
  name: {
333
379
  type: 'string',
334
380
  description: 'Short localized display name',
@@ -351,9 +397,47 @@ export const $AccountStandardResponseDto = {
351
397
  type: 'string',
352
398
  description: 'Icon identifier for UI display',
353
399
  example: 'bank-icbc'
400
+ },
401
+ productCategory: {
402
+ type: 'string',
403
+ description:
404
+ 'Onboarding product category (coarse grouping derived from assetSubClass)',
405
+ enum: [
406
+ 'cash',
407
+ 'investment',
408
+ 'credit_card',
409
+ 'loan',
410
+ 'payable_tax',
411
+ 'other'
412
+ ],
413
+ example: 'investment'
414
+ },
415
+ assetClass: {
416
+ type: 'string',
417
+ description:
418
+ 'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
419
+ enum: [
420
+ 'LIQUIDITY',
421
+ 'EQUITY',
422
+ 'FIXED_INCOME',
423
+ 'PRECIOUS_METALS',
424
+ 'COMMODITY',
425
+ 'INSURANCE',
426
+ 'ALTERNATIVE_INVESTMENT',
427
+ 'PERSONAL_ASSETS',
428
+ 'LIABILITY',
429
+ 'REAL_ESTATE',
430
+ 'INDEX'
431
+ ]
432
+ },
433
+ assetSubClass: {
434
+ type: 'string',
435
+ description:
436
+ 'Asset sub-class (product type, derived at read time from classification rules)',
437
+ example: 'STOCK'
354
438
  }
355
439
  },
356
- required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
440
+ required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
357
441
  } as const;
358
442
 
359
443
  export const $AccountStandardListResponseDto = {
@@ -383,18 +467,13 @@ export const $AccountStandardListResponseDto = {
383
467
  export const $TemplateMetadataDto = {
384
468
  type: 'object',
385
469
  properties: {
386
- extendable: {
387
- type: 'boolean',
388
- description: 'Whether this path can be extended',
389
- example: true
390
- },
391
470
  rootType: {
392
471
  type: 'string',
393
472
  description: 'Root account type',
394
473
  example: 'Assets'
395
474
  }
396
475
  },
397
- required: ['extendable', 'rootType']
476
+ required: ['rootType']
398
477
  } as const;
399
478
 
400
479
  export const $TemplateMetadataResponseDto = {
@@ -533,7 +612,7 @@ export const $CreatePostingDto = {
533
612
  type: 'string',
534
613
  description:
535
614
  'Account name in Beancount format (must start with uppercase, colon-separated)',
536
- example: 'Assets:Bank:Checking'
615
+ example: 'Assets:Checking'
537
616
  },
538
617
  units: {
539
618
  type: 'string',
@@ -660,13 +739,39 @@ export const $CreateTransactionDto = {
660
739
  required: ['date', 'narration', 'postings']
661
740
  } as const;
662
741
 
742
+ export const $CostDetailDto = {
743
+ type: 'object',
744
+ properties: {
745
+ number: {
746
+ type: 'string',
747
+ description: 'Per-unit cost basis (mirrors engine Cost.number)',
748
+ example: '240'
749
+ },
750
+ currency: {
751
+ type: 'string',
752
+ description: 'Cost currency',
753
+ example: 'USD'
754
+ },
755
+ date: {
756
+ type: 'string',
757
+ description: 'Lot acquisition date (ISO yyyy-mm-dd)',
758
+ example: '2024-01-15'
759
+ },
760
+ label: {
761
+ type: 'string',
762
+ description: 'Lot label',
763
+ example: 'lot-2024-01'
764
+ }
765
+ }
766
+ } as const;
767
+
663
768
  export const $PostingResponseDto = {
664
769
  type: 'object',
665
770
  properties: {
666
771
  account: {
667
772
  type: 'string',
668
773
  description: 'Account name',
669
- example: 'Assets:Bank:Checking'
774
+ example: 'Assets:Checking'
670
775
  },
671
776
  units: {
672
777
  type: 'string',
@@ -678,6 +783,15 @@ export const $PostingResponseDto = {
678
783
  type: 'string',
679
784
  description: 'Currency',
680
785
  example: 'USD'
786
+ },
787
+ cost: {
788
+ description:
789
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
790
+ allOf: [
791
+ {
792
+ $ref: '#/components/schemas/CostDetailDto'
793
+ }
794
+ ]
681
795
  }
682
796
  },
683
797
  required: ['account']
@@ -1023,7 +1137,7 @@ export const $PostingDetailDto = {
1023
1137
  account: {
1024
1138
  type: 'string',
1025
1139
  description: 'Fully-qualified Beancount account path',
1026
- example: 'Assets:Bank:Checking'
1140
+ example: 'Assets:Checking'
1027
1141
  },
1028
1142
  units: {
1029
1143
  type: 'string',
@@ -1051,6 +1165,15 @@ export const $PostingDetailDto = {
1051
1165
  description: 'Cost date',
1052
1166
  example: '2024-01-15'
1053
1167
  },
1168
+ cost: {
1169
+ description:
1170
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
1171
+ allOf: [
1172
+ {
1173
+ $ref: '#/components/schemas/CostDetailDto'
1174
+ }
1175
+ ]
1176
+ },
1054
1177
  priceAmount: {
1055
1178
  type: 'string',
1056
1179
  description: 'Price amount',
@@ -1203,6 +1326,77 @@ export const $TransactionDetailDto = {
1203
1326
  ]
1204
1327
  } as const;
1205
1328
 
1329
+ export const $BalanceByCurrencyDto = {
1330
+ type: 'object',
1331
+ properties: {
1332
+ currency: {
1333
+ type: 'string',
1334
+ description: 'ISO 4217 currency code',
1335
+ example: 'CNY'
1336
+ },
1337
+ balance: {
1338
+ type: 'string',
1339
+ description: 'Balance amount',
1340
+ example: '50000.00'
1341
+ }
1342
+ },
1343
+ required: ['currency', 'balance']
1344
+ } as const;
1345
+
1346
+ export const $ExchangeRateWarningDto = {
1347
+ type: 'object',
1348
+ properties: {
1349
+ type: {
1350
+ type: 'string',
1351
+ description: 'Warning type',
1352
+ example: 'MISSING_EXCHANGE_RATE'
1353
+ },
1354
+ currency: {
1355
+ type: 'string',
1356
+ description: 'Currency without exchange rate',
1357
+ example: 'EUR'
1358
+ },
1359
+ totalAmount: {
1360
+ type: 'string',
1361
+ description: 'Total amount affected',
1362
+ example: '1000.00'
1363
+ }
1364
+ },
1365
+ required: ['type', 'currency', 'totalAmount']
1366
+ } as const;
1367
+
1368
+ export const $TransactionListSummaryDto = {
1369
+ type: 'object',
1370
+ properties: {
1371
+ totalAmount: {
1372
+ type: 'string',
1373
+ description:
1374
+ '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.',
1375
+ example: '-6000.00'
1376
+ },
1377
+ currency: {
1378
+ type: 'string',
1379
+ description: 'Base currency (ISO 4217)',
1380
+ example: 'CNY'
1381
+ },
1382
+ balanceByCurrency: {
1383
+ description: 'Raw (unconverted) balance per currency',
1384
+ type: 'array',
1385
+ items: {
1386
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
1387
+ }
1388
+ },
1389
+ warnings: {
1390
+ description: 'Currencies missing an FX rate (omitted when empty)',
1391
+ type: 'array',
1392
+ items: {
1393
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
1394
+ }
1395
+ }
1396
+ },
1397
+ required: ['totalAmount', 'currency', 'balanceByCurrency']
1398
+ } as const;
1399
+
1206
1400
  export const $TransactionListResponseDto = {
1207
1401
  type: 'object',
1208
1402
  properties: {
@@ -1227,6 +1421,15 @@ export const $TransactionListResponseDto = {
1227
1421
  type: 'number',
1228
1422
  description: 'Number of items skipped',
1229
1423
  example: 0
1424
+ },
1425
+ summary: {
1426
+ description:
1427
+ '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.',
1428
+ allOf: [
1429
+ {
1430
+ $ref: '#/components/schemas/TransactionListSummaryDto'
1431
+ }
1432
+ ]
1230
1433
  }
1231
1434
  },
1232
1435
  required: ['data', 'total', 'limit', 'offset']
@@ -1326,7 +1529,7 @@ export const $BalanceResponseDto = {
1326
1529
  account: {
1327
1530
  type: 'string',
1328
1531
  description: 'Account name',
1329
- example: 'Assets:Bank:Checking'
1532
+ example: 'Assets:Checking'
1330
1533
  },
1331
1534
  balance: {
1332
1535
  type: 'string',
@@ -1353,7 +1556,7 @@ export const $MultiCurrencyBalanceResponseDto = {
1353
1556
  account: {
1354
1557
  type: 'string',
1355
1558
  description: 'Account name',
1356
- example: 'Assets:Bank:Checking'
1559
+ example: 'Assets:Checking'
1357
1560
  },
1358
1561
  balances: {
1359
1562
  type: 'object',
@@ -1409,7 +1612,7 @@ export const $TransactionSummaryDto = {
1409
1612
  accountName: {
1410
1613
  type: 'string',
1411
1614
  description: 'Source account name (first posting)',
1412
- example: 'Assets:Bank:Checking'
1615
+ example: 'Assets:Checking'
1413
1616
  },
1414
1617
  sourceType: {
1415
1618
  type: 'string',
@@ -1811,7 +2014,8 @@ export const $ResolveResultDto = {
1811
2014
  },
1812
2015
  resolutionId: {
1813
2016
  type: 'string',
1814
- description: 'Resolution ID for undo'
2017
+ description:
2018
+ 'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
1815
2019
  },
1816
2020
  canUndo: {
1817
2021
  type: 'boolean',
@@ -1829,7 +2033,7 @@ export const $ResolveResultDto = {
1829
2033
  example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
1830
2034
  }
1831
2035
  },
1832
- required: ['success', 'resolutionId', 'canUndo', 'undoDeadline']
2036
+ required: ['success']
1833
2037
  } as const;
1834
2038
 
1835
2039
  export const $UndoResultDto = {
@@ -2700,56 +2904,213 @@ export const $UpdateCommodityDto = {
2700
2904
  }
2701
2905
  } as const;
2702
2906
 
2703
- export const $CreateRecurringRuleDto = {
2907
+ export const $CreateBeanPriceDto = {
2704
2908
  type: 'object',
2705
2909
  properties: {
2706
- name: {
2707
- type: 'string',
2708
- description: 'Rule name (unique per user)',
2709
- maxLength: 100
2710
- },
2711
- icon: {
2910
+ currency: {
2712
2911
  type: 'string',
2713
- description: 'Icon emoji',
2714
- maxLength: 10
2912
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2913
+ example: 'USD'
2715
2914
  },
2716
- frequency: {
2915
+ quoteCurrency: {
2717
2916
  type: 'string',
2718
- description: 'Recurring frequency',
2719
- enum: [
2720
- 'WEEKLY',
2721
- 'BIWEEKLY',
2722
- 'MONTHLY',
2723
- 'BIMONTHLY',
2724
- 'QUARTERLY',
2725
- 'YEARLY',
2726
- 'CUSTOM'
2727
- ]
2917
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
2918
+ example: 'CNY'
2728
2919
  },
2729
- expectedAmount: {
2920
+ amount: {
2730
2921
  type: 'number',
2731
- description: 'Expected amount (positive number)',
2922
+ description:
2923
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
2924
+ example: 175.5,
2732
2925
  minimum: 0
2733
2926
  },
2734
- expectedDay: {
2735
- type: 'number',
2736
- description: 'Expected day of month (1-31)',
2737
- minimum: 1,
2738
- maximum: 31
2739
- },
2740
- customIntervalDays: {
2741
- type: 'number',
2742
- description: 'Custom interval in days (required for CUSTOM frequency)',
2743
- minimum: 1
2744
- },
2745
- currency: {
2927
+ date: {
2746
2928
  type: 'string',
2747
- description: 'Currency code',
2748
- default: 'CNY',
2749
- maxLength: 10
2929
+ description: 'Price date (ISO 8601 format)',
2930
+ example: '2024-11-05'
2750
2931
  },
2751
- matchPayeePattern: {
2752
- type: 'string',
2932
+ metadata: {
2933
+ type: 'object',
2934
+ description:
2935
+ 'Metadata (validated by Zod schema, max field lengths enforced)',
2936
+ example: {
2937
+ source: 'MANUAL',
2938
+ note: 'Bank valuation report',
2939
+ confidence: 0.95
2940
+ }
2941
+ }
2942
+ },
2943
+ required: ['currency', 'quoteCurrency', 'amount', 'date']
2944
+ } as const;
2945
+
2946
+ export const $PriceResponseDto = {
2947
+ type: 'object',
2948
+ properties: {
2949
+ id: {
2950
+ type: 'string',
2951
+ description: 'Unique identifier',
2952
+ example: 'uuid-123-456'
2953
+ },
2954
+ userId: {
2955
+ type: 'string',
2956
+ description: 'User ID (owner of the price)',
2957
+ example: 'user-123'
2958
+ },
2959
+ currency: {
2960
+ type: 'string',
2961
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2962
+ example: 'BTC'
2963
+ },
2964
+ quoteCurrency: {
2965
+ type: 'string',
2966
+ description: 'Quote currency (pricing currency, e.g., USD, CNY)',
2967
+ example: 'USD'
2968
+ },
2969
+ amount: {
2970
+ type: 'number',
2971
+ description:
2972
+ 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
2973
+ example: 50000
2974
+ },
2975
+ date: {
2976
+ type: 'string',
2977
+ description:
2978
+ 'Price date (ISO 8601 format). Represents the date this price was valid.',
2979
+ example: '2024-01-01',
2980
+ format: 'date'
2981
+ },
2982
+ meta: {
2983
+ type: 'object',
2984
+ description:
2985
+ 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
2986
+ example: {
2987
+ source: 'MANUAL',
2988
+ note: 'User-defined price',
2989
+ confidence: 1
2990
+ }
2991
+ },
2992
+ createdAt: {
2993
+ format: 'date-time',
2994
+ type: 'string',
2995
+ description: 'Creation timestamp',
2996
+ example: '2024-11-03T10:00:00Z'
2997
+ },
2998
+ updatedAt: {
2999
+ format: 'date-time',
3000
+ type: 'string',
3001
+ description: 'Last update timestamp',
3002
+ example: '2024-11-03T10:00:00Z'
3003
+ }
3004
+ },
3005
+ required: [
3006
+ 'id',
3007
+ 'userId',
3008
+ 'currency',
3009
+ 'quoteCurrency',
3010
+ 'amount',
3011
+ 'date',
3012
+ 'meta',
3013
+ 'createdAt',
3014
+ 'updatedAt'
3015
+ ]
3016
+ } as const;
3017
+
3018
+ export const $PriceListResponseDto = {
3019
+ type: 'object',
3020
+ properties: {
3021
+ items: {
3022
+ description: 'List of prices',
3023
+ type: 'array',
3024
+ items: {
3025
+ $ref: '#/components/schemas/PriceResponseDto'
3026
+ }
3027
+ },
3028
+ total: {
3029
+ type: 'number',
3030
+ description: 'Total number of prices',
3031
+ example: 42
3032
+ }
3033
+ },
3034
+ required: ['items', 'total']
3035
+ } as const;
3036
+
3037
+ export const $UpdateBeanPriceDto = {
3038
+ type: 'object',
3039
+ properties: {
3040
+ currency: {
3041
+ type: 'string',
3042
+ description: 'Currency being priced'
3043
+ },
3044
+ quoteCurrency: {
3045
+ type: 'string',
3046
+ description: 'Quote currency (pricing currency)'
3047
+ },
3048
+ amount: {
3049
+ type: 'number',
3050
+ description: 'Price amount (MUST be >= 0 per Beancount spec)',
3051
+ minimum: 0
3052
+ },
3053
+ date: {
3054
+ type: 'string',
3055
+ description: 'Price date (ISO 8601 format)'
3056
+ },
3057
+ metadata: {
3058
+ type: 'object',
3059
+ description: 'Metadata'
3060
+ }
3061
+ }
3062
+ } as const;
3063
+
3064
+ export const $CreateRecurringRuleDto = {
3065
+ type: 'object',
3066
+ properties: {
3067
+ name: {
3068
+ type: 'string',
3069
+ description: 'Rule name (unique per user)',
3070
+ maxLength: 100
3071
+ },
3072
+ icon: {
3073
+ type: 'string',
3074
+ description: 'Icon emoji',
3075
+ maxLength: 10
3076
+ },
3077
+ frequency: {
3078
+ type: 'string',
3079
+ description: 'Recurring frequency',
3080
+ enum: [
3081
+ 'WEEKLY',
3082
+ 'BIWEEKLY',
3083
+ 'MONTHLY',
3084
+ 'BIMONTHLY',
3085
+ 'QUARTERLY',
3086
+ 'YEARLY',
3087
+ 'CUSTOM'
3088
+ ]
3089
+ },
3090
+ expectedAmount: {
3091
+ type: 'number',
3092
+ description: 'Expected amount (positive number)',
3093
+ minimum: 0
3094
+ },
3095
+ expectedDay: {
3096
+ type: 'number',
3097
+ description: 'Expected day of month (1-31)',
3098
+ minimum: 1,
3099
+ maximum: 31
3100
+ },
3101
+ customIntervalDays: {
3102
+ type: 'number',
3103
+ description: 'Custom interval in days (required for CUSTOM frequency)',
3104
+ minimum: 1
3105
+ },
3106
+ currency: {
3107
+ type: 'string',
3108
+ description: 'Currency code',
3109
+ default: 'CNY',
3110
+ maxLength: 10
3111
+ },
3112
+ matchPayeePattern: {
3113
+ type: 'string',
2753
3114
  description: 'Payee matching pattern (supports wildcards)',
2754
3115
  maxLength: 200
2755
3116
  },
@@ -3471,281 +3832,473 @@ export const $ForecastResponseDto = {
3471
3832
  ]
3472
3833
  } as const;
3473
3834
 
3474
- export const $CreateTransactionRuleDto = {
3835
+ export const $CurrencyBalanceDto = {
3475
3836
  type: 'object',
3476
3837
  properties: {
3477
- name: {
3838
+ currency: {
3478
3839
  type: 'string',
3479
- minLength: 1,
3480
- maxLength: 100
3840
+ description: 'ISO 4217 currency code',
3841
+ example: 'CNY'
3481
3842
  },
3482
- description: {
3843
+ balance: {
3483
3844
  type: 'string',
3484
- maxLength: 500
3485
- },
3486
- narrationKeywords: {
3487
- items: {
3488
- type: 'array'
3489
- },
3490
- maxItems: 50,
3491
- type: 'array'
3492
- },
3493
- payeeKeywords: {
3494
- items: {
3495
- type: 'array'
3496
- },
3497
- maxItems: 50,
3498
- type: 'array'
3845
+ description: 'Balance amount',
3846
+ example: '500000.00'
3847
+ }
3848
+ },
3849
+ required: ['currency', 'balance']
3850
+ } as const;
3851
+
3852
+ export const $TimeSeriesPointDto = {
3853
+ type: 'object',
3854
+ properties: {
3855
+ date: {
3856
+ type: 'string',
3857
+ description: 'Date in YYYY-MM-DD format',
3858
+ example: '2024-06-15'
3499
3859
  },
3500
- categoryKeywords: {
3501
- items: {
3502
- type: 'array'
3503
- },
3504
- maxItems: 50,
3505
- type: 'array'
3860
+ value: {
3861
+ type: 'string',
3862
+ description: 'Value at this date (in base currency)',
3863
+ example: '500000.00'
3506
3864
  },
3507
- methodKeywords: {
3508
- items: {
3509
- type: 'array'
3510
- },
3511
- maxItems: 50,
3512
- description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
3513
- type: 'array'
3865
+ change: {
3866
+ type: 'object',
3867
+ description: 'Change from previous point',
3868
+ example: '5000.00'
3514
3869
  },
3515
- categoryAccount: {
3870
+ assets: {
3516
3871
  type: 'string',
3517
- maxLength: 200,
3518
- description:
3519
- 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
3872
+ description: 'Total assets at this date (in base currency)',
3873
+ example: '494338.00'
3520
3874
  },
3521
- matchLogic: {
3875
+ liabilities: {
3522
3876
  type: 'string',
3523
- enum: ['OR', 'AND'],
3524
- default: 'OR'
3525
- },
3526
- amountMin: {
3527
- type: 'number',
3528
- minimum: 0,
3529
- description: 'Minimum transaction amount (inclusive)'
3877
+ description: 'Total liabilities at this date (in base currency)',
3878
+ example: '310098.00'
3530
3879
  },
3531
- amountMax: {
3532
- type: 'number',
3533
- minimum: 0,
3534
- description: 'Maximum transaction amount (inclusive)'
3535
- },
3536
- priority: {
3537
- type: 'number',
3538
- default: 50,
3539
- minimum: 0,
3540
- maximum: 1000
3541
- },
3542
- additionalTags: {
3880
+ byCurrency: {
3881
+ description: 'Multi-currency breakdown for this point',
3882
+ type: 'array',
3543
3883
  items: {
3544
- type: 'array'
3545
- },
3546
- maxItems: 20,
3547
- type: 'array'
3548
- },
3549
- additionalMetadata: {
3550
- type: 'object'
3551
- },
3552
- upsertByPayee: {
3553
- type: 'boolean',
3554
- description:
3555
- 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
3884
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3885
+ }
3556
3886
  }
3557
3887
  },
3558
- required: ['name', 'matchLogic', 'priority']
3888
+ required: ['date', 'value']
3559
3889
  } as const;
3560
3890
 
3561
- export const $AmountRangeDto = {
3891
+ export const $TrendSummaryDto = {
3562
3892
  type: 'object',
3563
3893
  properties: {
3564
- min: {
3565
- type: 'number',
3566
- description: 'Minimum amount'
3894
+ startValue: {
3895
+ type: 'string',
3896
+ description: 'Value at start of period',
3897
+ example: '450000.00'
3567
3898
  },
3568
- max: {
3569
- type: 'number',
3570
- description: 'Maximum amount'
3899
+ endValue: {
3900
+ type: 'string',
3901
+ description: 'Value at end of period',
3902
+ example: '500000.00'
3903
+ },
3904
+ totalChange: {
3905
+ type: 'string',
3906
+ description: 'Total change over period',
3907
+ example: '50000.00'
3908
+ },
3909
+ totalChangePercentage: {
3910
+ type: 'string',
3911
+ description: 'Total change percentage',
3912
+ example: '+11.11%'
3571
3913
  }
3572
- }
3914
+ },
3915
+ required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
3573
3916
  } as const;
3574
3917
 
3575
- export const $TransactionRuleResponseDto = {
3918
+ export const $MultiCurrencyPointDto = {
3576
3919
  type: 'object',
3577
3920
  properties: {
3578
- id: {
3579
- type: 'string',
3580
- description: 'Rule ID'
3581
- },
3582
- name: {
3583
- type: 'string',
3584
- description: 'Rule name'
3585
- },
3586
- description: {
3921
+ date: {
3587
3922
  type: 'string',
3588
- description: 'Rule description'
3589
- },
3590
- narrationKeywords: {
3591
- description: 'Keywords to match in transaction narration',
3592
- type: 'array',
3593
- items: {
3594
- type: 'string'
3595
- }
3596
- },
3597
- payeeKeywords: {
3598
- description: 'Keywords to match in payee name',
3599
- type: 'array',
3600
- items: {
3601
- type: 'string'
3602
- }
3923
+ description: 'Date in YYYY-MM-DD format',
3924
+ example: '2024-06-15'
3603
3925
  },
3604
- categoryKeywords: {
3605
- description: 'Keywords to match in category',
3926
+ byCurrency: {
3927
+ description: 'Balances by currency',
3606
3928
  type: 'array',
3607
3929
  items: {
3608
- type: 'string'
3930
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3609
3931
  }
3610
- },
3611
- methodKeywords: {
3612
- description: 'Keywords to match in payment method',
3932
+ }
3933
+ },
3934
+ required: ['date', 'byCurrency']
3935
+ } as const;
3936
+
3937
+ export const $PortfolioTrendsResponseDto = {
3938
+ type: 'object',
3939
+ properties: {
3940
+ series: {
3941
+ description: 'Time series data points',
3613
3942
  type: 'array',
3614
3943
  items: {
3615
- type: 'string'
3944
+ $ref: '#/components/schemas/TimeSeriesPointDto'
3616
3945
  }
3617
3946
  },
3618
- categoryAccount: {
3619
- type: 'string',
3620
- description: 'Destination account for categorization'
3621
- },
3622
- matchLogic: {
3623
- type: 'string',
3624
- description: 'Keyword matching logic',
3625
- enum: ['OR', 'AND'],
3626
- example: 'OR'
3627
- },
3628
- amountRange: {
3629
- description: 'Amount range for matching',
3947
+ summary: {
3948
+ description: 'Period summary',
3630
3949
  allOf: [
3631
3950
  {
3632
- $ref: '#/components/schemas/AmountRangeDto'
3951
+ $ref: '#/components/schemas/TrendSummaryDto'
3633
3952
  }
3634
3953
  ]
3635
3954
  },
3636
- priority: {
3637
- type: 'number',
3638
- description: 'Rule priority (0-1000, higher = first match)',
3639
- example: 50
3640
- },
3641
- enabled: {
3642
- type: 'boolean',
3643
- description: 'Whether the rule is enabled'
3644
- },
3645
- learningSource: {
3955
+ period: {
3646
3956
  type: 'string',
3647
- description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
3648
- enum: ['NLP', 'REVIEW_CENTER'],
3649
- nullable: true,
3650
- example: 'REVIEW_CENTER'
3957
+ description: 'Period requested',
3958
+ example: '6m'
3651
3959
  },
3652
- autoApplyEnabled: {
3653
- type: 'boolean',
3654
- description: 'Whether auto-apply is enabled for this rule'
3960
+ granularity: {
3961
+ type: 'string',
3962
+ description: 'Data granularity',
3963
+ example: 'month'
3655
3964
  },
3656
- confirmationCount: {
3657
- type: 'number',
3658
- description: 'Number of confirmations for NLP-learned rules',
3659
- example: 3
3965
+ currency: {
3966
+ type: 'string',
3967
+ description: 'Base currency for converted values',
3968
+ example: 'CNY'
3660
3969
  },
3661
- additionalTags: {
3662
- description: 'Additional tags',
3970
+ byCurrency: {
3971
+ description:
3972
+ 'Multi-currency time series (each point has currency breakdown)',
3663
3973
  type: 'array',
3664
3974
  items: {
3665
- type: 'string'
3975
+ $ref: '#/components/schemas/MultiCurrencyPointDto'
3666
3976
  }
3667
3977
  },
3668
- additionalMetadata: {
3669
- type: 'object',
3670
- description: 'Additional metadata',
3671
- additionalProperties: {
3672
- type: 'string'
3978
+ warnings: {
3979
+ description: 'Exchange rate warnings',
3980
+ type: 'array',
3981
+ items: {
3982
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
3673
3983
  }
3674
- },
3675
- createdAt: {
3676
- format: 'date-time',
3677
- type: 'string',
3678
- description: 'Created timestamp'
3679
- },
3680
- updatedAt: {
3681
- format: 'date-time',
3682
- type: 'string',
3683
- description: 'Updated timestamp'
3684
3984
  }
3685
3985
  },
3686
- required: [
3687
- 'id',
3688
- 'name',
3689
- 'narrationKeywords',
3690
- 'payeeKeywords',
3691
- 'categoryKeywords',
3692
- 'methodKeywords',
3693
- 'matchLogic',
3694
- 'priority',
3695
- 'enabled',
3696
- 'autoApplyEnabled',
3697
- 'confirmationCount',
3698
- 'additionalTags',
3699
- 'createdAt',
3700
- 'updatedAt'
3701
- ]
3986
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3702
3987
  } as const;
3703
3988
 
3704
- export const $TransactionRuleListResponseDto = {
3989
+ export const $CashFlowPointDto = {
3705
3990
  type: 'object',
3706
3991
  properties: {
3707
- data: {
3708
- type: 'array',
3709
- items: {
3710
- $ref: '#/components/schemas/TransactionRuleResponseDto'
3711
- }
3992
+ month: {
3993
+ type: 'string',
3994
+ description: 'Month key (YYYY-MM)',
3995
+ example: '2024-03'
3712
3996
  },
3713
- total: {
3714
- type: 'number',
3715
- description: 'Total count of rules'
3997
+ income: {
3998
+ type: 'string',
3999
+ description: 'Income in base currency (absolute, converted)',
4000
+ example: '10000.00'
3716
4001
  },
3717
- limit: {
3718
- type: 'number',
3719
- description: 'Results per page'
4002
+ expense: {
4003
+ type: 'string',
4004
+ description: 'Expense in base currency (absolute, converted)',
4005
+ example: '5000.00'
3720
4006
  },
3721
- offset: {
3722
- type: 'number',
3723
- description: 'Pagination offset'
4007
+ netSavings: {
4008
+ type: 'string',
4009
+ description: 'netSavings = income − expense (savings positive)',
4010
+ example: '5000.00'
3724
4011
  }
3725
4012
  },
3726
- required: ['data', 'total', 'limit', 'offset']
4013
+ required: ['month', 'income', 'expense', 'netSavings']
3727
4014
  } as const;
3728
4015
 
3729
- export const $ValidateRuleDto = {
4016
+ export const $CashFlowTrendSummaryDto = {
3730
4017
  type: 'object',
3731
4018
  properties: {
3732
- name: {
4019
+ totalIncome: {
3733
4020
  type: 'string',
3734
- minLength: 1,
3735
- maxLength: 100
4021
+ description: 'Total income across the period',
4022
+ example: '60000.00'
3736
4023
  },
3737
- description: {
4024
+ totalExpense: {
3738
4025
  type: 'string',
3739
- maxLength: 500
4026
+ description: 'Total expense across the period',
4027
+ example: '30000.00'
3740
4028
  },
3741
- narrationKeywords: {
3742
- items: {
3743
- type: 'array'
3744
- },
3745
- maxItems: 50,
3746
- type: 'array'
4029
+ totalNetSavings: {
4030
+ type: 'string',
4031
+ description: 'income − expense across the period',
4032
+ example: '30000.00'
3747
4033
  },
3748
- payeeKeywords: {
4034
+ averageMonthlyNetSavings: {
4035
+ type: 'string',
4036
+ description:
4037
+ 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
4038
+ example: '5000.00'
4039
+ }
4040
+ },
4041
+ required: [
4042
+ 'totalIncome',
4043
+ 'totalExpense',
4044
+ 'totalNetSavings',
4045
+ 'averageMonthlyNetSavings'
4046
+ ]
4047
+ } as const;
4048
+
4049
+ export const $CashFlowTrendsResponseDto = {
4050
+ type: 'object',
4051
+ properties: {
4052
+ series: {
4053
+ description:
4054
+ 'Monthly cash-flow series (fixed N-month window, zero-filled)',
4055
+ type: 'array',
4056
+ items: {
4057
+ $ref: '#/components/schemas/CashFlowPointDto'
4058
+ }
4059
+ },
4060
+ summary: {
4061
+ description: 'Period totals',
4062
+ allOf: [
4063
+ {
4064
+ $ref: '#/components/schemas/CashFlowTrendSummaryDto'
4065
+ }
4066
+ ]
4067
+ },
4068
+ period: {
4069
+ type: 'string',
4070
+ description: 'Period requested',
4071
+ example: '6m'
4072
+ },
4073
+ granularity: {
4074
+ type: 'string',
4075
+ description: 'Data granularity (v1 returns month buckets)',
4076
+ example: 'month'
4077
+ },
4078
+ currency: {
4079
+ type: 'string',
4080
+ description: 'Base currency for converted values',
4081
+ example: 'CNY'
4082
+ },
4083
+ warnings: {
4084
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
4085
+ type: 'array',
4086
+ items: {
4087
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
4088
+ }
4089
+ }
4090
+ },
4091
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
4092
+ } as const;
4093
+
4094
+ export const $GenerateSnapshotBody = {
4095
+ type: 'object',
4096
+ properties: {}
4097
+ } as const;
4098
+
4099
+ export const $GenerateSnapshotResponse = {
4100
+ type: 'object',
4101
+ properties: {}
4102
+ } as const;
4103
+
4104
+ export const $BackfillSnapshotsBody = {
4105
+ type: 'object',
4106
+ properties: {}
4107
+ } as const;
4108
+
4109
+ export const $BackfillSnapshotsResponse = {
4110
+ type: 'object',
4111
+ properties: {}
4112
+ } as const;
4113
+
4114
+ export const $DeleteOwnUserDto = {
4115
+ type: 'object',
4116
+ properties: {
4117
+ accessToken: {
4118
+ type: 'string',
4119
+ description: 'Access token for user verification',
4120
+ example: 'abc123xyz'
4121
+ }
4122
+ },
4123
+ required: ['accessToken']
4124
+ } as const;
4125
+
4126
+ export const $SignupDto = {
4127
+ type: 'object',
4128
+ properties: {
4129
+ turnstileToken: {
4130
+ type: 'string',
4131
+ description:
4132
+ 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4133
+ example: '0.abc123def456...'
4134
+ }
4135
+ }
4136
+ } as const;
4137
+
4138
+ export const $SignupResponseDto = {
4139
+ type: 'object',
4140
+ properties: {
4141
+ authToken: {
4142
+ type: 'string',
4143
+ description: 'JWT auth token',
4144
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
4145
+ },
4146
+ accessToken: {
4147
+ type: 'string',
4148
+ description: 'Auto-generated access token'
4149
+ },
4150
+ role: {
4151
+ type: 'string',
4152
+ description: 'Assigned user role',
4153
+ enum: ['USER', 'ADMIN', 'DEMO', 'INACTIVE', 'PAID', 'OPS']
4154
+ }
4155
+ },
4156
+ required: ['authToken', 'accessToken', 'role']
4157
+ } as const;
4158
+
4159
+ export const $UpdateUserSettingDto = {
4160
+ type: 'object',
4161
+ properties: {
4162
+ secId: {
4163
+ type: 'number',
4164
+ description: 'Security ID'
4165
+ },
4166
+ annualInterestRate: {
4167
+ type: 'number',
4168
+ description: 'Annual interest rate',
4169
+ example: 0.05
4170
+ },
4171
+ currency: {
4172
+ type: 'string',
4173
+ description: 'Currency code',
4174
+ example: 'USD'
4175
+ },
4176
+ baseCurrency: {
4177
+ type: 'string',
4178
+ description: 'Base currency code',
4179
+ example: 'USD'
4180
+ },
4181
+ benchmark: {
4182
+ type: 'string',
4183
+ description: 'Benchmark symbol',
4184
+ example: 'SPY'
4185
+ },
4186
+ colorScheme: {
4187
+ type: 'string',
4188
+ description: 'Color scheme',
4189
+ enum: ['DARK', 'LIGHT']
4190
+ },
4191
+ dateRange: {
4192
+ type: 'string',
4193
+ description: 'Date range filter',
4194
+ example: '1y'
4195
+ },
4196
+ emergencyFund: {
4197
+ type: 'number',
4198
+ description: 'Emergency fund amount',
4199
+ example: 10000
4200
+ },
4201
+ 'filters.accounts': {
4202
+ description: 'Account filter IDs',
4203
+ type: 'array',
4204
+ items: {
4205
+ type: 'string'
4206
+ }
4207
+ },
4208
+ 'filters.assetClasses': {
4209
+ description: 'Asset class filters',
4210
+ type: 'array',
4211
+ items: {
4212
+ type: 'string'
4213
+ }
4214
+ },
4215
+ 'filters.dataSource': {
4216
+ type: 'string',
4217
+ description: 'Data source filter'
4218
+ },
4219
+ 'filters.symbol': {
4220
+ type: 'string',
4221
+ description: 'Symbol filter'
4222
+ },
4223
+ 'filters.tags': {
4224
+ description: 'Tag filters',
4225
+ type: 'array',
4226
+ items: {
4227
+ type: 'string'
4228
+ }
4229
+ },
4230
+ isExperimentalFeatures: {
4231
+ type: 'boolean',
4232
+ description: 'Enable experimental features'
4233
+ },
4234
+ isRestrictedView: {
4235
+ type: 'boolean',
4236
+ description: 'Enable restricted view mode'
4237
+ },
4238
+ language: {
4239
+ type: 'string',
4240
+ description: 'Language code',
4241
+ example: 'en'
4242
+ },
4243
+ locale: {
4244
+ type: 'string',
4245
+ description: 'Locale code',
4246
+ example: 'en-US'
4247
+ },
4248
+ projectedTotalAmount: {
4249
+ type: 'number',
4250
+ description: 'Projected total amount',
4251
+ example: 1000000
4252
+ },
4253
+ retirementDate: {
4254
+ type: 'string',
4255
+ description: 'Retirement date in ISO 8601 format',
4256
+ example: '2050-01-01'
4257
+ },
4258
+ savingsRate: {
4259
+ type: 'number',
4260
+ description: 'Savings rate percentage',
4261
+ example: 0.2
4262
+ },
4263
+ viewMode: {
4264
+ type: 'string',
4265
+ description: 'View mode',
4266
+ enum: ['DEFAULT', 'ZEN']
4267
+ }
4268
+ }
4269
+ } as const;
4270
+
4271
+ export const $UpdatePropertyDto = {
4272
+ type: 'object',
4273
+ properties: {
4274
+ value: {
4275
+ type: 'string',
4276
+ description: 'Property value'
4277
+ }
4278
+ },
4279
+ required: ['value']
4280
+ } as const;
4281
+
4282
+ export const $CreateTransactionRuleDto = {
4283
+ type: 'object',
4284
+ properties: {
4285
+ name: {
4286
+ type: 'string',
4287
+ minLength: 1,
4288
+ maxLength: 100
4289
+ },
4290
+ description: {
4291
+ type: 'string',
4292
+ maxLength: 500
4293
+ },
4294
+ narrationKeywords: {
4295
+ items: {
4296
+ type: 'array'
4297
+ },
4298
+ maxItems: 50,
4299
+ type: 'array'
4300
+ },
4301
+ payeeKeywords: {
3749
4302
  items: {
3750
4303
  type: 'array'
3751
4304
  },
@@ -3813,175 +4366,175 @@ export const $ValidateRuleDto = {
3813
4366
  required: ['name', 'matchLogic', 'priority']
3814
4367
  } as const;
3815
4368
 
3816
- export const $ValidateRuleResponseDto = {
4369
+ export const $AmountRangeDto = {
3817
4370
  type: 'object',
3818
4371
  properties: {
3819
- valid: {
3820
- type: 'boolean',
3821
- description: 'Whether the rule configuration is valid',
3822
- example: true
3823
- },
3824
- errors: {
3825
- description: 'List of validation errors (empty if valid)',
3826
- example: [],
3827
- items: {
3828
- type: 'array'
3829
- },
3830
- type: 'array'
4372
+ min: {
4373
+ type: 'number',
4374
+ description: 'Minimum amount'
3831
4375
  },
3832
- warnings: {
3833
- description: 'List of validation warnings (non-blocking issues)',
3834
- example: [
3835
- 'No account constraints specified - rule will match any account'
3836
- ],
3837
- items: {
3838
- type: 'array'
3839
- },
3840
- type: 'array'
4376
+ max: {
4377
+ type: 'number',
4378
+ description: 'Maximum amount'
3841
4379
  }
3842
- },
3843
- required: ['valid', 'errors', 'warnings']
4380
+ }
3844
4381
  } as const;
3845
4382
 
3846
- export const $BulkCreateRulesDto = {
4383
+ export const $TransactionRuleResponseDto = {
3847
4384
  type: 'object',
3848
4385
  properties: {
3849
- rules: {
3850
- items: {
3851
- type: 'array'
3852
- },
3853
- description: 'Array of rules to import',
3854
- type: 'array'
4386
+ id: {
4387
+ type: 'string',
4388
+ description: 'Rule ID'
3855
4389
  },
3856
- conflictStrategy: {
4390
+ name: {
3857
4391
  type: 'string',
3858
- enum: ['replace', 'skip'],
3859
- default: 'skip',
3860
- description:
3861
- 'Conflict handling strategy: skip (default) ignores duplicates, replace soft-deletes existing rule'
3862
- }
3863
- },
3864
- required: ['rules', 'conflictStrategy']
3865
- } as const;
3866
-
3867
- export const $BulkCreateRulesResponseDto = {
3868
- type: 'object',
3869
- properties: {
3870
- successCount: {
3871
- type: 'number',
3872
- description: 'Number of successfully created rules'
4392
+ description: 'Rule name'
3873
4393
  },
3874
- failureCount: {
3875
- type: 'number',
3876
- description: 'Number of failed rules'
4394
+ description: {
4395
+ type: 'string',
4396
+ description: 'Rule description'
3877
4397
  },
3878
- errors: {
4398
+ narrationKeywords: {
4399
+ description: 'Keywords to match in transaction narration',
3879
4400
  type: 'array',
3880
- description: 'Error details for failed rules',
3881
4401
  items: {
3882
- type: 'object',
3883
- properties: {
3884
- index: {
3885
- type: 'number'
3886
- },
3887
- message: {
3888
- type: 'string'
3889
- }
3890
- }
4402
+ type: 'string'
3891
4403
  }
3892
4404
  },
3893
- createdRuleIds: {
3894
- description: 'IDs of successfully created rules',
4405
+ payeeKeywords: {
4406
+ description: 'Keywords to match in payee name',
3895
4407
  type: 'array',
3896
4408
  items: {
3897
4409
  type: 'string'
3898
4410
  }
3899
- }
3900
- },
3901
- required: ['successCount', 'failureCount', 'errors', 'createdRuleIds']
3902
- } as const;
3903
-
3904
- export const $ExportRulesResponseDto = {
3905
- type: 'object',
3906
- properties: {
3907
- exportedAt: {
4411
+ },
4412
+ categoryKeywords: {
4413
+ description: 'Keywords to match in category',
4414
+ type: 'array',
4415
+ items: {
4416
+ type: 'string'
4417
+ }
4418
+ },
4419
+ methodKeywords: {
4420
+ description: 'Keywords to match in payment method',
4421
+ type: 'array',
4422
+ items: {
4423
+ type: 'string'
4424
+ }
4425
+ },
4426
+ categoryAccount: {
3908
4427
  type: 'string',
3909
- description: 'Export timestamp'
4428
+ description: 'Destination account for categorization'
3910
4429
  },
3911
- userId: {
4430
+ matchLogic: {
3912
4431
  type: 'string',
3913
- description: 'User ID'
4432
+ description: 'Keyword matching logic',
4433
+ enum: ['OR', 'AND'],
4434
+ example: 'OR'
3914
4435
  },
3915
- ruleCount: {
4436
+ amountRange: {
4437
+ description: 'Amount range for matching',
4438
+ allOf: [
4439
+ {
4440
+ $ref: '#/components/schemas/AmountRangeDto'
4441
+ }
4442
+ ]
4443
+ },
4444
+ priority: {
3916
4445
  type: 'number',
3917
- description: 'Number of exported rules'
4446
+ description: 'Rule priority (0-1000, higher = first match)',
4447
+ example: 50
3918
4448
  },
3919
- rules: {
4449
+ enabled: {
4450
+ type: 'boolean',
4451
+ description: 'Whether the rule is enabled'
4452
+ },
4453
+ learningSource: {
4454
+ type: 'string',
4455
+ description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
4456
+ enum: ['NLP', 'REVIEW_CENTER'],
4457
+ nullable: true,
4458
+ example: 'REVIEW_CENTER'
4459
+ },
4460
+ autoApplyEnabled: {
4461
+ type: 'boolean',
4462
+ description: 'Whether auto-apply is enabled for this rule'
4463
+ },
4464
+ confirmationCount: {
4465
+ type: 'number',
4466
+ description: 'Number of confirmations for NLP-learned rules',
4467
+ example: 3
4468
+ },
4469
+ additionalTags: {
4470
+ description: 'Additional tags',
3920
4471
  type: 'array',
3921
- description: 'Exported rules'
4472
+ items: {
4473
+ type: 'string'
4474
+ }
4475
+ },
4476
+ additionalMetadata: {
4477
+ type: 'object',
4478
+ description: 'Additional metadata',
4479
+ additionalProperties: {
4480
+ type: 'string'
4481
+ }
4482
+ },
4483
+ createdAt: {
4484
+ format: 'date-time',
4485
+ type: 'string',
4486
+ description: 'Created timestamp'
4487
+ },
4488
+ updatedAt: {
4489
+ format: 'date-time',
4490
+ type: 'string',
4491
+ description: 'Updated timestamp'
3922
4492
  }
3923
4493
  },
3924
- required: ['exportedAt', 'userId', 'ruleCount', 'rules']
4494
+ required: [
4495
+ 'id',
4496
+ 'name',
4497
+ 'narrationKeywords',
4498
+ 'payeeKeywords',
4499
+ 'categoryKeywords',
4500
+ 'methodKeywords',
4501
+ 'matchLogic',
4502
+ 'priority',
4503
+ 'enabled',
4504
+ 'autoApplyEnabled',
4505
+ 'confirmationCount',
4506
+ 'additionalTags',
4507
+ 'createdAt',
4508
+ 'updatedAt'
4509
+ ]
3925
4510
  } as const;
3926
4511
 
3927
- export const $RuleStatisticsResponseDto = {
4512
+ export const $TransactionRuleListResponseDto = {
3928
4513
  type: 'object',
3929
4514
  properties: {
3930
- period: {
3931
- type: 'string',
3932
- description: 'Statistics time period',
3933
- enum: ['7d', '30d', '90d']
3934
- },
3935
- totalRules: {
3936
- type: 'number',
3937
- description: 'Total number of rules'
4515
+ data: {
4516
+ type: 'array',
4517
+ items: {
4518
+ $ref: '#/components/schemas/TransactionRuleResponseDto'
4519
+ }
3938
4520
  },
3939
- rulesWithMatches: {
4521
+ total: {
3940
4522
  type: 'number',
3941
- description: 'Number of rules with at least one match'
4523
+ description: 'Total count of rules'
3942
4524
  },
3943
- totalMatches: {
4525
+ limit: {
3944
4526
  type: 'number',
3945
- description: 'Total number of matches across all rules'
4527
+ description: 'Results per page'
3946
4528
  },
3947
- averageConfidence: {
4529
+ offset: {
3948
4530
  type: 'number',
3949
- description: 'Average confidence score across all matches',
3950
- example: 0.82
3951
- },
3952
- ruleStats: {
3953
- type: 'array',
3954
- description: 'Per-rule statistics',
3955
- items: {
3956
- type: 'object',
3957
- properties: {
3958
- ruleId: {
3959
- type: 'string'
3960
- },
3961
- ruleName: {
3962
- type: 'string'
3963
- },
3964
- matchCount: {
3965
- type: 'number'
3966
- },
3967
- averageConfidence: {
3968
- type: 'number'
3969
- }
3970
- }
3971
- }
4531
+ description: 'Pagination offset'
3972
4532
  }
3973
4533
  },
3974
- required: [
3975
- 'period',
3976
- 'totalRules',
3977
- 'rulesWithMatches',
3978
- 'totalMatches',
3979
- 'averageConfidence',
3980
- 'ruleStats'
3981
- ]
4534
+ required: ['data', 'total', 'limit', 'offset']
3982
4535
  } as const;
3983
4536
 
3984
- export const $UpdateTransactionRuleDto = {
4537
+ export const $ValidateRuleDto = {
3985
4538
  type: 'object',
3986
4539
  properties: {
3987
4540
  name: {
@@ -4030,7 +4583,8 @@ export const $UpdateTransactionRuleDto = {
4030
4583
  },
4031
4584
  matchLogic: {
4032
4585
  type: 'string',
4033
- enum: ['OR', 'AND']
4586
+ enum: ['OR', 'AND'],
4587
+ default: 'OR'
4034
4588
  },
4035
4589
  amountMin: {
4036
4590
  type: 'number',
@@ -4044,13 +4598,10 @@ export const $UpdateTransactionRuleDto = {
4044
4598
  },
4045
4599
  priority: {
4046
4600
  type: 'number',
4601
+ default: 50,
4047
4602
  minimum: 0,
4048
4603
  maximum: 1000
4049
4604
  },
4050
- enabled: {
4051
- type: 'boolean',
4052
- description: 'Enable or disable the rule'
4053
- },
4054
4605
  additionalTags: {
4055
4606
  items: {
4056
4607
  type: 'array'
@@ -4060,20 +4611,277 @@ export const $UpdateTransactionRuleDto = {
4060
4611
  },
4061
4612
  additionalMetadata: {
4062
4613
  type: 'object'
4614
+ },
4615
+ upsertByPayee: {
4616
+ type: 'boolean',
4617
+ description:
4618
+ 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
4063
4619
  }
4064
- }
4620
+ },
4621
+ required: ['name', 'matchLogic', 'priority']
4065
4622
  } as const;
4066
4623
 
4067
- export const $TestRuleDto = {
4624
+ export const $ValidateRuleResponseDto = {
4068
4625
  type: 'object',
4069
4626
  properties: {
4070
- narration: {
4071
- type: 'string',
4072
- minLength: 1,
4073
- maxLength: 500
4627
+ valid: {
4628
+ type: 'boolean',
4629
+ description: 'Whether the rule configuration is valid',
4630
+ example: true
4074
4631
  },
4075
- payee: {
4076
- type: 'string',
4632
+ errors: {
4633
+ description: 'List of validation errors (empty if valid)',
4634
+ example: [],
4635
+ items: {
4636
+ type: 'array'
4637
+ },
4638
+ type: 'array'
4639
+ },
4640
+ warnings: {
4641
+ description: 'List of validation warnings (non-blocking issues)',
4642
+ example: [
4643
+ 'No account constraints specified - rule will match any account'
4644
+ ],
4645
+ items: {
4646
+ type: 'array'
4647
+ },
4648
+ type: 'array'
4649
+ }
4650
+ },
4651
+ required: ['valid', 'errors', 'warnings']
4652
+ } as const;
4653
+
4654
+ export const $BulkCreateRulesDto = {
4655
+ type: 'object',
4656
+ properties: {
4657
+ rules: {
4658
+ items: {
4659
+ type: 'array'
4660
+ },
4661
+ description: 'Array of rules to import',
4662
+ type: 'array'
4663
+ },
4664
+ conflictStrategy: {
4665
+ type: 'string',
4666
+ enum: ['replace', 'skip'],
4667
+ default: 'skip',
4668
+ description:
4669
+ 'Conflict handling strategy: skip (default) ignores duplicates, replace soft-deletes existing rule'
4670
+ }
4671
+ },
4672
+ required: ['rules', 'conflictStrategy']
4673
+ } as const;
4674
+
4675
+ export const $BulkCreateRulesResponseDto = {
4676
+ type: 'object',
4677
+ properties: {
4678
+ successCount: {
4679
+ type: 'number',
4680
+ description: 'Number of successfully created rules'
4681
+ },
4682
+ failureCount: {
4683
+ type: 'number',
4684
+ description: 'Number of failed rules'
4685
+ },
4686
+ errors: {
4687
+ type: 'array',
4688
+ description: 'Error details for failed rules',
4689
+ items: {
4690
+ type: 'object',
4691
+ properties: {
4692
+ index: {
4693
+ type: 'number'
4694
+ },
4695
+ message: {
4696
+ type: 'string'
4697
+ }
4698
+ }
4699
+ }
4700
+ },
4701
+ createdRuleIds: {
4702
+ description: 'IDs of successfully created rules',
4703
+ type: 'array',
4704
+ items: {
4705
+ type: 'string'
4706
+ }
4707
+ }
4708
+ },
4709
+ required: ['successCount', 'failureCount', 'errors', 'createdRuleIds']
4710
+ } as const;
4711
+
4712
+ export const $ExportRulesResponseDto = {
4713
+ type: 'object',
4714
+ properties: {
4715
+ exportedAt: {
4716
+ type: 'string',
4717
+ description: 'Export timestamp'
4718
+ },
4719
+ userId: {
4720
+ type: 'string',
4721
+ description: 'User ID'
4722
+ },
4723
+ ruleCount: {
4724
+ type: 'number',
4725
+ description: 'Number of exported rules'
4726
+ },
4727
+ rules: {
4728
+ type: 'array',
4729
+ description: 'Exported rules'
4730
+ }
4731
+ },
4732
+ required: ['exportedAt', 'userId', 'ruleCount', 'rules']
4733
+ } as const;
4734
+
4735
+ export const $RuleStatisticsResponseDto = {
4736
+ type: 'object',
4737
+ properties: {
4738
+ period: {
4739
+ type: 'string',
4740
+ description: 'Statistics time period',
4741
+ enum: ['7d', '30d', '90d']
4742
+ },
4743
+ totalRules: {
4744
+ type: 'number',
4745
+ description: 'Total number of rules'
4746
+ },
4747
+ rulesWithMatches: {
4748
+ type: 'number',
4749
+ description: 'Number of rules with at least one match'
4750
+ },
4751
+ totalMatches: {
4752
+ type: 'number',
4753
+ description: 'Total number of matches across all rules'
4754
+ },
4755
+ averageConfidence: {
4756
+ type: 'number',
4757
+ description: 'Average confidence score across all matches',
4758
+ example: 0.82
4759
+ },
4760
+ ruleStats: {
4761
+ type: 'array',
4762
+ description: 'Per-rule statistics',
4763
+ items: {
4764
+ type: 'object',
4765
+ properties: {
4766
+ ruleId: {
4767
+ type: 'string'
4768
+ },
4769
+ ruleName: {
4770
+ type: 'string'
4771
+ },
4772
+ matchCount: {
4773
+ type: 'number'
4774
+ },
4775
+ averageConfidence: {
4776
+ type: 'number'
4777
+ }
4778
+ }
4779
+ }
4780
+ }
4781
+ },
4782
+ required: [
4783
+ 'period',
4784
+ 'totalRules',
4785
+ 'rulesWithMatches',
4786
+ 'totalMatches',
4787
+ 'averageConfidence',
4788
+ 'ruleStats'
4789
+ ]
4790
+ } as const;
4791
+
4792
+ export const $UpdateTransactionRuleDto = {
4793
+ type: 'object',
4794
+ properties: {
4795
+ name: {
4796
+ type: 'string',
4797
+ minLength: 1,
4798
+ maxLength: 100
4799
+ },
4800
+ description: {
4801
+ type: 'string',
4802
+ maxLength: 500
4803
+ },
4804
+ narrationKeywords: {
4805
+ items: {
4806
+ type: 'array'
4807
+ },
4808
+ maxItems: 50,
4809
+ type: 'array'
4810
+ },
4811
+ payeeKeywords: {
4812
+ items: {
4813
+ type: 'array'
4814
+ },
4815
+ maxItems: 50,
4816
+ type: 'array'
4817
+ },
4818
+ categoryKeywords: {
4819
+ items: {
4820
+ type: 'array'
4821
+ },
4822
+ maxItems: 50,
4823
+ type: 'array'
4824
+ },
4825
+ methodKeywords: {
4826
+ items: {
4827
+ type: 'array'
4828
+ },
4829
+ maxItems: 50,
4830
+ description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4831
+ type: 'array'
4832
+ },
4833
+ categoryAccount: {
4834
+ type: 'string',
4835
+ maxLength: 200,
4836
+ description:
4837
+ 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4838
+ },
4839
+ matchLogic: {
4840
+ type: 'string',
4841
+ enum: ['OR', 'AND']
4842
+ },
4843
+ amountMin: {
4844
+ type: 'number',
4845
+ minimum: 0,
4846
+ description: 'Minimum transaction amount (inclusive)'
4847
+ },
4848
+ amountMax: {
4849
+ type: 'number',
4850
+ minimum: 0,
4851
+ description: 'Maximum transaction amount (inclusive)'
4852
+ },
4853
+ priority: {
4854
+ type: 'number',
4855
+ minimum: 0,
4856
+ maximum: 1000
4857
+ },
4858
+ enabled: {
4859
+ type: 'boolean',
4860
+ description: 'Enable or disable the rule'
4861
+ },
4862
+ additionalTags: {
4863
+ items: {
4864
+ type: 'array'
4865
+ },
4866
+ maxItems: 20,
4867
+ type: 'array'
4868
+ },
4869
+ additionalMetadata: {
4870
+ type: 'object'
4871
+ }
4872
+ }
4873
+ } as const;
4874
+
4875
+ export const $TestRuleDto = {
4876
+ type: 'object',
4877
+ properties: {
4878
+ narration: {
4879
+ type: 'string',
4880
+ minLength: 1,
4881
+ maxLength: 500
4882
+ },
4883
+ payee: {
4884
+ type: 'string',
4077
4885
  maxLength: 200
4078
4886
  },
4079
4887
  categoryAccount: {
@@ -4120,151 +4928,393 @@ export const $TestRuleResponseDto = {
4120
4928
  required: ['ruleId', 'matches', 'confidence', 'matchDetails']
4121
4929
  } as const;
4122
4930
 
4123
- export const $DeleteOwnUserDto = {
4931
+ export const $CreateBeanEventDto = {
4124
4932
  type: 'object',
4125
4933
  properties: {
4126
- accessToken: {
4934
+ date: {
4127
4935
  type: 'string',
4128
- description: 'Access token for user verification',
4129
- example: 'abc123xyz'
4936
+ description: 'Life event date (ISO 8601)',
4937
+ example: '2024-03-15'
4938
+ },
4939
+ type: {
4940
+ type: 'string',
4941
+ description:
4942
+ 'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
4943
+ example: 'employer'
4944
+ },
4945
+ description: {
4946
+ type: 'string',
4947
+ description:
4948
+ 'Life event description. Empty string is a VALID value (distinct from absence).',
4949
+ example: 'Acme Corp'
4950
+ },
4951
+ meta: {
4952
+ type: 'object',
4953
+ description:
4954
+ 'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
4955
+ example: {
4956
+ note: 'Promotion'
4957
+ }
4130
4958
  }
4131
4959
  },
4132
- required: ['accessToken']
4960
+ required: ['date', 'type', 'description']
4133
4961
  } as const;
4134
4962
 
4135
- export const $SignupDto = {
4963
+ export const $EventResponseDto = {
4136
4964
  type: 'object',
4137
4965
  properties: {
4138
- turnstileToken: {
4966
+ id: {
4967
+ type: 'string',
4968
+ description: 'Unique identifier',
4969
+ example: 'uuid-123-456'
4970
+ },
4971
+ userId: {
4972
+ type: 'string',
4973
+ description: 'User ID (owner of the life event)',
4974
+ example: 'user-123'
4975
+ },
4976
+ date: {
4977
+ type: 'string',
4978
+ description: 'Life event date (ISO 8601 format)',
4979
+ example: '2024-03-15',
4980
+ format: 'date'
4981
+ },
4982
+ type: {
4139
4983
  type: 'string',
4140
4984
  description:
4141
- 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4142
- example: '0.abc123def456...'
4985
+ 'Life event type (user-defined, e.g., "employer", "location")',
4986
+ example: 'employer'
4987
+ },
4988
+ description: {
4989
+ type: 'string',
4990
+ description:
4991
+ 'Life event description. May be an empty string (a valid value distinct from absence).',
4992
+ example: 'Acme Corp'
4993
+ },
4994
+ meta: {
4995
+ type: 'object',
4996
+ description: 'Product-side metadata (free-form JSON)',
4997
+ example: {
4998
+ note: 'Promotion'
4999
+ }
5000
+ },
5001
+ createdAt: {
5002
+ format: 'date-time',
5003
+ type: 'string',
5004
+ description: 'Creation timestamp',
5005
+ example: '2024-03-15T10:00:00Z'
5006
+ },
5007
+ updatedAt: {
5008
+ format: 'date-time',
5009
+ type: 'string',
5010
+ description:
5011
+ 'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
5012
+ example: '2024-03-15T10:00:00Z'
4143
5013
  }
4144
- }
5014
+ },
5015
+ required: [
5016
+ 'id',
5017
+ 'userId',
5018
+ 'date',
5019
+ 'type',
5020
+ 'description',
5021
+ 'meta',
5022
+ 'createdAt',
5023
+ 'updatedAt'
5024
+ ]
4145
5025
  } as const;
4146
5026
 
4147
- export const $UpdateUserSettingDto = {
5027
+ export const $EventListResponseDto = {
4148
5028
  type: 'object',
4149
5029
  properties: {
4150
- secId: {
4151
- type: 'number',
4152
- description: 'Security ID'
5030
+ items: {
5031
+ description: 'List of life events',
5032
+ type: 'array',
5033
+ items: {
5034
+ $ref: '#/components/schemas/EventResponseDto'
5035
+ }
4153
5036
  },
4154
- annualInterestRate: {
5037
+ total: {
4155
5038
  type: 'number',
4156
- description: 'Annual interest rate',
4157
- example: 0.05
5039
+ description: 'Total number of life events matching the query',
5040
+ example: 42
5041
+ }
5042
+ },
5043
+ required: ['items', 'total']
5044
+ } as const;
5045
+
5046
+ export const $UpdateBeanEventDto = {
5047
+ type: 'object',
5048
+ properties: {
5049
+ date: {
5050
+ type: 'string',
5051
+ description: 'Life event date (ISO 8601)'
5052
+ },
5053
+ type: {
5054
+ type: 'string',
5055
+ description: 'Life event type (user-defined)'
5056
+ },
5057
+ description: {
5058
+ type: 'string',
5059
+ description:
5060
+ 'Life event description. Empty string is a VALID value (distinct from absence).'
5061
+ },
5062
+ meta: {
5063
+ type: 'object',
5064
+ description: 'Product-side metadata (free-form JSON)'
5065
+ }
5066
+ }
5067
+ } as const;
5068
+
5069
+ export const $OnboardingAccountDto = {
5070
+ type: 'object',
5071
+ properties: {
5072
+ path: {
5073
+ type: 'string',
5074
+ description:
5075
+ 'Account path (Assets/Liabilities only; format validated by the account service)',
5076
+ example: 'Assets:Checking'
4158
5077
  },
4159
5078
  currency: {
4160
5079
  type: 'string',
4161
- description: 'Currency code',
5080
+ description: 'ISO 4217 currency code (3 letters)',
4162
5081
  example: 'USD'
4163
5082
  },
4164
- baseCurrency: {
5083
+ openingBalance: {
4165
5084
  type: 'string',
4166
- description: 'Base currency code',
4167
- example: 'USD'
5085
+ description:
5086
+ 'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
5087
+ example: '1000.00'
4168
5088
  },
4169
- benchmark: {
5089
+ platformId: {
4170
5090
  type: 'string',
4171
- description: 'Benchmark symbol',
4172
- example: 'SPY'
5091
+ description:
5092
+ 'Platform ID to bind the account to (references Platform.id); omit for unbound',
5093
+ example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
5094
+ }
5095
+ },
5096
+ required: ['path', 'currency']
5097
+ } as const;
5098
+
5099
+ export const $OnboardingDto = {
5100
+ type: 'object',
5101
+ properties: {
5102
+ accounts: {
5103
+ description: 'Asset/Liability accounts to register with opening balances',
5104
+ type: 'array',
5105
+ items: {
5106
+ $ref: '#/components/schemas/OnboardingAccountDto'
5107
+ }
4173
5108
  },
4174
- colorScheme: {
5109
+ skipAssetRegistration: {
5110
+ type: 'boolean',
5111
+ description:
5112
+ 'Skip asset registration; only bootstrap the core account set',
5113
+ default: false
5114
+ }
5115
+ }
5116
+ } as const;
5117
+
5118
+ export const $ActualBalanceDto = {
5119
+ type: 'object',
5120
+ properties: {
5121
+ amount: {
4175
5122
  type: 'string',
4176
- description: 'Color scheme',
4177
- enum: ['DARK', 'LIGHT']
5123
+ description:
5124
+ 'Actual balance amount as a decimal string (preserves precision for tolerance inference).',
5125
+ example: '1234.56'
5126
+ },
5127
+ ccy: {
5128
+ type: 'string',
5129
+ description: 'Currency code (ISO 4217 or commodity ticker).',
5130
+ example: 'CNY'
5131
+ }
5132
+ },
5133
+ required: ['amount', 'ccy']
5134
+ } as const;
5135
+
5136
+ export const $ComputeReconciliationDto = {
5137
+ type: 'object',
5138
+ properties: {
5139
+ accountId: {
5140
+ type: 'string',
5141
+ description: 'BeanAccount id to reconcile.'
5142
+ },
5143
+ asOfDate: {
5144
+ type: 'string',
5145
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5146
+ example: '2026-07-24'
5147
+ },
5148
+ actualBalance: {
5149
+ description: 'Actual balance from the external statement.',
5150
+ allOf: [
5151
+ {
5152
+ $ref: '#/components/schemas/ActualBalanceDto'
5153
+ }
5154
+ ]
5155
+ }
5156
+ },
5157
+ required: ['accountId', 'asOfDate', 'actualBalance']
5158
+ } as const;
5159
+
5160
+ export const $ReconciliationComputeResultDto = {
5161
+ type: 'object',
5162
+ properties: {
5163
+ accountId: {
5164
+ type: 'string'
5165
+ },
5166
+ asOfDate: {
5167
+ type: 'string'
5168
+ },
5169
+ bookBalance: {
5170
+ type: 'string',
5171
+ description: 'System-computed book balance (decimal string).'
5172
+ },
5173
+ actualBalance: {
5174
+ type: 'string',
5175
+ description: 'User-entered actual balance (decimal string).'
5176
+ },
5177
+ currency: {
5178
+ type: 'string'
4178
5179
  },
4179
- dateRange: {
5180
+ diff: {
4180
5181
  type: 'string',
4181
- description: 'Date range filter',
4182
- example: '1y'
4183
- },
4184
- emergencyFund: {
4185
- type: 'number',
4186
- description: 'Emergency fund amount',
4187
- example: 10000
5182
+ description: 'Diff = book − actual (decimal string).'
4188
5183
  },
4189
- 'filters.accounts': {
4190
- description: 'Account filter IDs',
4191
- type: 'array',
4192
- items: {
4193
- type: 'string'
4194
- }
5184
+ tolerance: {
5185
+ type: 'string',
5186
+ description: 'Applied tolerance (decimal string).'
4195
5187
  },
4196
- 'filters.assetClasses': {
4197
- description: 'Asset class filters',
4198
- type: 'array',
4199
- items: {
4200
- type: 'string'
4201
- }
5188
+ withinTolerance: {
5189
+ type: 'boolean',
5190
+ description: 'true when |diff| ≤ tolerance.'
4202
5191
  },
4203
- 'filters.dataSource': {
5192
+ suggestedAction: {
4204
5193
  type: 'string',
4205
- description: 'Data source filter'
5194
+ enum: ['assert', 'pad'],
5195
+ description:
5196
+ 'Suggested next action: assert when within tolerance, pad otherwise.'
5197
+ }
5198
+ },
5199
+ required: [
5200
+ 'accountId',
5201
+ 'asOfDate',
5202
+ 'bookBalance',
5203
+ 'actualBalance',
5204
+ 'currency',
5205
+ 'diff',
5206
+ 'tolerance',
5207
+ 'withinTolerance',
5208
+ 'suggestedAction'
5209
+ ]
5210
+ } as const;
5211
+
5212
+ export const $AssertReconciliationDto = {
5213
+ type: 'object',
5214
+ properties: {
5215
+ accountId: {
5216
+ type: 'string',
5217
+ description: 'BeanAccount id to reconcile.'
4206
5218
  },
4207
- 'filters.symbol': {
5219
+ asOfDate: {
4208
5220
  type: 'string',
4209
- description: 'Symbol filter'
5221
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5222
+ example: '2026-07-24'
4210
5223
  },
4211
- 'filters.tags': {
4212
- description: 'Tag filters',
4213
- type: 'array',
4214
- items: {
4215
- type: 'string'
4216
- }
5224
+ actualBalance: {
5225
+ description: 'Actual balance from the external statement.',
5226
+ allOf: [
5227
+ {
5228
+ $ref: '#/components/schemas/ActualBalanceDto'
5229
+ }
5230
+ ]
4217
5231
  },
4218
- isExperimentalFeatures: {
4219
- type: 'boolean',
4220
- description: 'Enable experimental features'
5232
+ tolerance: {
5233
+ type: 'string',
5234
+ description:
5235
+ 'Optional explicit tolerance override. Omit to infer from amount precision (Beancount default).',
5236
+ example: '0.01'
5237
+ }
5238
+ },
5239
+ required: ['accountId', 'asOfDate', 'actualBalance']
5240
+ } as const;
5241
+
5242
+ export const $ReconciliationRecordDto = {
5243
+ type: 'object',
5244
+ properties: {
5245
+ id: {
5246
+ type: 'string'
4221
5247
  },
4222
- isRestrictedView: {
4223
- type: 'boolean',
4224
- description: 'Enable restricted view mode'
5248
+ accountId: {
5249
+ type: 'string'
4225
5250
  },
4226
- language: {
5251
+ date: {
5252
+ type: 'string'
5253
+ },
5254
+ amount: {
4227
5255
  type: 'string',
4228
- description: 'Language code',
4229
- example: 'en'
5256
+ description: 'Asserted (actual) amount.'
4230
5257
  },
4231
- locale: {
5258
+ currency: {
5259
+ type: 'string'
5260
+ },
5261
+ tolerance: {
5262
+ type: 'string'
5263
+ },
5264
+ diffAmount: {
4232
5265
  type: 'string',
4233
- description: 'Locale code',
4234
- example: 'en-US'
5266
+ description: 'book − actual.'
4235
5267
  },
4236
- projectedTotalAmount: {
4237
- type: 'number',
4238
- description: 'Projected total amount',
4239
- example: 1000000
5268
+ diffCurrency: {
5269
+ type: 'string'
4240
5270
  },
4241
- retirementDate: {
5271
+ createdAt: {
5272
+ type: 'string'
5273
+ }
5274
+ },
5275
+ required: ['id', 'accountId', 'date', 'amount', 'currency', 'createdAt']
5276
+ } as const;
5277
+
5278
+ export const $PadReconciliationDto = {
5279
+ type: 'object',
5280
+ properties: {
5281
+ accountId: {
4242
5282
  type: 'string',
4243
- description: 'Retirement date in ISO 8601 format',
4244
- example: '2050-01-01'
5283
+ description: 'BeanAccount id to reconcile.'
4245
5284
  },
4246
- savingsRate: {
4247
- type: 'number',
4248
- description: 'Savings rate percentage',
4249
- example: 0.2
5285
+ asOfDate: {
5286
+ type: 'string',
5287
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5288
+ example: '2026-07-24'
4250
5289
  },
4251
- viewMode: {
5290
+ actualBalance: {
5291
+ description: 'Actual balance from the external statement.',
5292
+ allOf: [
5293
+ {
5294
+ $ref: '#/components/schemas/ActualBalanceDto'
5295
+ }
5296
+ ]
5297
+ },
5298
+ sourceAccount: {
4252
5299
  type: 'string',
4253
- description: 'View mode',
4254
- enum: ['DEFAULT', 'ZEN']
5300
+ description:
5301
+ 'Pad source account. Defaults to Equity:Opening-Balances (official Beancount convention).',
5302
+ example: 'Equity:Opening-Balances',
5303
+ default: 'Equity:Opening-Balances'
4255
5304
  }
4256
- }
5305
+ },
5306
+ required: ['accountId', 'asOfDate', 'actualBalance']
4257
5307
  } as const;
4258
5308
 
4259
- export const $UpdatePropertyDto = {
5309
+ export const $PadResultDto = {
4260
5310
  type: 'object',
4261
5311
  properties: {
4262
- value: {
5312
+ transactionId: {
4263
5313
  type: 'string',
4264
- description: 'Property value'
5314
+ description: 'Created pad adjusting transaction id.'
4265
5315
  }
4266
5316
  },
4267
- required: ['value']
5317
+ required: ['transactionId']
4268
5318
  } as const;
4269
5319
 
4270
5320
  export const $FileImportDto = {
@@ -4433,7 +5483,7 @@ export const $IdentifyResultDto = {
4433
5483
  account: {
4434
5484
  type: 'string',
4435
5485
  description: 'Default account used by this importer',
4436
- example: 'Assets:Alipay:Balance'
5486
+ example: 'Assets:CN:Alipay:Balance'
4437
5487
  },
4438
5488
  message: {
4439
5489
  type: 'string',
@@ -4450,7 +5500,7 @@ export const $MapperDefaultsDto = {
4450
5500
  sourceAccount: {
4451
5501
  type: 'string',
4452
5502
  description: 'Source account for transactions (Beancount format)',
4453
- example: 'Assets:Alipay:Balance'
5503
+ example: 'Assets:CN:Alipay:Balance'
4454
5504
  },
4455
5505
  currency: {
4456
5506
  type: 'string',
@@ -4487,7 +5537,7 @@ export const $MapperDefaultsDto = {
4487
5537
  description:
4488
5538
  'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
4489
5539
  example: {
4490
- HuaBei: 'Liabilities:Alipay:Huabei',
5540
+ HuaBei: 'Liabilities:CN:CreditLine',
4491
5541
  CreditCard: 'Liabilities:CreditCard'
4492
5542
  }
4493
5543
  }
@@ -4619,8 +5669,9 @@ export const $UpdateMapperDefaultsDto = {
4619
5669
  sourceAccount: {
4620
5670
  type: 'string',
4621
5671
  description: 'Source account for transactions (Beancount format)',
4622
- example: 'Assets:Alipay:Balance',
4623
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5672
+ example: 'Assets:CN:Alipay:Balance',
5673
+ pattern:
5674
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4624
5675
  },
4625
5676
  currency: {
4626
5677
  type: 'string',
@@ -4634,20 +5685,22 @@ export const $UpdateMapperDefaultsDto = {
4634
5685
  type: 'string',
4635
5686
  description: 'Default expense account (optional)',
4636
5687
  example: 'Expenses:Unknown',
4637
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5688
+ pattern:
5689
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4638
5690
  },
4639
5691
  incomeAccount: {
4640
5692
  type: 'string',
4641
5693
  description: 'Default income account (optional)',
4642
5694
  example: 'Income:Unknown',
4643
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5695
+ pattern:
5696
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4644
5697
  },
4645
5698
  methodAccountMapping: {
4646
5699
  type: 'object',
4647
5700
  description:
4648
5701
  'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
4649
5702
  example: {
4650
- HuaBei: 'Liabilities:Alipay:Huabei',
5703
+ HuaBei: 'Liabilities:CN:CreditLine',
4651
5704
  CreditCard: 'Liabilities:CreditCard'
4652
5705
  }
4653
5706
  }
@@ -4682,119 +5735,13 @@ export const $UpdateImporterConfigDto = {
4682
5735
  }
4683
5736
  } as const;
4684
5737
 
4685
- export const $CreatePlatformDto = {
4686
- type: 'object',
4687
- properties: {
4688
- name: {
4689
- type: 'string',
4690
- description: 'Platform name',
4691
- example: 'Binance'
4692
- },
4693
- canonical: {
4694
- type: 'string',
4695
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4696
- example: 'binance'
4697
- },
4698
- aliases: {
4699
- description: 'Platform aliases (multi-language names for lookup)',
4700
- example: ['Binance', 'Binance Exchange', 'BNB'],
4701
- type: 'array',
4702
- items: {
4703
- type: 'string'
4704
- }
4705
- },
4706
- url: {
4707
- type: 'string',
4708
- description: 'Platform URL',
4709
- example: 'https://www.binance.com'
4710
- },
4711
- type: {
4712
- type: 'string',
4713
- description: 'Platform type',
4714
- enum: [
4715
- 'BANK',
4716
- 'BROKERAGE',
4717
- 'CRYPTO_EXCHANGE',
4718
- 'PAYMENT',
4719
- 'INVESTMENT',
4720
- 'INSURANCE',
4721
- 'OTHER'
4722
- ],
4723
- example: 'CRYPTO_EXCHANGE'
4724
- },
4725
- logoUrl: {
4726
- type: 'string',
4727
- description: 'Platform logo URL',
4728
- example: 'https://example.com/logos/binance.png'
4729
- },
4730
- isActive: {
4731
- type: 'boolean',
4732
- description: 'Whether the platform is active',
4733
- default: true
4734
- }
4735
- },
4736
- required: ['name', 'canonical', 'aliases', 'url', 'type']
4737
- } as const;
4738
-
4739
- export const $UpdatePlatformDto = {
4740
- type: 'object',
4741
- properties: {
4742
- name: {
4743
- type: 'string',
4744
- description: 'Platform name',
4745
- example: 'Binance'
4746
- },
4747
- canonical: {
4748
- type: 'string',
4749
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4750
- example: 'binance'
4751
- },
4752
- aliases: {
4753
- description: 'Platform aliases (multi-language names for lookup)',
4754
- example: ['Binance', 'Binance Exchange', 'BNB'],
4755
- type: 'array',
4756
- items: {
4757
- type: 'string'
4758
- }
4759
- },
4760
- url: {
4761
- type: 'string',
4762
- description: 'Platform URL',
4763
- example: 'https://www.binance.com'
4764
- },
4765
- type: {
4766
- type: 'string',
4767
- description: 'Platform type',
4768
- enum: [
4769
- 'BANK',
4770
- 'BROKERAGE',
4771
- 'CRYPTO_EXCHANGE',
4772
- 'PAYMENT',
4773
- 'INVESTMENT',
4774
- 'INSURANCE',
4775
- 'OTHER'
4776
- ],
4777
- example: 'CRYPTO_EXCHANGE'
4778
- },
4779
- logoUrl: {
4780
- type: 'string',
4781
- description: 'Platform logo URL',
4782
- example: 'https://example.com/logos/binance.png'
4783
- },
4784
- isActive: {
4785
- type: 'boolean',
4786
- description: 'Whether the platform is active'
4787
- }
4788
- }
4789
- } as const;
4790
-
4791
5738
  export const $ProviderSyncConfigDto = {
4792
5739
  type: 'object',
4793
5740
  properties: {
4794
5741
  sourceAccount: {
4795
5742
  type: 'string',
4796
5743
  description: 'Source account for the first posting',
4797
- example: 'Assets:Bank:Chase'
5744
+ example: 'Assets:US:Chase:Checking'
4798
5745
  },
4799
5746
  defaultCurrency: {
4800
5747
  type: 'string',
@@ -4803,26 +5750,29 @@ export const $ProviderSyncConfigDto = {
4803
5750
  },
4804
5751
  defaultExpenseAccount: {
4805
5752
  type: 'string',
4806
- description: 'Default expense account for the second posting',
5753
+ description:
5754
+ 'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4807
5755
  example: 'Expenses:Unknown'
4808
5756
  },
4809
5757
  defaultIncomeAccount: {
4810
5758
  type: 'string',
4811
- description: 'Default income account for the second posting',
5759
+ description:
5760
+ 'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4812
5761
  example: 'Income:Unknown'
4813
5762
  },
4814
5763
  filterPending: {
4815
5764
  type: 'boolean',
4816
5765
  description: 'Filter pending transactions',
4817
5766
  default: true
5767
+ },
5768
+ externalAccountId: {
5769
+ type: 'string',
5770
+ description:
5771
+ 'External account ID for per-batch providers (e.g. GoCardless). Overrides sourceAccount when an ExternalAccountLink mapping exists.',
5772
+ example: 'acc_gocardless_001'
4818
5773
  }
4819
5774
  },
4820
- required: [
4821
- 'sourceAccount',
4822
- 'defaultCurrency',
4823
- 'defaultExpenseAccount',
4824
- 'defaultIncomeAccount'
4825
- ]
5775
+ required: ['sourceAccount', 'defaultCurrency']
4826
5776
  } as const;
4827
5777
 
4828
5778
  export const $ProviderSyncDto = {
@@ -4927,11 +5877,99 @@ export const $SupportedProvidersResponseDto = {
4927
5877
  ],
4928
5878
  type: 'array',
4929
5879
  items: {
4930
- type: 'string'
5880
+ type: 'string'
5881
+ }
5882
+ }
5883
+ },
5884
+ required: ['providers']
5885
+ } as const;
5886
+
5887
+ export const $CreateExternalAccountLinkDto = {
5888
+ type: 'object',
5889
+ properties: {
5890
+ provider: {
5891
+ type: 'string',
5892
+ enum: [
5893
+ 'plaid',
5894
+ 'teller',
5895
+ 'truelayer',
5896
+ 'gocardless',
5897
+ 'simplefin',
5898
+ 'yodlee',
5899
+ 'beancount-direct',
5900
+ 'parsed-bill'
5901
+ ],
5902
+ example: 'plaid',
5903
+ description: 'Open Banking provider (whitelist)'
5904
+ },
5905
+ externalAccountId: {
5906
+ type: 'string',
5907
+ example: 'acc-plaid-001',
5908
+ description: 'External account ID from the provider'
5909
+ },
5910
+ beanAccountId: {
5911
+ type: 'string',
5912
+ example: '550e8400-e29b-41d4-a716-446655440000',
5913
+ description: 'Target BeanAccount ID (must belong to the JWT user)'
5914
+ }
5915
+ },
5916
+ required: ['provider', 'externalAccountId', 'beanAccountId']
5917
+ } as const;
5918
+
5919
+ export const $ExternalAccountLinkResponseDto = {
5920
+ type: 'object',
5921
+ properties: {
5922
+ id: {
5923
+ type: 'string'
5924
+ },
5925
+ provider: {
5926
+ type: 'string'
5927
+ },
5928
+ externalAccountId: {
5929
+ type: 'string'
5930
+ },
5931
+ beanAccountId: {
5932
+ type: 'string'
5933
+ },
5934
+ isActive: {
5935
+ type: 'boolean'
5936
+ },
5937
+ createdAt: {
5938
+ type: 'string'
5939
+ },
5940
+ updatedAt: {
5941
+ type: 'string'
5942
+ }
5943
+ },
5944
+ required: [
5945
+ 'id',
5946
+ 'provider',
5947
+ 'externalAccountId',
5948
+ 'beanAccountId',
5949
+ 'isActive',
5950
+ 'createdAt',
5951
+ 'updatedAt'
5952
+ ]
5953
+ } as const;
5954
+
5955
+ export const $ExternalAccountLinkListResponseDto = {
5956
+ type: 'object',
5957
+ properties: {
5958
+ items: {
5959
+ type: 'array',
5960
+ items: {
5961
+ $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
4931
5962
  }
5963
+ },
5964
+ total: {
5965
+ type: 'number'
5966
+ },
5967
+ provider: {
5968
+ type: 'string',
5969
+ description: 'Filter by provider (query param)'
4932
5970
  }
4933
5971
  },
4934
- required: ['providers']
5972
+ required: ['items', 'total']
4935
5973
  } as const;
4936
5974
 
4937
5975
  export const $ParserTelemetryReportDto = {
@@ -4949,10 +5987,17 @@ export const $ProcessNlpDto = {
4949
5987
  properties: {
4950
5988
  message: {
4951
5989
  type: 'string',
4952
- description: 'Natural language text describing a transaction (Chinese)',
4953
- example: 'yesterday Starbucks spent 35 yuan',
5990
+ description:
5991
+ 'Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.',
5992
+ example: 'Starbucks 35',
4954
5993
  maxLength: 500
4955
5994
  },
5995
+ confirm: {
5996
+ type: 'boolean',
5997
+ description:
5998
+ 'Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.',
5999
+ example: true
6000
+ },
4956
6001
  sessionId: {
4957
6002
  type: 'string',
4958
6003
  description:
@@ -4968,9 +6013,20 @@ export const $ProcessNlpDto = {
4968
6013
  currency: 'CNY',
4969
6014
  payee: 'Starbucks'
4970
6015
  }
6016
+ },
6017
+ selectedRuleId: {
6018
+ type: 'string',
6019
+ description:
6020
+ '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.',
6021
+ example: 'rule_abc123'
6022
+ },
6023
+ selectedAccount: {
6024
+ type: 'string',
6025
+ description:
6026
+ '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.',
6027
+ example: 'Expenses:Food:Coffee'
4971
6028
  }
4972
- },
4973
- required: ['message']
6029
+ }
4974
6030
  } as const;
4975
6031
 
4976
6032
  export const $NlpTransactionInfoDto = {
@@ -5292,7 +6348,8 @@ export const $NlpAccountConfirmationDataDto = {
5292
6348
  },
5293
6349
  suggestedAccount: {
5294
6350
  type: 'string',
5295
- description: 'Suggested replacement account',
6351
+ description:
6352
+ 'Suggested replacement account (omitted when no clear candidate)',
5296
6353
  example: 'Expenses:Food:Drinks'
5297
6354
  },
5298
6355
  similarAccounts: {
@@ -5314,7 +6371,6 @@ export const $NlpAccountConfirmationDataDto = {
5314
6371
  },
5315
6372
  required: [
5316
6373
  'invalidAccount',
5317
- 'suggestedAccount',
5318
6374
  'similarAccounts',
5319
6375
  'errorMessage',
5320
6376
  'transactionContext'
@@ -5483,11 +6539,12 @@ export const $NlpSuggestedAccountDto = {
5483
6539
  account: {
5484
6540
  type: 'string',
5485
6541
  description: 'Suggested account path',
5486
- example: 'Assets:Bank:Checking'
6542
+ example: 'Assets:Checking'
5487
6543
  },
5488
6544
  confidence: {
5489
6545
  type: 'number',
5490
- description: 'Confidence score for this suggestion (0-1)',
6546
+ description:
6547
+ 'Confidence score for this suggestion (0-1). Present = predicted (confirm/confirm_rule/confirm_account); omitted = actual persisted account (created). (#586)',
5491
6548
  example: 0.9
5492
6549
  }
5493
6550
  },
@@ -5523,23 +6580,31 @@ export const $NlpDefaultAccountsDto = {
5523
6580
  properties: {
5524
6581
  asset: {
5525
6582
  type: 'string',
5526
- description: 'Default asset account',
5527
- example: 'Assets:Bank:Checking'
6583
+ description:
6584
+ 'Default OPEN asset account (MRU when multiple), or null when none/ambiguous',
6585
+ example: 'Assets:Checking',
6586
+ nullable: true
5528
6587
  },
5529
6588
  expense: {
5530
6589
  type: 'string',
5531
- description: 'Default expense account',
5532
- example: 'Expenses:Uncategorized'
6590
+ description:
6591
+ 'Default OPEN expense account (MRU when multiple), or null when none/ambiguous',
6592
+ example: 'Expenses:Food:Coffee',
6593
+ nullable: true
5533
6594
  },
5534
6595
  income: {
5535
6596
  type: 'string',
5536
- description: 'Default income account',
5537
- example: 'Income:Uncategorized'
6597
+ description:
6598
+ 'Default OPEN income account (MRU when multiple), or null when none/ambiguous',
6599
+ example: 'Income:Salary',
6600
+ nullable: true
5538
6601
  },
5539
6602
  liability: {
5540
6603
  type: 'string',
5541
- description: 'Default liability account',
5542
- example: 'Liabilities:CreditCard'
6604
+ description:
6605
+ 'Default OPEN liability account (MRU when multiple), or null when none/ambiguous',
6606
+ example: 'Liabilities:CreditCard',
6607
+ nullable: true
5543
6608
  }
5544
6609
  },
5545
6610
  required: ['asset', 'expense', 'income', 'liability']
@@ -5564,7 +6629,8 @@ export const $NlpResponseDto = {
5564
6629
  'confirm_rule',
5565
6630
  'confirm_account',
5566
6631
  'confirm_payee',
5567
- 'cancel'
6632
+ 'cancel',
6633
+ 'aborted'
5568
6634
  ]
5569
6635
  },
5570
6636
  intent: {
@@ -5726,7 +6792,7 @@ export const $NlpResponseDto = {
5726
6792
  },
5727
6793
  suggestedAccounts: {
5728
6794
  description:
5729
- 'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
6795
+ 'Suggested accounts for this transaction (#586). confirm/confirm_rule/confirm_account: predicted (source/destination carry confidence); created: actual persisted accounts (confidence omitted). confirm_account destination is the suggested replacement, never the invalid account.',
5730
6796
  allOf: [
5731
6797
  {
5732
6798
  $ref: '#/components/schemas/NlpSuggestedAccountsDto'
@@ -5735,7 +6801,7 @@ export const $NlpResponseDto = {
5735
6801
  },
5736
6802
  defaultAccounts: {
5737
6803
  description:
5738
- 'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
6804
+ 'Default fallback accounts for the user/region (#586). v1 returns universal constants; per-user personalization is planned.',
5739
6805
  allOf: [
5740
6806
  {
5741
6807
  $ref: '#/components/schemas/NlpDefaultAccountsDto'
@@ -5743,24 +6809,285 @@ export const $NlpResponseDto = {
5743
6809
  ]
5744
6810
  }
5745
6811
  },
5746
- required: ['status', 'action']
6812
+ required: ['status', 'action']
6813
+ } as const;
6814
+
6815
+ export const $PlatformListItemDto = {
6816
+ type: 'object',
6817
+ properties: {
6818
+ id: {
6819
+ type: 'string',
6820
+ description: 'Global platform ID'
6821
+ },
6822
+ name: {
6823
+ type: 'string',
6824
+ description: 'Platform name'
6825
+ },
6826
+ url: {
6827
+ type: 'string',
6828
+ description: 'Platform URL'
6829
+ },
6830
+ type: {
6831
+ type: 'string',
6832
+ description: 'Platform type',
6833
+ enum: [
6834
+ 'BANK',
6835
+ 'BROKERAGE',
6836
+ 'CRYPTO_EXCHANGE',
6837
+ 'PAYMENT',
6838
+ 'INVESTMENT',
6839
+ 'INSURANCE',
6840
+ 'OTHER'
6841
+ ]
6842
+ },
6843
+ canonical: {
6844
+ type: 'string',
6845
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
6846
+ },
6847
+ suggestedSegment: {
6848
+ type: 'string',
6849
+ description:
6850
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
6851
+ },
6852
+ logoUrl: {
6853
+ type: 'string',
6854
+ description: 'Logo URL',
6855
+ nullable: true
6856
+ },
6857
+ countryCode: {
6858
+ type: 'string',
6859
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
6860
+ example: 'CN',
6861
+ nullable: true
6862
+ },
6863
+ category: {
6864
+ type: 'string',
6865
+ description:
6866
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
6867
+ nullable: true,
6868
+ example: 'DigitalWallet'
6869
+ },
6870
+ isBound: {
6871
+ type: 'boolean',
6872
+ description: 'Whether user has accounts using this platform'
6873
+ }
6874
+ },
6875
+ required: [
6876
+ 'id',
6877
+ 'name',
6878
+ 'url',
6879
+ 'type',
6880
+ 'canonical',
6881
+ 'suggestedSegment',
6882
+ 'logoUrl',
6883
+ 'countryCode',
6884
+ 'category',
6885
+ 'isBound'
6886
+ ]
6887
+ } as const;
6888
+
6889
+ export const $PlatformMatchResultDto = {
6890
+ type: 'object',
6891
+ properties: {
6892
+ id: {
6893
+ type: 'string',
6894
+ description: 'Global platform ID'
6895
+ },
6896
+ name: {
6897
+ type: 'string',
6898
+ description: 'Platform name (e.g., "ICBC")'
6899
+ },
6900
+ canonical: {
6901
+ type: 'string',
6902
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
6903
+ },
6904
+ type: {
6905
+ type: 'string',
6906
+ description: 'Platform type',
6907
+ enum: [
6908
+ 'BANK',
6909
+ 'BROKERAGE',
6910
+ 'CRYPTO_EXCHANGE',
6911
+ 'PAYMENT',
6912
+ 'INVESTMENT',
6913
+ 'INSURANCE',
6914
+ 'OTHER'
6915
+ ]
6916
+ },
6917
+ suggestedSegment: {
6918
+ type: 'string',
6919
+ description:
6920
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
6921
+ },
6922
+ logoUrl: {
6923
+ type: 'string',
6924
+ description: 'Logo URL',
6925
+ nullable: true
6926
+ },
6927
+ countryCode: {
6928
+ type: 'string',
6929
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
6930
+ example: 'CN',
6931
+ nullable: true
6932
+ },
6933
+ category: {
6934
+ type: 'string',
6935
+ description:
6936
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
6937
+ nullable: true,
6938
+ example: 'DigitalWallet'
6939
+ },
6940
+ matchType: {
6941
+ type: 'string',
6942
+ description: "How this row matched: 'exact' > 'prefix' > 'substring'",
6943
+ enum: ['exact', 'prefix', 'substring']
6944
+ }
6945
+ },
6946
+ required: [
6947
+ 'id',
6948
+ 'name',
6949
+ 'canonical',
6950
+ 'type',
6951
+ 'suggestedSegment',
6952
+ 'logoUrl',
6953
+ 'countryCode',
6954
+ 'category',
6955
+ 'matchType'
6956
+ ]
6957
+ } as const;
6958
+
6959
+ export const $PlatformMatchResponseDto = {
6960
+ type: 'object',
6961
+ properties: {
6962
+ platforms: {
6963
+ description: 'Ranked matches, best tier first (at most 10 rows)',
6964
+ type: 'array',
6965
+ items: {
6966
+ $ref: '#/components/schemas/PlatformMatchResultDto'
6967
+ }
6968
+ },
6969
+ matchType: {
6970
+ type: 'string',
6971
+ description:
6972
+ "Overall match quality — top row's tier, or 'none' when no hits",
6973
+ enum: ['none', 'exact', 'prefix', 'substring']
6974
+ },
6975
+ total: {
6976
+ type: 'number',
6977
+ description: 'Total matches before LIMIT (truncation transparency)'
6978
+ },
6979
+ hasMore: {
6980
+ type: 'boolean',
6981
+ description: 'true when total > platforms.length (more matches exist)'
6982
+ }
6983
+ },
6984
+ required: ['platforms', 'matchType', 'total', 'hasMore']
6985
+ } as const;
6986
+
6987
+ export const $CreatePlatformDto = {
6988
+ type: 'object',
6989
+ properties: {
6990
+ name: {
6991
+ type: 'string',
6992
+ description: 'Platform name',
6993
+ example: 'Binance'
6994
+ },
6995
+ canonical: {
6996
+ type: 'string',
6997
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
6998
+ example: 'binance'
6999
+ },
7000
+ aliases: {
7001
+ description: 'Platform aliases (multi-language names for lookup)',
7002
+ example: ['Binance', 'Binance Exchange', 'BNB'],
7003
+ type: 'array',
7004
+ items: {
7005
+ type: 'string'
7006
+ }
7007
+ },
7008
+ url: {
7009
+ type: 'string',
7010
+ description: 'Platform URL',
7011
+ example: 'https://www.binance.com'
7012
+ },
7013
+ type: {
7014
+ type: 'string',
7015
+ description: 'Platform type',
7016
+ enum: [
7017
+ 'BANK',
7018
+ 'BROKERAGE',
7019
+ 'CRYPTO_EXCHANGE',
7020
+ 'PAYMENT',
7021
+ 'INVESTMENT',
7022
+ 'INSURANCE',
7023
+ 'OTHER'
7024
+ ],
7025
+ example: 'CRYPTO_EXCHANGE'
7026
+ },
7027
+ logoUrl: {
7028
+ type: 'string',
7029
+ description: 'Platform logo URL',
7030
+ example: 'https://example.com/logos/binance.png'
7031
+ },
7032
+ isActive: {
7033
+ type: 'boolean',
7034
+ description: 'Whether the platform is active',
7035
+ default: true
7036
+ }
7037
+ },
7038
+ required: ['name', 'canonical', 'aliases', 'url', 'type']
5747
7039
  } as const;
5748
7040
 
5749
- export const $BalanceByCurrencyDto = {
7041
+ export const $UpdatePlatformDto = {
5750
7042
  type: 'object',
5751
7043
  properties: {
5752
- currency: {
7044
+ name: {
5753
7045
  type: 'string',
5754
- description: 'ISO 4217 currency code',
5755
- example: 'CNY'
7046
+ description: 'Platform name',
7047
+ example: 'Binance'
5756
7048
  },
5757
- balance: {
7049
+ canonical: {
5758
7050
  type: 'string',
5759
- description: 'Balance amount',
5760
- example: '50000.00'
7051
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
7052
+ example: 'binance'
7053
+ },
7054
+ aliases: {
7055
+ description: 'Platform aliases (multi-language names for lookup)',
7056
+ example: ['Binance', 'Binance Exchange', 'BNB'],
7057
+ type: 'array',
7058
+ items: {
7059
+ type: 'string'
7060
+ }
7061
+ },
7062
+ url: {
7063
+ type: 'string',
7064
+ description: 'Platform URL',
7065
+ example: 'https://www.binance.com'
7066
+ },
7067
+ type: {
7068
+ type: 'string',
7069
+ description: 'Platform type',
7070
+ enum: [
7071
+ 'BANK',
7072
+ 'BROKERAGE',
7073
+ 'CRYPTO_EXCHANGE',
7074
+ 'PAYMENT',
7075
+ 'INVESTMENT',
7076
+ 'INSURANCE',
7077
+ 'OTHER'
7078
+ ],
7079
+ example: 'CRYPTO_EXCHANGE'
7080
+ },
7081
+ logoUrl: {
7082
+ type: 'string',
7083
+ description: 'Platform logo URL',
7084
+ example: 'https://example.com/logos/binance.png'
7085
+ },
7086
+ isActive: {
7087
+ type: 'boolean',
7088
+ description: 'Whether the platform is active'
5761
7089
  }
5762
- },
5763
- required: ['currency', 'balance']
7090
+ }
5764
7091
  } as const;
5765
7092
 
5766
7093
  export const $NetWorthByCurrencyDto = {
@@ -5832,28 +7159,6 @@ export const $ConvertedNetWorthDto = {
5832
7159
  ]
5833
7160
  } as const;
5834
7161
 
5835
- export const $ExchangeRateWarningDto = {
5836
- type: 'object',
5837
- properties: {
5838
- type: {
5839
- type: 'string',
5840
- description: 'Warning type',
5841
- example: 'MISSING_EXCHANGE_RATE'
5842
- },
5843
- currency: {
5844
- type: 'string',
5845
- description: 'Currency without exchange rate',
5846
- example: 'EUR'
5847
- },
5848
- totalAmount: {
5849
- type: 'string',
5850
- description: 'Total amount affected',
5851
- example: '1000.00'
5852
- }
5853
- },
5854
- required: ['type', 'currency', 'totalAmount']
5855
- } as const;
5856
-
5857
7162
  export const $NetWorthResponseDto = {
5858
7163
  type: 'object',
5859
7164
  properties: {
@@ -5939,7 +7244,7 @@ export const $AccountItemDto = {
5939
7244
  name: {
5940
7245
  type: 'string',
5941
7246
  description: 'Full account name',
5942
- example: 'Assets:Bank:CMB:Savings'
7247
+ example: 'Assets:CN:CMB:Savings'
5943
7248
  },
5944
7249
  displayName: {
5945
7250
  type: 'string',
@@ -5955,6 +7260,12 @@ export const $AccountItemDto = {
5955
7260
  type: 'string',
5956
7261
  description: 'Currency code',
5957
7262
  example: 'CNY'
7263
+ },
7264
+ convertedBalance: {
7265
+ type: 'string',
7266
+ description:
7267
+ 'FX-converted balance in base currency; omitted when not convertible',
7268
+ example: '50000.00'
5958
7269
  }
5959
7270
  },
5960
7271
  required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -5981,11 +7292,66 @@ export const $PlatformGroupDto = {
5981
7292
  },
5982
7293
  totalBalance: {
5983
7294
  type: 'string',
5984
- description: 'Total balance across all accounts in platform',
7295
+ description: 'FX-converted total balance in base currency',
7296
+ example: '100000.00'
7297
+ },
7298
+ balanceByCurrency: {
7299
+ description: 'Raw (unconverted) balances grouped by currency',
7300
+ type: 'array',
7301
+ items: {
7302
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
7303
+ }
7304
+ },
7305
+ convertedBalance: {
7306
+ type: 'string',
7307
+ description:
7308
+ 'Converted balance in base currency (omitted when no currency is convertible)',
5985
7309
  example: '100000.00'
7310
+ },
7311
+ sharePct: {
7312
+ type: 'number',
7313
+ description:
7314
+ 'Share of the grand converted total (0-100); 0 when grand total is 0',
7315
+ example: 42.5
7316
+ }
7317
+ },
7318
+ required: [
7319
+ 'platformId',
7320
+ 'platformName',
7321
+ 'accounts',
7322
+ 'totalBalance',
7323
+ 'balanceByCurrency',
7324
+ 'sharePct'
7325
+ ]
7326
+ } as const;
7327
+
7328
+ export const $AccountExchangeRateWarningDto = {
7329
+ type: 'object',
7330
+ properties: {
7331
+ type: {
7332
+ type: 'string',
7333
+ description: 'Warning type',
7334
+ example: 'MISSING_EXCHANGE_RATE'
7335
+ },
7336
+ currency: {
7337
+ type: 'string',
7338
+ description: 'Currency without exchange rate',
7339
+ example: 'USD'
7340
+ },
7341
+ accounts: {
7342
+ description: 'Affected account paths',
7343
+ type: 'array',
7344
+ items: {
7345
+ type: 'string'
7346
+ }
7347
+ },
7348
+ totalAmount: {
7349
+ type: 'string',
7350
+ description: 'Total amount in this currency',
7351
+ example: '5000.00'
5986
7352
  }
5987
7353
  },
5988
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
7354
+ required: ['type', 'currency', 'accounts', 'totalAmount']
5989
7355
  } as const;
5990
7356
 
5991
7357
  export const $AccountsSummaryDto = {
@@ -5998,9 +7364,21 @@ export const $AccountsSummaryDto = {
5998
7364
  totalPlatforms: {
5999
7365
  type: 'number',
6000
7366
  description: 'Total number of platforms'
7367
+ },
7368
+ baseCurrency: {
7369
+ type: 'string',
7370
+ description: 'Base currency for conversion',
7371
+ example: 'CNY'
7372
+ },
7373
+ warnings: {
7374
+ description: 'Per-account exchange rate warnings',
7375
+ type: 'array',
7376
+ items: {
7377
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
7378
+ }
6001
7379
  }
6002
7380
  },
6003
- required: ['totalAccounts', 'totalPlatforms']
7381
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
6004
7382
  } as const;
6005
7383
 
6006
7384
  export const $AccountsResponseDto = {
@@ -6035,7 +7413,7 @@ export const $AccountItemWithAssetClassDto = {
6035
7413
  name: {
6036
7414
  type: 'string',
6037
7415
  description: 'Full account name',
6038
- example: 'Assets:Bank:CMB:Savings'
7416
+ example: 'Assets:CN:CMB:Savings'
6039
7417
  },
6040
7418
  displayName: {
6041
7419
  type: 'string',
@@ -6052,6 +7430,12 @@ export const $AccountItemWithAssetClassDto = {
6052
7430
  description: 'Currency code',
6053
7431
  example: 'CNY'
6054
7432
  },
7433
+ convertedBalance: {
7434
+ type: 'string',
7435
+ description:
7436
+ 'FX-converted balance in base currency; omitted when not convertible',
7437
+ example: '50000.00'
7438
+ },
6055
7439
  assetClass: {
6056
7440
  type: 'string',
6057
7441
  description: 'Asset class',
@@ -6131,35 +7515,6 @@ export const $AssetClassGroupDto = {
6131
7515
  required: ['assetClass', 'accounts', 'balanceByCurrency']
6132
7516
  } as const;
6133
7517
 
6134
- export const $AccountExchangeRateWarningDto = {
6135
- type: 'object',
6136
- properties: {
6137
- type: {
6138
- type: 'string',
6139
- description: 'Warning type',
6140
- example: 'MISSING_EXCHANGE_RATE'
6141
- },
6142
- currency: {
6143
- type: 'string',
6144
- description: 'Currency without exchange rate',
6145
- example: 'USD'
6146
- },
6147
- accounts: {
6148
- description: 'Affected account paths',
6149
- type: 'array',
6150
- items: {
6151
- type: 'string'
6152
- }
6153
- },
6154
- totalAmount: {
6155
- type: 'string',
6156
- description: 'Total amount in this currency',
6157
- example: '5000.00'
6158
- }
6159
- },
6160
- required: ['type', 'currency', 'accounts', 'totalAmount']
6161
- } as const;
6162
-
6163
7518
  export const $AssetClassSummaryDto = {
6164
7519
  type: 'object',
6165
7520
  properties: {
@@ -6233,7 +7588,7 @@ export const $HoldingAssetClassAccountSliceDto = {
6233
7588
  accountPath: {
6234
7589
  type: 'string',
6235
7590
  description: 'Full account path',
6236
- example: 'Assets:US:Investments:Brokerage'
7591
+ example: 'Assets:US:Fidelity:Brokerage'
6237
7592
  },
6238
7593
  accountCurrency: {
6239
7594
  type: 'string',
@@ -6405,38 +7760,133 @@ export const $CashFlowResponseDto = {
6405
7760
  description: 'Base currency code',
6406
7761
  example: 'CNY'
6407
7762
  },
6408
- byCurrency: {
6409
- description: 'Cash flow grouped by original currency',
6410
- allOf: [
6411
- {
6412
- $ref: '#/components/schemas/CashFlowByCurrencyDto'
6413
- }
6414
- ]
7763
+ byCurrency: {
7764
+ description: 'Cash flow grouped by original currency',
7765
+ allOf: [
7766
+ {
7767
+ $ref: '#/components/schemas/CashFlowByCurrencyDto'
7768
+ }
7769
+ ]
7770
+ },
7771
+ converted: {
7772
+ description: 'Converted values in base currency',
7773
+ allOf: [
7774
+ {
7775
+ $ref: '#/components/schemas/ConvertedCashFlowDto'
7776
+ }
7777
+ ]
7778
+ },
7779
+ warnings: {
7780
+ description: 'Exchange rate warnings',
7781
+ type: 'array',
7782
+ items: {
7783
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
7784
+ }
7785
+ }
7786
+ },
7787
+ required: [
7788
+ 'period',
7789
+ 'income',
7790
+ 'expense',
7791
+ 'netSavings',
7792
+ 'savingsRate',
7793
+ 'currency'
7794
+ ]
7795
+ } as const;
7796
+
7797
+ export const $CategoryGroupDto = {
7798
+ type: 'object',
7799
+ properties: {
7800
+ category: {
7801
+ type: 'string',
7802
+ description:
7803
+ 'Functional category (account-path Group segment); regional and universal account paths merge under it',
7804
+ example: 'Food'
7805
+ },
7806
+ totalExpense: {
7807
+ type: 'string',
7808
+ description:
7809
+ 'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
7810
+ example: '1200.00'
7811
+ },
7812
+ sharePct: {
7813
+ type: 'number',
7814
+ description: 'Share of grand total (0-100); 0 when grand total is 0',
7815
+ example: 42.5
7816
+ },
7817
+ balanceByCurrency: {
7818
+ description: 'Raw (unconverted) expense per currency',
7819
+ type: 'array',
7820
+ items: {
7821
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
7822
+ }
7823
+ },
7824
+ convertedBalance: {
7825
+ type: 'string',
7826
+ description:
7827
+ 'Converted total in base currency (omitted when FX missing for all currencies in this category)',
7828
+ example: '1200.00'
7829
+ }
7830
+ },
7831
+ required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
7832
+ } as const;
7833
+
7834
+ export const $ExpensesByCategorySummaryDto = {
7835
+ type: 'object',
7836
+ properties: {
7837
+ totalExpense: {
7838
+ type: 'string',
7839
+ description:
7840
+ 'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
7841
+ example: '5000.00'
7842
+ },
7843
+ categoryCount: {
7844
+ type: 'number',
7845
+ description: 'Number of categories',
7846
+ example: 8
7847
+ }
7848
+ },
7849
+ required: ['totalExpense', 'categoryCount']
7850
+ } as const;
7851
+
7852
+ export const $ExpensesByCategoryResponseDto = {
7853
+ type: 'object',
7854
+ properties: {
7855
+ period: {
7856
+ type: 'string',
7857
+ description: 'Period requested',
7858
+ example: '1m'
7859
+ },
7860
+ baseCurrency: {
7861
+ type: 'string',
7862
+ description: 'Base currency for converted values',
7863
+ example: 'CNY'
7864
+ },
7865
+ groups: {
7866
+ description:
7867
+ 'Expense groups by functional category, sorted by converted total desc',
7868
+ type: 'array',
7869
+ items: {
7870
+ $ref: '#/components/schemas/CategoryGroupDto'
7871
+ }
6415
7872
  },
6416
- converted: {
6417
- description: 'Converted values in base currency',
7873
+ summary: {
7874
+ description: 'Summary statistics',
6418
7875
  allOf: [
6419
7876
  {
6420
- $ref: '#/components/schemas/ConvertedCashFlowDto'
7877
+ $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
6421
7878
  }
6422
7879
  ]
6423
7880
  },
6424
7881
  warnings: {
6425
- description: 'Exchange rate warnings',
7882
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
6426
7883
  type: 'array',
6427
7884
  items: {
6428
7885
  $ref: '#/components/schemas/ExchangeRateWarningDto'
6429
7886
  }
6430
7887
  }
6431
7888
  },
6432
- required: [
6433
- 'period',
6434
- 'income',
6435
- 'expense',
6436
- 'netSavings',
6437
- 'savingsRate',
6438
- 'currency'
6439
- ]
7889
+ required: ['period', 'baseCurrency', 'groups', 'summary']
6440
7890
  } as const;
6441
7891
 
6442
7892
  export const $MonetaryDto = {
@@ -6653,409 +8103,243 @@ export const $HoldingPnlRowDto = {
6653
8103
  },
6654
8104
  required: [
6655
8105
  'accountId',
6656
- 'accountPath',
6657
- 'symbol',
6658
- 'chartToken',
6659
- 'assetClass',
6660
- 'units'
6661
- ]
6662
- } as const;
6663
-
6664
- export const $HoldingPnlWarningDto = {
6665
- type: 'object',
6666
- properties: {
6667
- type: {
6668
- type: 'string',
6669
- description: 'Warning type',
6670
- example: 'MISSING_COST_FX_RATE',
6671
- enum: [
6672
- 'MISSING_COST_FX_RATE',
6673
- 'MISSING_MARKET_FX_RATE',
6674
- 'MISSING_SALE_PRICE',
6675
- 'MISSING_REALIZED_FX_RATE',
6676
- 'OVERSOLD_LOTS',
6677
- 'NO_PRICE',
6678
- 'MIXED_COST_CURRENCY'
6679
- ]
6680
- },
6681
- symbol: {
6682
- type: 'object',
6683
- nullable: true
6684
- },
6685
- accountId: {
6686
- type: 'object',
6687
- nullable: true
6688
- },
6689
- currency: {
6690
- type: 'object',
6691
- nullable: true
6692
- }
6693
- },
6694
- required: ['type']
6695
- } as const;
6696
-
6697
- export const $HoldingPnlResponseDto = {
6698
- type: 'object',
6699
- properties: {
6700
- asOfDate: {
6701
- type: 'string',
6702
- example: '2026-07-08'
6703
- },
6704
- baseCurrency: {
6705
- type: 'string',
6706
- example: 'CNY'
6707
- },
6708
- method: {
6709
- type: 'string',
6710
- description:
6711
- 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
6712
- enum: ['average', 'FIFO'],
6713
- example: 'average'
6714
- },
6715
- rows: {
6716
- type: 'array',
6717
- items: {
6718
- $ref: '#/components/schemas/HoldingPnlRowDto'
6719
- }
6720
- },
6721
- warnings: {
6722
- type: 'array',
6723
- items: {
6724
- $ref: '#/components/schemas/HoldingPnlWarningDto'
6725
- }
6726
- }
6727
- },
6728
- required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6729
- } as const;
6730
-
6731
- export const $CreateBeanPriceDto = {
6732
- type: 'object',
6733
- properties: {
6734
- currency: {
6735
- type: 'string',
6736
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6737
- example: 'USD'
6738
- },
6739
- quoteCurrency: {
6740
- type: 'string',
6741
- description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
6742
- example: 'CNY'
6743
- },
6744
- amount: {
6745
- type: 'number',
6746
- description:
6747
- 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
6748
- example: 175.5,
6749
- minimum: 0
6750
- },
6751
- date: {
6752
- type: 'string',
6753
- description: 'Price date (ISO 8601 format)',
6754
- example: '2024-11-05'
6755
- },
6756
- metadata: {
6757
- type: 'object',
6758
- description:
6759
- 'Metadata (validated by Zod schema, max field lengths enforced)',
6760
- example: {
6761
- source: 'MANUAL',
6762
- note: 'Bank valuation report',
6763
- confidence: 0.95
6764
- }
6765
- }
6766
- },
6767
- required: ['currency', 'quoteCurrency', 'amount', 'date']
6768
- } as const;
6769
-
6770
- export const $PriceResponseDto = {
6771
- type: 'object',
6772
- properties: {
6773
- id: {
6774
- type: 'string',
6775
- description: 'Unique identifier',
6776
- example: 'uuid-123-456'
6777
- },
6778
- userId: {
6779
- type: 'string',
6780
- description: 'User ID (owner of the price)',
6781
- example: 'user-123'
6782
- },
6783
- currency: {
6784
- type: 'string',
6785
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6786
- example: 'BTC'
6787
- },
6788
- quoteCurrency: {
6789
- type: 'string',
6790
- description: 'Quote currency (pricing currency, e.g., USD, CNY)',
6791
- example: 'USD'
6792
- },
6793
- amount: {
6794
- type: 'number',
6795
- description:
6796
- 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
6797
- example: 50000
6798
- },
6799
- date: {
6800
- type: 'string',
6801
- description:
6802
- 'Price date (ISO 8601 format). Represents the date this price was valid.',
6803
- example: '2024-01-01',
6804
- format: 'date'
6805
- },
6806
- meta: {
6807
- type: 'object',
6808
- description:
6809
- 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
6810
- example: {
6811
- source: 'MANUAL',
6812
- note: 'User-defined price',
6813
- confidence: 1
6814
- }
6815
- },
6816
- createdAt: {
6817
- format: 'date-time',
6818
- type: 'string',
6819
- description: 'Creation timestamp',
6820
- example: '2024-11-03T10:00:00Z'
6821
- },
6822
- updatedAt: {
6823
- format: 'date-time',
6824
- type: 'string',
6825
- description: 'Last update timestamp',
6826
- example: '2024-11-03T10:00:00Z'
6827
- }
6828
- },
6829
- required: [
6830
- 'id',
6831
- 'userId',
6832
- 'currency',
6833
- 'quoteCurrency',
6834
- 'amount',
6835
- 'date',
6836
- 'meta',
6837
- 'createdAt',
6838
- 'updatedAt'
6839
- ]
6840
- } as const;
6841
-
6842
- export const $PriceListResponseDto = {
6843
- type: 'object',
6844
- properties: {
6845
- items: {
6846
- description: 'List of prices',
6847
- type: 'array',
6848
- items: {
6849
- $ref: '#/components/schemas/PriceResponseDto'
6850
- }
6851
- },
6852
- total: {
6853
- type: 'number',
6854
- description: 'Total number of prices',
6855
- example: 42
6856
- }
6857
- },
6858
- required: ['items', 'total']
6859
- } as const;
6860
-
6861
- export const $UpdateBeanPriceDto = {
6862
- type: 'object',
6863
- properties: {
6864
- currency: {
6865
- type: 'string',
6866
- description: 'Currency being priced'
6867
- },
6868
- quoteCurrency: {
6869
- type: 'string',
6870
- description: 'Quote currency (pricing currency)'
6871
- },
6872
- amount: {
6873
- type: 'number',
6874
- description: 'Price amount (MUST be >= 0 per Beancount spec)',
6875
- minimum: 0
6876
- },
6877
- date: {
6878
- type: 'string',
6879
- description: 'Price date (ISO 8601 format)'
6880
- },
6881
- metadata: {
6882
- type: 'object',
6883
- description: 'Metadata'
6884
- }
6885
- }
8106
+ 'accountPath',
8107
+ 'symbol',
8108
+ 'chartToken',
8109
+ 'assetClass',
8110
+ 'units'
8111
+ ]
6886
8112
  } as const;
6887
8113
 
6888
- export const $CurrencyBalanceDto = {
8114
+ export const $HoldingPnlWarningDto = {
6889
8115
  type: 'object',
6890
8116
  properties: {
6891
- currency: {
8117
+ type: {
6892
8118
  type: 'string',
6893
- description: 'ISO 4217 currency code',
6894
- example: 'CNY'
8119
+ description: 'Warning type',
8120
+ example: 'MISSING_COST_FX_RATE',
8121
+ enum: [
8122
+ 'MISSING_COST_FX_RATE',
8123
+ 'MISSING_MARKET_FX_RATE',
8124
+ 'MISSING_SALE_PRICE',
8125
+ 'MISSING_REALIZED_FX_RATE',
8126
+ 'OVERSOLD_LOTS',
8127
+ 'NO_PRICE',
8128
+ 'MIXED_COST_CURRENCY'
8129
+ ]
6895
8130
  },
6896
- balance: {
6897
- type: 'string',
6898
- description: 'Balance amount',
6899
- example: '500000.00'
8131
+ symbol: {
8132
+ type: 'object',
8133
+ nullable: true
8134
+ },
8135
+ accountId: {
8136
+ type: 'object',
8137
+ nullable: true
8138
+ },
8139
+ currency: {
8140
+ type: 'object',
8141
+ nullable: true
6900
8142
  }
6901
8143
  },
6902
- required: ['currency', 'balance']
8144
+ required: ['type']
6903
8145
  } as const;
6904
8146
 
6905
- export const $TimeSeriesPointDto = {
8147
+ export const $HoldingPnlResponseDto = {
6906
8148
  type: 'object',
6907
8149
  properties: {
6908
- date: {
8150
+ asOfDate: {
6909
8151
  type: 'string',
6910
- description: 'Date in YYYY-MM-DD format',
6911
- example: '2024-06-15'
8152
+ example: '2026-07-08'
6912
8153
  },
6913
- value: {
8154
+ baseCurrency: {
6914
8155
  type: 'string',
6915
- description: 'Value at this date (in base currency)',
6916
- example: '500000.00'
8156
+ example: 'CNY'
6917
8157
  },
6918
- change: {
6919
- type: 'object',
6920
- description: 'Change from previous point',
6921
- example: '5000.00'
8158
+ method: {
8159
+ type: 'string',
8160
+ description:
8161
+ 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
8162
+ enum: ['average', 'FIFO'],
8163
+ example: 'average'
6922
8164
  },
6923
- byCurrency: {
6924
- description: 'Multi-currency breakdown for this point',
8165
+ rows: {
6925
8166
  type: 'array',
6926
8167
  items: {
6927
- $ref: '#/components/schemas/CurrencyBalanceDto'
8168
+ $ref: '#/components/schemas/HoldingPnlRowDto'
8169
+ }
8170
+ },
8171
+ warnings: {
8172
+ type: 'array',
8173
+ items: {
8174
+ $ref: '#/components/schemas/HoldingPnlWarningDto'
6928
8175
  }
6929
8176
  }
6930
8177
  },
6931
- required: ['date', 'value']
8178
+ required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6932
8179
  } as const;
6933
8180
 
6934
- export const $TrendSummaryDto = {
8181
+ export const $AnonymousLoginDto = {
6935
8182
  type: 'object',
6936
8183
  properties: {
6937
- startValue: {
6938
- type: 'string',
6939
- description: 'Value at start of period',
6940
- example: '450000.00'
6941
- },
6942
- endValue: {
6943
- type: 'string',
6944
- description: 'Value at end of period',
6945
- example: '500000.00'
6946
- },
6947
- totalChange: {
6948
- type: 'string',
6949
- description: 'Total change over period',
6950
- example: '50000.00'
6951
- },
6952
- totalChangePercentage: {
8184
+ accessToken: {
6953
8185
  type: 'string',
6954
- description: 'Total change percentage',
6955
- example: '+11.11%'
8186
+ description: 'Access token for anonymous login'
6956
8187
  }
6957
8188
  },
6958
- required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
8189
+ required: ['accessToken']
6959
8190
  } as const;
6960
8191
 
6961
- export const $MultiCurrencyPointDto = {
8192
+ export const $AnonymousLoginResponseDto = {
6962
8193
  type: 'object',
6963
8194
  properties: {
6964
- date: {
8195
+ authToken: {
6965
8196
  type: 'string',
6966
- description: 'Date in YYYY-MM-DD format',
6967
- example: '2024-06-15'
6968
- },
6969
- byCurrency: {
6970
- description: 'Balances by currency',
6971
- type: 'array',
6972
- items: {
6973
- $ref: '#/components/schemas/CurrencyBalanceDto'
6974
- }
8197
+ description: 'JWT auth token',
8198
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
6975
8199
  }
6976
8200
  },
6977
- required: ['date', 'byCurrency']
8201
+ required: ['authToken']
6978
8202
  } as const;
6979
8203
 
6980
- export const $PortfolioTrendsResponseDto = {
8204
+ export const $SymbolSearchResultDto = {
6981
8205
  type: 'object',
6982
8206
  properties: {
6983
- series: {
6984
- description: 'Time series data points',
6985
- type: 'array',
6986
- items: {
6987
- $ref: '#/components/schemas/TimeSeriesPointDto'
6988
- }
8207
+ symbol: {
8208
+ type: 'string',
8209
+ example: 'AAPL'
6989
8210
  },
6990
- summary: {
6991
- description: 'Period summary',
6992
- allOf: [
6993
- {
6994
- $ref: '#/components/schemas/TrendSummaryDto'
6995
- }
6996
- ]
8211
+ name: {
8212
+ type: 'object',
8213
+ example: 'Apple Inc.',
8214
+ nullable: true
6997
8215
  },
6998
- period: {
6999
- type: 'string',
7000
- description: 'Period requested',
7001
- example: '6m'
8216
+ exchange: {
8217
+ type: 'object',
8218
+ example: 'US',
8219
+ nullable: true
7002
8220
  },
7003
- granularity: {
7004
- type: 'string',
7005
- description: 'Data granularity',
7006
- example: 'month'
8221
+ assetType: {
8222
+ type: 'object',
8223
+ description: 'OpenBB asset_type (e.g. stock, etf)',
8224
+ example: 'stock',
8225
+ nullable: true
7007
8226
  },
7008
- currency: {
7009
- type: 'string',
7010
- description: 'Base currency for converted values',
7011
- example: 'CNY'
8227
+ assetClass: {
8228
+ type: 'object',
8229
+ description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
8230
+ example: 'EQUITY',
8231
+ nullable: true
7012
8232
  },
7013
- byCurrency: {
7014
- description:
7015
- 'Multi-currency time series (each point has currency breakdown)',
7016
- type: 'array',
7017
- items: {
7018
- $ref: '#/components/schemas/MultiCurrencyPointDto'
7019
- }
8233
+ assetSubClass: {
8234
+ type: 'object',
8235
+ description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
8236
+ example: 'STOCK',
8237
+ nullable: true
7020
8238
  },
7021
- warnings: {
7022
- description: 'Exchange rate warnings',
7023
- type: 'array',
7024
- items: {
7025
- $ref: '#/components/schemas/ExchangeRateWarningDto'
7026
- }
8239
+ currency: {
8240
+ type: 'object',
8241
+ description: 'Trading currency (extra_data or inferred from exchange)',
8242
+ example: 'USD',
8243
+ nullable: true
7027
8244
  }
7028
8245
  },
7029
- required: ['series', 'summary', 'period', 'granularity', 'currency']
7030
- } as const;
7031
-
7032
- export const $GenerateSnapshotBody = {
7033
- type: 'object',
7034
- properties: {}
7035
- } as const;
7036
-
7037
- export const $GenerateSnapshotResponse = {
7038
- type: 'object',
7039
- properties: {}
7040
- } as const;
7041
-
7042
- export const $BackfillSnapshotsBody = {
7043
- type: 'object',
7044
- properties: {}
7045
- } as const;
7046
-
7047
- export const $BackfillSnapshotsResponse = {
7048
- type: 'object',
7049
- properties: {}
8246
+ required: ['symbol']
7050
8247
  } as const;
7051
8248
 
7052
- export const $AnonymousLoginDto = {
8249
+ export const $SymbolQuoteDto = {
7053
8250
  type: 'object',
7054
8251
  properties: {
7055
- accessToken: {
8252
+ symbol: {
7056
8253
  type: 'string',
7057
- description: 'Access token for anonymous login'
8254
+ example: 'AAPL'
8255
+ },
8256
+ name: {
8257
+ type: 'object',
8258
+ example: 'Apple Inc.',
8259
+ nullable: true
8260
+ },
8261
+ exchange: {
8262
+ type: 'object',
8263
+ example: 'US',
8264
+ nullable: true
8265
+ },
8266
+ assetType: {
8267
+ type: 'object',
8268
+ description: 'OpenBB asset_type',
8269
+ example: 'stock',
8270
+ nullable: true
8271
+ },
8272
+ assetClass: {
8273
+ type: 'object',
8274
+ description: 'IGN asset class',
8275
+ example: 'EQUITY',
8276
+ nullable: true
8277
+ },
8278
+ assetSubClass: {
8279
+ type: 'object',
8280
+ description: 'IGN asset sub-class',
8281
+ example: 'STOCK',
8282
+ nullable: true
8283
+ },
8284
+ currency: {
8285
+ type: 'object',
8286
+ description: 'Trading currency (extra_data or inferred from exchange)',
8287
+ example: 'USD',
8288
+ nullable: true
8289
+ },
8290
+ price: {
8291
+ type: 'object',
8292
+ description: 'Latest price (Decimal string)',
8293
+ example: '189.84',
8294
+ nullable: true
8295
+ },
8296
+ priceDate: {
8297
+ type: 'object',
8298
+ description: 'Date the price was observed (ISO yyyy-MM-dd)',
8299
+ example: '2026-08-05',
8300
+ nullable: true
8301
+ },
8302
+ changePercent: {
8303
+ type: 'object',
8304
+ description:
8305
+ 'Change vs previous close, in percentage points (1.7 == 1.7%). openbb stores change_percent as a normalized decimal; this exposes percentage points for frontend convenience.',
8306
+ example: 1.7,
8307
+ nullable: true
8308
+ },
8309
+ prevClose: {
8310
+ type: 'object',
8311
+ description: 'Previous close (Decimal string)',
8312
+ nullable: true
8313
+ },
8314
+ open: {
8315
+ type: 'object',
8316
+ description: 'Day open (Decimal string)',
8317
+ nullable: true
8318
+ },
8319
+ high: {
8320
+ type: 'object',
8321
+ description: 'Day high (Decimal string)',
8322
+ nullable: true
8323
+ },
8324
+ low: {
8325
+ type: 'object',
8326
+ description: 'Day low (Decimal string)',
8327
+ nullable: true
8328
+ },
8329
+ volume: {
8330
+ type: 'object',
8331
+ description: 'Day volume (Decimal string)',
8332
+ nullable: true
8333
+ },
8334
+ yearHigh: {
8335
+ type: 'object',
8336
+ description: '52-week high (Decimal string)',
8337
+ nullable: true
8338
+ },
8339
+ yearLow: {
8340
+ type: 'object',
8341
+ description: '52-week low (Decimal string)',
8342
+ nullable: true
7058
8343
  }
7059
- },
7060
- required: ['accessToken']
8344
+ }
7061
8345
  } as const;