@firela/api-types 0.0.0-canary.505aa62c → 0.0.0-canary.5178802d

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.
@@ -51,6 +51,14 @@ export const $CreateAccountDto = {
51
51
  description: 'Icon identifier (overrides template)',
52
52
  example: 'bank-custom'
53
53
  },
54
+ displayName: {
55
+ type: 'string',
56
+ description:
57
+ 'User-set display name override (omit/null = keep the derived name)',
58
+ nullable: true,
59
+ maxLength: 50,
60
+ example: 'Salary card'
61
+ },
54
62
  openDirectiveMeta: {
55
63
  type: 'object',
56
64
  description:
@@ -88,6 +96,49 @@ export const $AccountResponseDto = {
88
96
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
89
97
  example: 'Assets'
90
98
  },
99
+ assetSubClass: {
100
+ type: 'string',
101
+ description:
102
+ '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.',
103
+ enum: [
104
+ 'DEPOSIT',
105
+ 'CASH',
106
+ 'MONEY_MARKET_FUND',
107
+ 'STOCK',
108
+ 'ETF',
109
+ 'MUTUAL_FUND',
110
+ 'EQUITY_COMPENSATION',
111
+ 'GOVERNMENT_BOND',
112
+ 'CORPORATE_BOND',
113
+ 'BOND_FUND',
114
+ 'PRIMARY_RESIDENCE',
115
+ 'INVESTMENT_PROPERTY',
116
+ 'REIT',
117
+ 'GOLD',
118
+ 'SILVER',
119
+ 'PRECIOUS_METAL',
120
+ 'PRECIOUS_METAL_FUND',
121
+ 'COMMODITY',
122
+ 'COMMODITY_FUND',
123
+ 'CRYPTOCURRENCY',
124
+ 'RETIREMENT_ACCOUNT',
125
+ 'HEALTH_ACCOUNT',
126
+ 'EDUCATION_ACCOUNT',
127
+ 'INSURANCE',
128
+ 'PRIVATE_EQUITY',
129
+ 'HEDGE_FUND',
130
+ 'COLLECTIBLES',
131
+ 'MORTGAGE',
132
+ 'STUDENT_LOAN',
133
+ 'CREDIT_CARD',
134
+ 'PERSONAL_LOAN',
135
+ 'ACCOUNTS_PAYABLE',
136
+ 'TAX_PAYABLE',
137
+ 'OTHER'
138
+ ],
139
+ nullable: true,
140
+ example: 'STOCK'
141
+ },
91
142
  status: {
92
143
  type: 'string',
93
144
  description: 'Account status',
@@ -138,7 +189,8 @@ export const $AccountResponseDto = {
138
189
  },
139
190
  displayName: {
140
191
  type: 'string',
141
- description: 'Localized display name (ADR-0114, read-time projection)',
192
+ description:
193
+ 'Display name with precedence: user-set name (#762) > ADR-0114 localized name > path leaf (read-time projection)',
142
194
  example: 'Checking'
143
195
  },
144
196
  icon: {
@@ -154,7 +206,7 @@ export const $AccountResponseDto = {
154
206
  }
155
207
  },
156
208
  platformId: {
157
- type: 'object',
209
+ type: 'string',
158
210
  description: 'Platform ID (null if unbound)',
159
211
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
160
212
  },
@@ -234,6 +286,14 @@ export const $UpdateAccountDto = {
234
286
  description: 'Icon identifier',
235
287
  example: 'bank-custom'
236
288
  },
289
+ displayName: {
290
+ type: 'string',
291
+ description:
292
+ 'User-set display name override (null = clear the override and fall back to the derived name, omit = unchanged)',
293
+ nullable: true,
294
+ maxLength: 50,
295
+ example: 'Salary card'
296
+ },
237
297
  openDirectiveMeta: {
238
298
  type: 'object',
239
299
  description:
@@ -334,16 +394,43 @@ export const $AccountStandardResponseDto = {
334
394
  },
335
395
  name: {
336
396
  type: 'string',
337
- description: 'Short localized display name',
397
+ description:
398
+ 'Short display name. Universal rows project to the request locale (Accept-Language); regional rows keep the authored native name — mixed-language by design (ADR-0131 class P vs class A).',
338
399
  example: 'Housing Fund'
339
400
  },
401
+ aliases: {
402
+ description:
403
+ 'Authored market-language alternative names delivered verbatim (not localized copy, not xlf-managed, not locale-projected). Flat string[] per ADR-0129 D1; ADR-0131 class A.',
404
+ example: ['Alipay', 'WeChat Pay'],
405
+ type: 'array',
406
+ items: {
407
+ type: 'string'
408
+ }
409
+ },
410
+ searchTerms: {
411
+ description:
412
+ 'Locale-projected search synonyms (e.g. the zh bank-card / debit-card everyday terms for the checking account). Pure-locale projection — absent when the locale has no seeded synonyms; English fallback rides the authored aliases field. Search-only vocabulary, not the NLP routing corpus (#698, ADR-0131 fourth-class adjudication).',
413
+ example: ['yinhangka', 'jiejika'],
414
+ type: 'array',
415
+ items: {
416
+ type: 'string'
417
+ }
418
+ },
419
+ currency: {
420
+ type: 'string',
421
+ description:
422
+ 'Product denomination as a 3-letter ISO 4217 code, authored market data delivered verbatim (not localized, not xlf-managed). ADR-0131 class A. Absent = single-currency not asserted — consumers fall back to their own region currency (#714).',
423
+ example: 'HKD'
424
+ },
340
425
  description: {
341
426
  type: 'string',
342
- description: 'Account description (stable semantics only)',
427
+ description:
428
+ 'Account description (stable semantics only). Mixed-language contract: universal rows project to the request locale via the accountDesc xlf axis with an en fallback (ADR-0131 class P, ADR-0132; unseeded locales falling back to English are expected); regional rows deliver the authored market language (ADR-0131 class A, verbatim, never xlf-managed).',
343
429
  example: 'ICBC checking account for daily transactions'
344
430
  },
345
431
  tags: {
346
- description: 'Account tags for categorization',
432
+ description:
433
+ 'Account tags for categorization — structured metadata delivered verbatim (not localized, not xlf-managed). ADR-0131 class A.',
347
434
  example: ['bank', 'checking', 'primary'],
348
435
  type: 'array',
349
436
  items: {
@@ -354,9 +441,47 @@ export const $AccountStandardResponseDto = {
354
441
  type: 'string',
355
442
  description: 'Icon identifier for UI display',
356
443
  example: 'bank-icbc'
444
+ },
445
+ productCategory: {
446
+ type: 'string',
447
+ description:
448
+ 'Onboarding product category (coarse grouping derived from assetSubClass)',
449
+ enum: [
450
+ 'cash',
451
+ 'investment',
452
+ 'credit_card',
453
+ 'loan',
454
+ 'payable_tax',
455
+ 'other'
456
+ ],
457
+ example: 'investment'
458
+ },
459
+ assetClass: {
460
+ type: 'string',
461
+ description:
462
+ 'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
463
+ enum: [
464
+ 'LIQUIDITY',
465
+ 'EQUITY',
466
+ 'FIXED_INCOME',
467
+ 'PRECIOUS_METALS',
468
+ 'COMMODITY',
469
+ 'INSURANCE',
470
+ 'ALTERNATIVE_INVESTMENT',
471
+ 'PERSONAL_ASSETS',
472
+ 'LIABILITY',
473
+ 'REAL_ESTATE',
474
+ 'INDEX'
475
+ ]
476
+ },
477
+ assetSubClass: {
478
+ type: 'string',
479
+ description:
480
+ 'Asset sub-class (product type, derived at read time from classification rules)',
481
+ example: 'STOCK'
357
482
  }
358
483
  },
359
- required: ['path', 'type', 'description', 'tags', 'icon']
484
+ required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
360
485
  } as const;
361
486
 
362
487
  export const $AccountStandardListResponseDto = {
@@ -417,7 +542,10 @@ export const $RegionConfigDto = {
417
542
  },
418
543
  locale: {
419
544
  type: 'string',
420
- example: 'de-DE'
545
+ example: 'de-DE',
546
+ pattern: '^[a-z]{2,8}-[A-Z]{2}$',
547
+ description:
548
+ "Region-qualified BCP-47 tag whose region subtag equals the region's own ISO 3166-1 code (e.g., ja-JP, zh-CN, zh-HK)"
421
549
  }
422
550
  },
423
551
  required: ['currency', 'dateFormat', 'locale']
@@ -430,6 +558,12 @@ export const $RegionInfoDto = {
430
558
  type: 'string',
431
559
  example: 'de'
432
560
  },
561
+ open: {
562
+ type: 'boolean',
563
+ example: true,
564
+ description:
565
+ 'Whether the region is open (has a ready regional account template). Not-yet-open regions still return identity metadata and degrade to the universal-only catalog.'
566
+ },
433
567
  displayName: {
434
568
  type: 'string',
435
569
  example: 'Germany'
@@ -448,7 +582,7 @@ export const $RegionInfoDto = {
448
582
  $ref: '#/components/schemas/RegionConfigDto'
449
583
  }
450
584
  },
451
- required: ['code', 'displayName', 'chain', 'config']
585
+ required: ['code', 'open', 'displayName', 'chain', 'config']
452
586
  } as const;
453
587
 
454
588
  export const $RegionsMetadataResponseDto = {
@@ -695,7 +829,7 @@ export const $PostingResponseDto = {
695
829
  units: {
696
830
  type: 'string',
697
831
  description:
698
- 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
832
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.',
699
833
  example: '100.50'
700
834
  },
701
835
  currency: {
@@ -1061,7 +1195,7 @@ export const $PostingDetailDto = {
1061
1195
  units: {
1062
1196
  type: 'string',
1063
1197
  description:
1064
- 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
1198
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned. Carries the raw Beancount sign (credit-normal accounts such as Income post negative — the accounting truth, ADR-0126); renderers must not infer economic semantics from this sign.',
1065
1199
  example: '100.50'
1066
1200
  },
1067
1201
  currency: {
@@ -1245,6 +1379,147 @@ export const $TransactionDetailDto = {
1245
1379
  ]
1246
1380
  } as const;
1247
1381
 
1382
+ export const $TransactionListItemDto = {
1383
+ type: 'object',
1384
+ properties: {
1385
+ id: {
1386
+ type: 'string',
1387
+ description: 'Transaction ID',
1388
+ example: 'clh1234567890abcdef'
1389
+ },
1390
+ date: {
1391
+ type: 'string',
1392
+ description: 'Transaction date',
1393
+ example: '2024-11-28'
1394
+ },
1395
+ flag: {
1396
+ type: 'string',
1397
+ description: 'Transaction flag',
1398
+ enum: [
1399
+ 'CLEARED',
1400
+ 'PENDING',
1401
+ 'PADDING',
1402
+ 'SUMMARIZE',
1403
+ 'TRANSFER',
1404
+ 'CONVERSIONS'
1405
+ ],
1406
+ example: 'CLEARED'
1407
+ },
1408
+ customFlag: {
1409
+ type: 'string',
1410
+ description: 'Custom flag (if not using standard flags)',
1411
+ example: 'R'
1412
+ },
1413
+ payee: {
1414
+ type: 'string',
1415
+ description: 'Payee name',
1416
+ example: 'Whole Foods Market'
1417
+ },
1418
+ narration: {
1419
+ type: 'string',
1420
+ description: 'Transaction narration',
1421
+ example: 'Grocery shopping'
1422
+ },
1423
+ tags: {
1424
+ description: 'Transaction tags',
1425
+ example: ['groceries'],
1426
+ type: 'array',
1427
+ items: {
1428
+ type: 'string'
1429
+ }
1430
+ },
1431
+ links: {
1432
+ description: 'Transaction links',
1433
+ example: ['invoice-2024-001'],
1434
+ type: 'array',
1435
+ items: {
1436
+ type: 'string'
1437
+ }
1438
+ },
1439
+ meta: {
1440
+ type: 'object',
1441
+ description: 'Transaction metadata'
1442
+ },
1443
+ status: {
1444
+ type: 'string',
1445
+ description: 'Transaction status',
1446
+ enum: ['ACTIVE', 'VOIDED', 'SUPERSEDED'],
1447
+ example: 'ACTIVE'
1448
+ },
1449
+ sourceType: {
1450
+ type: 'string',
1451
+ description:
1452
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1453
+ },
1454
+ sourcePlatform: {
1455
+ type: 'string',
1456
+ description: 'Source platform (e.g., alipay, wechat)',
1457
+ example: 'alipay'
1458
+ },
1459
+ postings: {
1460
+ description: 'Transaction postings',
1461
+ type: 'array',
1462
+ items: {
1463
+ $ref: '#/components/schemas/PostingDetailDto'
1464
+ }
1465
+ },
1466
+ createdAt: {
1467
+ type: 'string',
1468
+ description: 'Created at timestamp',
1469
+ example: '2024-11-28T10:30:00.000Z'
1470
+ },
1471
+ voidedAt: {
1472
+ type: 'string',
1473
+ description: 'Voided at timestamp (if voided)',
1474
+ example: '2024-11-29T15:00:00.000Z'
1475
+ },
1476
+ voidedBy: {
1477
+ type: 'string',
1478
+ description: 'User ID who voided this transaction',
1479
+ example: 'clh1234567890abcdef'
1480
+ },
1481
+ correctionReason: {
1482
+ type: 'string',
1483
+ description: 'Correction reason (if voided or superseded)',
1484
+ example: 'Duplicate entry'
1485
+ },
1486
+ supersededBy: {
1487
+ type: 'string',
1488
+ description:
1489
+ 'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
1490
+ example: 'clh1234567890abcdef'
1491
+ },
1492
+ originalTxn: {
1493
+ type: 'string',
1494
+ description:
1495
+ 'ID of the transaction this one corrected/replaced (back-link on the replacement)',
1496
+ example: 'clh1234567890abcdef'
1497
+ },
1498
+ viewpointAmount: {
1499
+ type: 'string',
1500
+ description:
1501
+ 'Row amount under the request viewpoint (ADR-0126). Category viewpoint (category + flow): per-leg sign-normalized sum over the category account set (Income-root legs negated, Expenses-root identity) — positive under normal booking but NOT clamped (explicit negative expense legs and net-flip refund months stay negative). No viewpoint (plain list / search, no accountId): wallet money-flow net = raw-sign sum over cost-less Assets/Liabilities legs (income positive, expenses negative, transfers net ~0); color cue is the wallet sign (net < 0 = wealth-decreasing). Status-orthogonal: audit views match too (ADR-0128 amount-as-matching-key). Omitted under the account viewpoint (incl. dual) and for rows with no wallet leg.',
1502
+ example: '10000.00'
1503
+ },
1504
+ viewpointCurrency: {
1505
+ type: 'string',
1506
+ description:
1507
+ 'Currency of viewpointAmount. A row spanning multiple currencies takes the largest-magnitude currency group (known simplification, ADR-0126).',
1508
+ example: 'CNY'
1509
+ }
1510
+ },
1511
+ required: [
1512
+ 'id',
1513
+ 'date',
1514
+ 'narration',
1515
+ 'tags',
1516
+ 'links',
1517
+ 'status',
1518
+ 'postings',
1519
+ 'createdAt'
1520
+ ]
1521
+ } as const;
1522
+
1248
1523
  export const $BalanceByCurrencyDto = {
1249
1524
  type: 'object',
1250
1525
  properties: {
@@ -1290,7 +1565,7 @@ export const $TransactionListSummaryDto = {
1290
1565
  totalAmount: {
1291
1566
  type: 'string',
1292
1567
  description:
1293
- '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.',
1568
+ 'Partial converted total in base currency (rated currencies only). Sign by viewpoint (ADR-0126): account viewpoint keeps the raw Beancount sign (income negative); category viewpoint is per-leg sign-normalized (Income legs negated, Expenses legs identity — positive under normal booking, not clamped). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.',
1294
1569
  example: '-6000.00'
1295
1570
  },
1296
1571
  currency: {
@@ -1316,6 +1591,26 @@ export const $TransactionListSummaryDto = {
1316
1591
  required: ['totalAmount', 'currency', 'balanceByCurrency']
1317
1592
  } as const;
1318
1593
 
1594
+ export const $TransactionListViewpointDto = {
1595
+ type: 'object',
1596
+ properties: {
1597
+ type: {
1598
+ type: 'string',
1599
+ description:
1600
+ 'Viewpoint type (only category drill-down carries a viewpoint today)',
1601
+ enum: ['category'],
1602
+ example: 'category'
1603
+ },
1604
+ flow: {
1605
+ type: 'string',
1606
+ description: 'Flow root the category account set is restricted to',
1607
+ enum: ['income', 'expense'],
1608
+ example: 'expense'
1609
+ }
1610
+ },
1611
+ required: ['type', 'flow']
1612
+ } as const;
1613
+
1319
1614
  export const $TransactionListResponseDto = {
1320
1615
  type: 'object',
1321
1616
  properties: {
@@ -1323,7 +1618,7 @@ export const $TransactionListResponseDto = {
1323
1618
  description: 'List of transactions',
1324
1619
  type: 'array',
1325
1620
  items: {
1326
- $ref: '#/components/schemas/TransactionDetailDto'
1621
+ $ref: '#/components/schemas/TransactionListItemDto'
1327
1622
  }
1328
1623
  },
1329
1624
  total: {
@@ -1349,6 +1644,15 @@ export const $TransactionListResponseDto = {
1349
1644
  $ref: '#/components/schemas/TransactionListSummaryDto'
1350
1645
  }
1351
1646
  ]
1647
+ },
1648
+ viewpoint: {
1649
+ description:
1650
+ 'Viewpoint metadata (ADR-0126). Present only for a single category filter (category + flow, no accountId); dual-perspective requests are viewpoint-less (raw signs, no viewpointAmount).',
1651
+ allOf: [
1652
+ {
1653
+ $ref: '#/components/schemas/TransactionListViewpointDto'
1654
+ }
1655
+ ]
1352
1656
  }
1353
1657
  },
1354
1658
  required: ['data', 'total', 'limit', 'offset']
@@ -1700,13 +2004,17 @@ export const $ReviewStatsDto = {
1700
2004
  type: 'object',
1701
2005
  description: 'Count by type'
1702
2006
  },
2007
+ resolved: {
2008
+ type: 'number',
2009
+ description: 'Current count of reviews in RESOLVED status'
2010
+ },
1703
2011
  oldestPending: {
1704
2012
  format: 'date-time',
1705
2013
  type: 'string',
1706
2014
  description: 'Oldest pending review date'
1707
2015
  }
1708
2016
  },
1709
- required: ['total', 'byType']
2017
+ required: ['total', 'byType', 'resolved']
1710
2018
  } as const;
1711
2019
 
1712
2020
  export const $DecisionOptionDto = {
@@ -2259,10 +2567,10 @@ export const $UpdatePayeeDto = {
2259
2567
  meta: {
2260
2568
  type: 'object',
2261
2569
  description:
2262
- 'Metadata for extended information (location, notes, contact info, etc.). Will merge with existing metadata.',
2570
+ 'Metadata for extended information (location, notes, contact info, etc.)',
2263
2571
  example: {
2264
2572
  location: 'Zhongguancun',
2265
- note: 'Updated note',
2573
+ note: 'Near subway station',
2266
2574
  favorite: true
2267
2575
  }
2268
2576
  },
@@ -2823,32 +3131,311 @@ export const $UpdateCommodityDto = {
2823
3131
  }
2824
3132
  } as const;
2825
3133
 
2826
- export const $CreateBeanPriceDto = {
3134
+ export const $CurrencyBalanceDto = {
2827
3135
  type: 'object',
2828
3136
  properties: {
2829
3137
  currency: {
2830
3138
  type: 'string',
2831
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2832
- example: 'USD'
2833
- },
2834
- quoteCurrency: {
2835
- type: 'string',
2836
- description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
3139
+ description: 'ISO 4217 currency code',
2837
3140
  example: 'CNY'
2838
3141
  },
2839
- amount: {
2840
- type: 'number',
2841
- description:
2842
- 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
2843
- example: 175.5,
2844
- minimum: 0
2845
- },
2846
- date: {
3142
+ balance: {
2847
3143
  type: 'string',
2848
- description: 'Price date (ISO 8601 format)',
2849
- example: '2024-11-05'
2850
- },
2851
- metadata: {
3144
+ description: 'Balance amount',
3145
+ example: '500000.00'
3146
+ }
3147
+ },
3148
+ required: ['currency', 'balance']
3149
+ } as const;
3150
+
3151
+ export const $TimeSeriesPointDto = {
3152
+ type: 'object',
3153
+ properties: {
3154
+ date: {
3155
+ type: 'string',
3156
+ description: 'Date in YYYY-MM-DD format',
3157
+ example: '2024-06-15'
3158
+ },
3159
+ value: {
3160
+ type: 'string',
3161
+ description: 'Value at this date (in base currency)',
3162
+ example: '500000.00'
3163
+ },
3164
+ change: {
3165
+ type: 'string',
3166
+ description: 'Change from previous point',
3167
+ example: '5000.00'
3168
+ },
3169
+ assets: {
3170
+ type: 'string',
3171
+ description: 'Total assets at this date (in base currency)',
3172
+ example: '494338.00'
3173
+ },
3174
+ liabilities: {
3175
+ type: 'string',
3176
+ description: 'Total liabilities at this date (in base currency)',
3177
+ example: '310098.00'
3178
+ },
3179
+ byCurrency: {
3180
+ description: 'Multi-currency breakdown for this point',
3181
+ type: 'array',
3182
+ items: {
3183
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3184
+ }
3185
+ }
3186
+ },
3187
+ required: ['date', 'value']
3188
+ } as const;
3189
+
3190
+ export const $TrendSummaryDto = {
3191
+ type: 'object',
3192
+ properties: {
3193
+ startValue: {
3194
+ type: 'string',
3195
+ description: 'Value at start of period',
3196
+ example: '450000.00'
3197
+ },
3198
+ endValue: {
3199
+ type: 'string',
3200
+ description: 'Value at end of period',
3201
+ example: '500000.00'
3202
+ },
3203
+ totalChange: {
3204
+ type: 'string',
3205
+ description: 'Total change over period',
3206
+ example: '50000.00'
3207
+ },
3208
+ totalChangePercentage: {
3209
+ type: 'string',
3210
+ description: 'Total change percentage',
3211
+ example: '+11.11%'
3212
+ }
3213
+ },
3214
+ required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
3215
+ } as const;
3216
+
3217
+ export const $MultiCurrencyPointDto = {
3218
+ type: 'object',
3219
+ properties: {
3220
+ date: {
3221
+ type: 'string',
3222
+ description: 'Date in YYYY-MM-DD format',
3223
+ example: '2024-06-15'
3224
+ },
3225
+ byCurrency: {
3226
+ description: 'Balances by currency',
3227
+ type: 'array',
3228
+ items: {
3229
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3230
+ }
3231
+ }
3232
+ },
3233
+ required: ['date', 'byCurrency']
3234
+ } as const;
3235
+
3236
+ export const $PortfolioTrendsResponseDto = {
3237
+ type: 'object',
3238
+ properties: {
3239
+ series: {
3240
+ description: 'Time series data points',
3241
+ type: 'array',
3242
+ items: {
3243
+ $ref: '#/components/schemas/TimeSeriesPointDto'
3244
+ }
3245
+ },
3246
+ summary: {
3247
+ description: 'Period summary',
3248
+ allOf: [
3249
+ {
3250
+ $ref: '#/components/schemas/TrendSummaryDto'
3251
+ }
3252
+ ]
3253
+ },
3254
+ period: {
3255
+ type: 'string',
3256
+ description: 'Period requested',
3257
+ example: '6m'
3258
+ },
3259
+ granularity: {
3260
+ type: 'string',
3261
+ description: 'Data granularity',
3262
+ example: 'month'
3263
+ },
3264
+ currency: {
3265
+ type: 'string',
3266
+ description: 'Base currency for converted values',
3267
+ example: 'CNY'
3268
+ },
3269
+ byCurrency: {
3270
+ description:
3271
+ 'Multi-currency time series (each point has currency breakdown)',
3272
+ type: 'array',
3273
+ items: {
3274
+ $ref: '#/components/schemas/MultiCurrencyPointDto'
3275
+ }
3276
+ },
3277
+ warnings: {
3278
+ description: 'Exchange rate warnings',
3279
+ type: 'array',
3280
+ items: {
3281
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
3282
+ }
3283
+ }
3284
+ },
3285
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3286
+ } as const;
3287
+
3288
+ export const $CashFlowPointDto = {
3289
+ type: 'object',
3290
+ properties: {
3291
+ month: {
3292
+ type: 'string',
3293
+ description: 'Month key (YYYY-MM)',
3294
+ example: '2024-03'
3295
+ },
3296
+ income: {
3297
+ type: 'string',
3298
+ description: 'Income in base currency (absolute, converted)',
3299
+ example: '10000.00'
3300
+ },
3301
+ expense: {
3302
+ type: 'string',
3303
+ description: 'Expense in base currency (absolute, converted)',
3304
+ example: '5000.00'
3305
+ },
3306
+ netSavings: {
3307
+ type: 'string',
3308
+ description: 'netSavings = income − expense (savings positive)',
3309
+ example: '5000.00'
3310
+ }
3311
+ },
3312
+ required: ['month', 'income', 'expense', 'netSavings']
3313
+ } as const;
3314
+
3315
+ export const $CashFlowTrendSummaryDto = {
3316
+ type: 'object',
3317
+ properties: {
3318
+ totalIncome: {
3319
+ type: 'string',
3320
+ description: 'Total income across the period',
3321
+ example: '60000.00'
3322
+ },
3323
+ totalExpense: {
3324
+ type: 'string',
3325
+ description: 'Total expense across the period',
3326
+ example: '30000.00'
3327
+ },
3328
+ totalNetSavings: {
3329
+ type: 'string',
3330
+ description: 'income − expense across the period',
3331
+ example: '30000.00'
3332
+ },
3333
+ averageMonthlyNetSavings: {
3334
+ type: 'string',
3335
+ description:
3336
+ 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
3337
+ example: '5000.00'
3338
+ }
3339
+ },
3340
+ required: [
3341
+ 'totalIncome',
3342
+ 'totalExpense',
3343
+ 'totalNetSavings',
3344
+ 'averageMonthlyNetSavings'
3345
+ ]
3346
+ } as const;
3347
+
3348
+ export const $CashFlowTrendsResponseDto = {
3349
+ type: 'object',
3350
+ properties: {
3351
+ series: {
3352
+ description:
3353
+ 'Monthly cash-flow series (fixed N-month window, zero-filled)',
3354
+ type: 'array',
3355
+ items: {
3356
+ $ref: '#/components/schemas/CashFlowPointDto'
3357
+ }
3358
+ },
3359
+ summary: {
3360
+ description: 'Period totals',
3361
+ allOf: [
3362
+ {
3363
+ $ref: '#/components/schemas/CashFlowTrendSummaryDto'
3364
+ }
3365
+ ]
3366
+ },
3367
+ period: {
3368
+ type: 'string',
3369
+ description: 'Period requested',
3370
+ example: '6m'
3371
+ },
3372
+ granularity: {
3373
+ type: 'string',
3374
+ description: 'Data granularity (v1 returns month buckets)',
3375
+ example: 'month'
3376
+ },
3377
+ currency: {
3378
+ type: 'string',
3379
+ description: 'Base currency for converted values',
3380
+ example: 'CNY'
3381
+ },
3382
+ warnings: {
3383
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
3384
+ type: 'array',
3385
+ items: {
3386
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
3387
+ }
3388
+ }
3389
+ },
3390
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3391
+ } as const;
3392
+
3393
+ export const $GenerateSnapshotBody = {
3394
+ type: 'object',
3395
+ properties: {}
3396
+ } as const;
3397
+
3398
+ export const $GenerateSnapshotResponse = {
3399
+ type: 'object',
3400
+ properties: {}
3401
+ } as const;
3402
+
3403
+ export const $BackfillSnapshotsBody = {
3404
+ type: 'object',
3405
+ properties: {}
3406
+ } as const;
3407
+
3408
+ export const $BackfillSnapshotsResponse = {
3409
+ type: 'object',
3410
+ properties: {}
3411
+ } as const;
3412
+
3413
+ export const $CreateBeanPriceDto = {
3414
+ type: 'object',
3415
+ properties: {
3416
+ currency: {
3417
+ type: 'string',
3418
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
3419
+ example: 'USD'
3420
+ },
3421
+ quoteCurrency: {
3422
+ type: 'string',
3423
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
3424
+ example: 'CNY'
3425
+ },
3426
+ amount: {
3427
+ type: 'number',
3428
+ description:
3429
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
3430
+ example: 175.5,
3431
+ minimum: 0
3432
+ },
3433
+ date: {
3434
+ type: 'string',
3435
+ description: 'Price date (ISO 8601 format)',
3436
+ example: '2024-11-05'
3437
+ },
3438
+ metadata: {
2852
3439
  type: 'object',
2853
3440
  description:
2854
3441
  'Metadata (validated by Zod schema, max field lengths enforced)',
@@ -2980,6 +3567,218 @@ export const $UpdateBeanPriceDto = {
2980
3567
  }
2981
3568
  } as const;
2982
3569
 
3570
+ export const $DeleteOwnUserDto = {
3571
+ type: 'object',
3572
+ properties: {
3573
+ accessToken: {
3574
+ type: 'string',
3575
+ description: 'Access token for user verification',
3576
+ example: 'abc123xyz'
3577
+ }
3578
+ },
3579
+ required: ['accessToken']
3580
+ } as const;
3581
+
3582
+ export const $UserSettingsResponseDto = {
3583
+ type: 'object',
3584
+ properties: {
3585
+ baseCurrency: {
3586
+ type: 'string',
3587
+ description:
3588
+ 'Stored base currency choice (ISO 4217) for net-worth/report aggregation. null = user never chose; aggregates fall back to the region default at display time (#713).',
3589
+ example: 'USD',
3590
+ nullable: true
3591
+ }
3592
+ },
3593
+ required: ['baseCurrency']
3594
+ } as const;
3595
+
3596
+ export const $UserResponseDto = {
3597
+ type: 'object',
3598
+ properties: {
3599
+ id: {
3600
+ type: 'string',
3601
+ description: 'User ID'
3602
+ },
3603
+ role: {
3604
+ type: 'string',
3605
+ description: 'Assigned user role'
3606
+ },
3607
+ permissions: {
3608
+ description: 'Permission strings',
3609
+ type: 'array',
3610
+ items: {
3611
+ type: 'string'
3612
+ }
3613
+ },
3614
+ settings: {
3615
+ description: 'User settings',
3616
+ allOf: [
3617
+ {
3618
+ $ref: '#/components/schemas/UserSettingsResponseDto'
3619
+ }
3620
+ ]
3621
+ }
3622
+ },
3623
+ required: ['id', 'role', 'permissions', 'settings']
3624
+ } as const;
3625
+
3626
+ export const $SignupDto = {
3627
+ type: 'object',
3628
+ properties: {
3629
+ turnstileToken: {
3630
+ type: 'string',
3631
+ description:
3632
+ 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
3633
+ example: '0.abc123def456...'
3634
+ }
3635
+ }
3636
+ } as const;
3637
+
3638
+ export const $SignupResponseDto = {
3639
+ type: 'object',
3640
+ properties: {
3641
+ authToken: {
3642
+ type: 'string',
3643
+ description: 'JWT auth token',
3644
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
3645
+ },
3646
+ accessToken: {
3647
+ type: 'string',
3648
+ description: 'Auto-generated access token'
3649
+ },
3650
+ role: {
3651
+ type: 'string',
3652
+ description: 'Assigned user role',
3653
+ enum: ['USER', 'ADMIN', 'DEMO', 'INACTIVE', 'PAID', 'OPS']
3654
+ }
3655
+ },
3656
+ required: ['authToken', 'accessToken', 'role']
3657
+ } as const;
3658
+
3659
+ export const $UpdateUserSettingDto = {
3660
+ type: 'object',
3661
+ properties: {
3662
+ secId: {
3663
+ type: 'number',
3664
+ description: 'Security ID'
3665
+ },
3666
+ annualInterestRate: {
3667
+ type: 'number',
3668
+ description: 'Annual interest rate',
3669
+ example: 0.05
3670
+ },
3671
+ currency: {
3672
+ type: 'string',
3673
+ description: 'Currency code',
3674
+ example: 'USD'
3675
+ },
3676
+ baseCurrency: {
3677
+ type: 'string',
3678
+ description: 'Base currency code',
3679
+ example: 'USD'
3680
+ },
3681
+ benchmark: {
3682
+ type: 'string',
3683
+ description: 'Benchmark symbol',
3684
+ example: 'SPY'
3685
+ },
3686
+ colorScheme: {
3687
+ type: 'string',
3688
+ description: 'Color scheme',
3689
+ enum: ['DARK', 'LIGHT']
3690
+ },
3691
+ dateRange: {
3692
+ type: 'string',
3693
+ description: 'Date range filter',
3694
+ example: '1y'
3695
+ },
3696
+ emergencyFund: {
3697
+ type: 'number',
3698
+ description: 'Emergency fund amount',
3699
+ example: 10000
3700
+ },
3701
+ 'filters.accounts': {
3702
+ description: 'Account filter IDs',
3703
+ type: 'array',
3704
+ items: {
3705
+ type: 'string'
3706
+ }
3707
+ },
3708
+ 'filters.assetClasses': {
3709
+ description: 'Asset class filters',
3710
+ type: 'array',
3711
+ items: {
3712
+ type: 'string'
3713
+ }
3714
+ },
3715
+ 'filters.dataSource': {
3716
+ type: 'string',
3717
+ description: 'Data source filter'
3718
+ },
3719
+ 'filters.symbol': {
3720
+ type: 'string',
3721
+ description: 'Symbol filter'
3722
+ },
3723
+ 'filters.tags': {
3724
+ description: 'Tag filters',
3725
+ type: 'array',
3726
+ items: {
3727
+ type: 'string'
3728
+ }
3729
+ },
3730
+ isExperimentalFeatures: {
3731
+ type: 'boolean',
3732
+ description: 'Enable experimental features'
3733
+ },
3734
+ isRestrictedView: {
3735
+ type: 'boolean',
3736
+ description: 'Enable restricted view mode'
3737
+ },
3738
+ language: {
3739
+ type: 'string',
3740
+ description: 'Language code',
3741
+ example: 'en'
3742
+ },
3743
+ locale: {
3744
+ type: 'string',
3745
+ description: 'Locale code',
3746
+ example: 'en-US'
3747
+ },
3748
+ projectedTotalAmount: {
3749
+ type: 'number',
3750
+ description: 'Projected total amount',
3751
+ example: 1000000
3752
+ },
3753
+ retirementDate: {
3754
+ type: 'string',
3755
+ description: 'Retirement date in ISO 8601 format',
3756
+ example: '2050-01-01'
3757
+ },
3758
+ savingsRate: {
3759
+ type: 'number',
3760
+ description: 'Savings rate percentage',
3761
+ example: 0.2
3762
+ },
3763
+ viewMode: {
3764
+ type: 'string',
3765
+ description: 'View mode',
3766
+ enum: ['DEFAULT', 'ZEN']
3767
+ }
3768
+ }
3769
+ } as const;
3770
+
3771
+ export const $UpdatePropertyDto = {
3772
+ type: 'object',
3773
+ properties: {
3774
+ value: {
3775
+ type: 'string',
3776
+ description: 'Property value'
3777
+ }
3778
+ },
3779
+ required: ['value']
3780
+ } as const;
3781
+
2983
3782
  export const $CreateRecurringRuleDto = {
2984
3783
  type: 'object',
2985
3784
  properties: {
@@ -3025,7 +3824,6 @@ export const $CreateRecurringRuleDto = {
3025
3824
  currency: {
3026
3825
  type: 'string',
3027
3826
  description: 'Currency code',
3028
- default: 'CNY',
3029
3827
  maxLength: 10
3030
3828
  },
3031
3829
  matchPayeePattern: {
@@ -3073,7 +3871,6 @@ export const $CreateRecurringRuleDto = {
3073
3871
  'name',
3074
3872
  'frequency',
3075
3873
  'expectedAmount',
3076
- 'currency',
3077
3874
  'matchAmountTolerance',
3078
3875
  'autoCreate'
3079
3876
  ]
@@ -3095,7 +3892,7 @@ export const $RecurringRuleResponseDto = {
3095
3892
  description: 'Rule name'
3096
3893
  },
3097
3894
  icon: {
3098
- type: 'object',
3895
+ type: 'string',
3099
3896
  description: 'Icon emoji'
3100
3897
  },
3101
3898
  frequency: {
@@ -3107,11 +3904,11 @@ export const $RecurringRuleResponseDto = {
3107
3904
  description: 'Expected amount'
3108
3905
  },
3109
3906
  expectedDay: {
3110
- type: 'object',
3907
+ type: 'number',
3111
3908
  description: 'Expected day of month'
3112
3909
  },
3113
3910
  customIntervalDays: {
3114
- type: 'object',
3911
+ type: 'number',
3115
3912
  description: 'Custom interval in days'
3116
3913
  },
3117
3914
  currency: {
@@ -3119,7 +3916,7 @@ export const $RecurringRuleResponseDto = {
3119
3916
  description: 'Currency code'
3120
3917
  },
3121
3918
  matchPayeePattern: {
3122
- type: 'object',
3919
+ type: 'string',
3123
3920
  description: 'Payee matching pattern'
3124
3921
  },
3125
3922
  matchAmountTolerance: {
@@ -3127,15 +3924,15 @@ export const $RecurringRuleResponseDto = {
3127
3924
  description: 'Amount tolerance percentage'
3128
3925
  },
3129
3926
  defaultExpenseAccount: {
3130
- type: 'object',
3927
+ type: 'string',
3131
3928
  description: 'Default expense account'
3132
3929
  },
3133
3930
  defaultPaymentAccount: {
3134
- type: 'object',
3931
+ type: 'string',
3135
3932
  description: 'Default payment account'
3136
3933
  },
3137
3934
  defaultPayee: {
3138
- type: 'object',
3935
+ type: 'string',
3139
3936
  description: 'Default payee'
3140
3937
  },
3141
3938
  isActive: {
@@ -3147,7 +3944,7 @@ export const $RecurringRuleResponseDto = {
3147
3944
  description: 'Rule start date (YYYY-MM-DD)'
3148
3945
  },
3149
3946
  endDate: {
3150
- type: 'object',
3947
+ type: 'string',
3151
3948
  description: 'Rule end date (YYYY-MM-DD)'
3152
3949
  },
3153
3950
  autoCreate: {
@@ -3155,7 +3952,7 @@ export const $RecurringRuleResponseDto = {
3155
3952
  description: 'Auto-create transaction on expected date'
3156
3953
  },
3157
3954
  lastOccurrence: {
3158
- type: 'object',
3955
+ type: 'string',
3159
3956
  description: 'Last matched occurrence date (YYYY-MM-DD)'
3160
3957
  },
3161
3958
  totalCount: {
@@ -3237,7 +4034,7 @@ export const $RecurringRuleWithStatsResponseDto = {
3237
4034
  description: 'Rule name'
3238
4035
  },
3239
4036
  icon: {
3240
- type: 'object',
4037
+ type: 'string',
3241
4038
  description: 'Icon emoji'
3242
4039
  },
3243
4040
  frequency: {
@@ -3249,11 +4046,11 @@ export const $RecurringRuleWithStatsResponseDto = {
3249
4046
  description: 'Expected amount'
3250
4047
  },
3251
4048
  expectedDay: {
3252
- type: 'object',
4049
+ type: 'number',
3253
4050
  description: 'Expected day of month'
3254
4051
  },
3255
4052
  customIntervalDays: {
3256
- type: 'object',
4053
+ type: 'number',
3257
4054
  description: 'Custom interval in days'
3258
4055
  },
3259
4056
  currency: {
@@ -3261,7 +4058,7 @@ export const $RecurringRuleWithStatsResponseDto = {
3261
4058
  description: 'Currency code'
3262
4059
  },
3263
4060
  matchPayeePattern: {
3264
- type: 'object',
4061
+ type: 'string',
3265
4062
  description: 'Payee matching pattern'
3266
4063
  },
3267
4064
  matchAmountTolerance: {
@@ -3269,15 +4066,15 @@ export const $RecurringRuleWithStatsResponseDto = {
3269
4066
  description: 'Amount tolerance percentage'
3270
4067
  },
3271
4068
  defaultExpenseAccount: {
3272
- type: 'object',
4069
+ type: 'string',
3273
4070
  description: 'Default expense account'
3274
4071
  },
3275
4072
  defaultPaymentAccount: {
3276
- type: 'object',
4073
+ type: 'string',
3277
4074
  description: 'Default payment account'
3278
4075
  },
3279
4076
  defaultPayee: {
3280
- type: 'object',
4077
+ type: 'string',
3281
4078
  description: 'Default payee'
3282
4079
  },
3283
4080
  isActive: {
@@ -3289,7 +4086,7 @@ export const $RecurringRuleWithStatsResponseDto = {
3289
4086
  description: 'Rule start date (YYYY-MM-DD)'
3290
4087
  },
3291
4088
  endDate: {
3292
- type: 'object',
4089
+ type: 'string',
3293
4090
  description: 'Rule end date (YYYY-MM-DD)'
3294
4091
  },
3295
4092
  autoCreate: {
@@ -3297,7 +4094,7 @@ export const $RecurringRuleWithStatsResponseDto = {
3297
4094
  description: 'Auto-create transaction on expected date'
3298
4095
  },
3299
4096
  lastOccurrence: {
3300
- type: 'object',
4097
+ type: 'string',
3301
4098
  description: 'Last matched occurrence date (YYYY-MM-DD)'
3302
4099
  },
3303
4100
  totalCount: {
@@ -3323,7 +4120,7 @@ export const $RecurringRuleWithStatsResponseDto = {
3323
4120
  description: 'Number of overdue expected transactions'
3324
4121
  },
3325
4122
  nextExpectedDate: {
3326
- type: 'object',
4123
+ type: 'string',
3327
4124
  description: 'Next expected date (YYYY-MM-DD)'
3328
4125
  },
3329
4126
  totalAmount: {
@@ -3339,11 +4136,11 @@ export const $RecurringRuleWithStatsResponseDto = {
3339
4136
  description: 'Number of matched transactions'
3340
4137
  },
3341
4138
  firstDate: {
3342
- type: 'object',
4139
+ type: 'string',
3343
4140
  description: 'First matched transaction date (YYYY-MM-DD)'
3344
4141
  },
3345
4142
  lastDate: {
3346
- type: 'object',
4143
+ type: 'string',
3347
4144
  description: 'Last matched transaction date (YYYY-MM-DD)'
3348
4145
  },
3349
4146
  variance: {
@@ -3384,7 +4181,7 @@ export const $UpdateRecurringRuleDto = {
3384
4181
  properties: {
3385
4182
  name: {
3386
4183
  type: 'string',
3387
- description: 'Rule name',
4184
+ description: 'Rule name (unique per user)',
3388
4185
  maxLength: 100
3389
4186
  },
3390
4187
  icon: {
@@ -3407,7 +4204,7 @@ export const $UpdateRecurringRuleDto = {
3407
4204
  },
3408
4205
  expectedAmount: {
3409
4206
  type: 'number',
3410
- description: 'Expected amount',
4207
+ description: 'Expected amount (positive number)',
3411
4208
  minimum: 0
3412
4209
  },
3413
4210
  expectedDay: {
@@ -3416,11 +4213,6 @@ export const $UpdateRecurringRuleDto = {
3416
4213
  minimum: 1,
3417
4214
  maximum: 31
3418
4215
  },
3419
- customIntervalDays: {
3420
- type: 'number',
3421
- description: 'Custom interval in days',
3422
- minimum: 1
3423
- },
3424
4216
  currency: {
3425
4217
  type: 'string',
3426
4218
  description: 'Currency code',
@@ -3428,41 +4220,48 @@ export const $UpdateRecurringRuleDto = {
3428
4220
  },
3429
4221
  matchPayeePattern: {
3430
4222
  type: 'string',
3431
- description: 'Payee matching pattern',
4223
+ description: 'Payee matching pattern (supports wildcards)',
3432
4224
  maxLength: 200
3433
4225
  },
3434
4226
  matchAmountTolerance: {
3435
4227
  type: 'number',
3436
4228
  description: 'Amount tolerance percentage (0-1)',
4229
+ default: 0.075,
3437
4230
  minimum: 0,
3438
4231
  maximum: 1
3439
4232
  },
3440
4233
  defaultExpenseAccount: {
3441
4234
  type: 'string',
3442
- description: 'Default expense account',
4235
+ description: 'Default expense account for auto-create',
3443
4236
  maxLength: 200
3444
4237
  },
3445
4238
  defaultPaymentAccount: {
3446
4239
  type: 'string',
3447
- description: 'Default payment account',
4240
+ description: 'Default payment account for auto-create',
3448
4241
  maxLength: 200
3449
4242
  },
3450
4243
  defaultPayee: {
3451
4244
  type: 'string',
3452
- description: 'Default payee',
4245
+ description: 'Default payee for auto-create',
3453
4246
  maxLength: 200
3454
4247
  },
3455
4248
  autoCreate: {
3456
4249
  type: 'boolean',
3457
- description: 'Auto-create transaction'
3458
- },
3459
- isActive: {
3460
- type: 'boolean',
3461
- description: 'Rule active status'
4250
+ description: 'Auto-create transaction when expected date arrives',
4251
+ default: false
3462
4252
  },
3463
4253
  endDate: {
3464
4254
  type: 'string',
3465
4255
  description: 'Rule end date (ISO format)'
4256
+ },
4257
+ customIntervalDays: {
4258
+ type: 'number',
4259
+ description: 'Custom interval in days',
4260
+ minimum: 1
4261
+ },
4262
+ isActive: {
4263
+ type: 'boolean',
4264
+ description: 'Rule active status'
3466
4265
  }
3467
4266
  }
3468
4267
  } as const;
@@ -3475,7 +4274,7 @@ export const $ExpectedTransactionRuleDto = {
3475
4274
  description: 'Rule name'
3476
4275
  },
3477
4276
  icon: {
3478
- type: 'object',
4277
+ type: 'string',
3479
4278
  description: 'Rule icon'
3480
4279
  },
3481
4280
  frequency: {
@@ -3518,15 +4317,15 @@ export const $ExpectedTransactionResponseDto = {
3518
4317
  description: 'Status (PENDING, COMPLETED, SKIPPED)'
3519
4318
  },
3520
4319
  matchedTransactionId: {
3521
- type: 'object',
4320
+ type: 'string',
3522
4321
  description: 'Matched transaction ID'
3523
4322
  },
3524
4323
  matchedAt: {
3525
- type: 'object',
4324
+ type: 'string',
3526
4325
  description: 'Match timestamp (ISO 8601)'
3527
4326
  },
3528
4327
  matchConfidence: {
3529
- type: 'object',
4328
+ type: 'number',
3530
4329
  description: 'Match confidence score (0-1)'
3531
4330
  },
3532
4331
  isOverdue: {
@@ -4310,7 +5109,8 @@ export const $UpdateTransactionRuleDto = {
4310
5109
  },
4311
5110
  matchLogic: {
4312
5111
  type: 'string',
4313
- enum: ['OR', 'AND']
5112
+ enum: ['OR', 'AND'],
5113
+ default: 'OR'
4314
5114
  },
4315
5115
  amountMin: {
4316
5116
  type: 'number',
@@ -4324,13 +5124,10 @@ export const $UpdateTransactionRuleDto = {
4324
5124
  },
4325
5125
  priority: {
4326
5126
  type: 'number',
5127
+ default: 50,
4327
5128
  minimum: 0,
4328
5129
  maximum: 1000
4329
5130
  },
4330
- enabled: {
4331
- type: 'boolean',
4332
- description: 'Enable or disable the rule'
4333
- },
4334
5131
  additionalTags: {
4335
5132
  items: {
4336
5133
  type: 'array'
@@ -4340,6 +5137,10 @@ export const $UpdateTransactionRuleDto = {
4340
5137
  },
4341
5138
  additionalMetadata: {
4342
5139
  type: 'object'
5140
+ },
5141
+ enabled: {
5142
+ type: 'boolean',
5143
+ description: 'Enable or disable the rule'
4343
5144
  }
4344
5145
  }
4345
5146
  } as const;
@@ -4400,151 +5201,81 @@ export const $TestRuleResponseDto = {
4400
5201
  required: ['ruleId', 'matches', 'confidence', 'matchDetails']
4401
5202
  } as const;
4402
5203
 
4403
- export const $DeleteOwnUserDto = {
4404
- type: 'object',
4405
- properties: {
4406
- accessToken: {
4407
- type: 'string',
4408
- description: 'Access token for user verification',
4409
- example: 'abc123xyz'
4410
- }
4411
- },
4412
- required: ['accessToken']
4413
- } as const;
4414
-
4415
- export const $SignupDto = {
4416
- type: 'object',
4417
- properties: {
4418
- turnstileToken: {
4419
- type: 'string',
4420
- description:
4421
- 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4422
- example: '0.abc123def456...'
4423
- }
4424
- }
4425
- } as const;
4426
-
4427
- export const $UpdateUserSettingDto = {
5204
+ export const $CategoryCatalogEntryDto = {
4428
5205
  type: 'object',
4429
5206
  properties: {
4430
- secId: {
4431
- type: 'number',
4432
- description: 'Security ID'
4433
- },
4434
- annualInterestRate: {
4435
- type: 'number',
4436
- description: 'Annual interest rate',
4437
- example: 0.05
4438
- },
4439
- currency: {
4440
- type: 'string',
4441
- description: 'Currency code',
4442
- example: 'USD'
4443
- },
4444
- baseCurrency: {
4445
- type: 'string',
4446
- description: 'Base currency code',
4447
- example: 'USD'
4448
- },
4449
- benchmark: {
5207
+ slug: {
4450
5208
  type: 'string',
4451
- description: 'Benchmark symbol',
4452
- example: 'SPY'
5209
+ description: 'Category slug (single source-of-truth)',
5210
+ example: 'food'
4453
5211
  },
4454
- colorScheme: {
5212
+ scenario: {
4455
5213
  type: 'string',
4456
- description: 'Color scheme',
4457
- enum: ['DARK', 'LIGHT']
5214
+ description: 'Display scenario group (maps to frontend picker _scenario)',
5215
+ enum: [
5216
+ 'expense',
5217
+ 'income',
5218
+ 'investment',
5219
+ 'banking',
5220
+ 'transfer',
5221
+ 'payment'
5222
+ ],
5223
+ example: 'expense'
4458
5224
  },
4459
- dateRange: {
5225
+ icon: {
4460
5226
  type: 'string',
4461
- description: 'Date range filter',
4462
- example: '1y'
4463
- },
4464
- emergencyFund: {
4465
- type: 'number',
4466
- description: 'Emergency fund amount',
4467
- example: 10000
5227
+ description: 'Lucide icon name',
5228
+ example: 'utensils'
4468
5229
  },
4469
- 'filters.accounts': {
4470
- description: 'Account filter IDs',
5230
+ regions: {
5231
+ description: "Applicable regions ('*' = all, 'cn' = CN-only)",
5232
+ example: ['*'],
4471
5233
  type: 'array',
4472
5234
  items: {
4473
5235
  type: 'string'
4474
5236
  }
4475
5237
  },
4476
- 'filters.assetClasses': {
4477
- description: 'Asset class filters',
5238
+ categoryAccounts: {
5239
+ description:
5240
+ "Beancount account paths (categoryAccount) of the region-enabled system rules whose categoryKeywords include this slug (#816). System rules only (public endpoint — user rules excluded); one-to-many by design (e.g. 'utilities' → Electricity/Water/Internet/Gas), sorted, [] when no rule maps the slug.",
5241
+ example: [
5242
+ 'Expenses:Utilities:Electricity',
5243
+ 'Expenses:Utilities:Gas',
5244
+ 'Expenses:Utilities:Internet',
5245
+ 'Expenses:Utilities:Water'
5246
+ ],
4478
5247
  type: 'array',
4479
5248
  items: {
4480
5249
  type: 'string'
4481
5250
  }
4482
- },
4483
- 'filters.dataSource': {
4484
- type: 'string',
4485
- description: 'Data source filter'
4486
- },
4487
- 'filters.symbol': {
4488
- type: 'string',
4489
- description: 'Symbol filter'
4490
- },
4491
- 'filters.tags': {
4492
- description: 'Tag filters',
5251
+ }
5252
+ },
5253
+ required: ['slug', 'scenario', 'icon', 'regions', 'categoryAccounts']
5254
+ } as const;
5255
+
5256
+ export const $CategoryCatalogListResponseDto = {
5257
+ type: 'object',
5258
+ properties: {
5259
+ items: {
5260
+ description: 'Category entries (region-scoped, query-filtered)',
4493
5261
  type: 'array',
4494
5262
  items: {
4495
- type: 'string'
5263
+ $ref: '#/components/schemas/CategoryCatalogEntryDto'
4496
5264
  }
4497
5265
  },
4498
- isExperimentalFeatures: {
4499
- type: 'boolean',
4500
- description: 'Enable experimental features'
4501
- },
4502
- isRestrictedView: {
4503
- type: 'boolean',
4504
- description: 'Enable restricted view mode'
4505
- },
4506
- language: {
4507
- type: 'string',
4508
- description: 'Language code',
4509
- example: 'en'
4510
- },
4511
- locale: {
4512
- type: 'string',
4513
- description: 'Locale code',
4514
- example: 'en-US'
4515
- },
4516
- projectedTotalAmount: {
4517
- type: 'number',
4518
- description: 'Projected total amount',
4519
- example: 1000000
4520
- },
4521
- retirementDate: {
4522
- type: 'string',
4523
- description: 'Retirement date in ISO 8601 format',
4524
- example: '2050-01-01'
4525
- },
4526
- savingsRate: {
5266
+ total: {
4527
5267
  type: 'number',
4528
- description: 'Savings rate percentage',
4529
- example: 0.2
5268
+ description:
5269
+ 'Total category entries for the region (before query filtering)',
5270
+ example: 30
4530
5271
  },
4531
- viewMode: {
4532
- type: 'string',
4533
- description: 'View mode',
4534
- enum: ['DEFAULT', 'ZEN']
4535
- }
4536
- }
4537
- } as const;
4538
-
4539
- export const $UpdatePropertyDto = {
4540
- type: 'object',
4541
- properties: {
4542
- value: {
5272
+ region: {
4543
5273
  type: 'string',
4544
- description: 'Property value'
5274
+ description: 'Region code',
5275
+ example: 'cn'
4545
5276
  }
4546
5277
  },
4547
- required: ['value']
5278
+ required: ['items', 'total', 'region']
4548
5279
  } as const;
4549
5280
 
4550
5281
  export const $CreateBeanEventDto = {
@@ -4710,6 +5441,14 @@ export const $OnboardingAccountDto = {
4710
5441
  description:
4711
5442
  'Platform ID to bind the account to (references Platform.id); omit for unbound',
4712
5443
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
5444
+ },
5445
+ displayName: {
5446
+ type: 'string',
5447
+ description:
5448
+ 'User-set display name override (omit/null = keep the derived name)',
5449
+ nullable: true,
5450
+ maxLength: 50,
5451
+ example: 'Salary card'
4713
5452
  }
4714
5453
  },
4715
5454
  required: ['path', 'currency']
@@ -5289,7 +6028,8 @@ export const $UpdateMapperDefaultsDto = {
5289
6028
  type: 'string',
5290
6029
  description: 'Source account for transactions (Beancount format)',
5291
6030
  example: 'Assets:CN:Alipay:Balance',
5292
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
6031
+ pattern:
6032
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
5293
6033
  },
5294
6034
  currency: {
5295
6035
  type: 'string',
@@ -5303,13 +6043,15 @@ export const $UpdateMapperDefaultsDto = {
5303
6043
  type: 'string',
5304
6044
  description: 'Default expense account (optional)',
5305
6045
  example: 'Expenses:Unknown',
5306
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
6046
+ pattern:
6047
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
5307
6048
  },
5308
6049
  incomeAccount: {
5309
6050
  type: 'string',
5310
6051
  description: 'Default income account (optional)',
5311
6052
  example: 'Income:Unknown',
5312
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
6053
+ pattern:
6054
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
5313
6055
  },
5314
6056
  methodAccountMapping: {
5315
6057
  type: 'object',
@@ -5366,12 +6108,14 @@ export const $ProviderSyncConfigDto = {
5366
6108
  },
5367
6109
  defaultExpenseAccount: {
5368
6110
  type: 'string',
5369
- description: 'Default expense account for the second posting',
6111
+ description:
6112
+ 'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
5370
6113
  example: 'Expenses:Unknown'
5371
6114
  },
5372
6115
  defaultIncomeAccount: {
5373
6116
  type: 'string',
5374
- description: 'Default income account for the second posting',
6117
+ description:
6118
+ 'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
5375
6119
  example: 'Income:Unknown'
5376
6120
  },
5377
6121
  filterPending: {
@@ -5386,12 +6130,7 @@ export const $ProviderSyncConfigDto = {
5386
6130
  example: 'acc_gocardless_001'
5387
6131
  }
5388
6132
  },
5389
- required: [
5390
- 'sourceAccount',
5391
- 'defaultCurrency',
5392
- 'defaultExpenseAccount',
5393
- 'defaultIncomeAccount'
5394
- ]
6133
+ required: ['sourceAccount', 'defaultCurrency']
5395
6134
  } as const;
5396
6135
 
5397
6136
  export const $ProviderSyncDto = {
@@ -5580,25 +6319,109 @@ export const $ExternalAccountLinkListResponseDto = {
5580
6319
  $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
5581
6320
  }
5582
6321
  },
5583
- total: {
5584
- type: 'number'
6322
+ total: {
6323
+ type: 'number'
6324
+ },
6325
+ provider: {
6326
+ type: 'string',
6327
+ description: 'Filter by provider (query param)'
6328
+ }
6329
+ },
6330
+ required: ['items', 'total']
6331
+ } as const;
6332
+
6333
+ export const $ParserTelemetryReportDto = {
6334
+ type: 'object',
6335
+ properties: {}
6336
+ } as const;
6337
+
6338
+ export const $UncoveredFormatMissDto = {
6339
+ type: 'object',
6340
+ properties: {}
6341
+ } as const;
6342
+
6343
+ export const $ClientParsedDataDto = {
6344
+ type: 'object',
6345
+ properties: {
6346
+ amount: {
6347
+ type: 'number',
6348
+ description: 'Transaction amount',
6349
+ example: 35
6350
+ },
6351
+ currency: {
6352
+ type: 'string',
6353
+ description: 'Currency code',
6354
+ example: 'CNY'
6355
+ },
6356
+ date: {
6357
+ type: 'string',
6358
+ description: 'Transaction date (ISO 8601)',
6359
+ example: '2026-08-15'
6360
+ },
6361
+ payee: {
6362
+ type: 'string',
6363
+ description: 'Payee/merchant name',
6364
+ example: 'Starbucks'
6365
+ },
6366
+ narration: {
6367
+ type: 'string',
6368
+ description: 'Transaction narration'
6369
+ },
6370
+ category: {
6371
+ type: 'string',
6372
+ description:
6373
+ 'Category in canonical form (catalog slug or Stage-2 rule keyword token, ADR-0116) — echo back verbatim from parsedData.category. Foreign forms (locale display names, account paths) are rejected with nlp.category.invalid.',
6374
+ example: 'food'
6375
+ },
6376
+ incomeType: {
6377
+ type: 'string',
6378
+ description: 'Income type',
6379
+ example: 'Salary'
6380
+ },
6381
+ incomeSource: {
6382
+ type: 'string',
6383
+ description: 'Income source',
6384
+ example: 'Anthropic Inc.'
6385
+ },
6386
+ symbol: {
6387
+ type: 'string',
6388
+ description: 'Security symbol code (e.g., 600519, AAPL)',
6389
+ example: 'AAPL'
6390
+ },
6391
+ quantity: {
6392
+ type: 'number',
6393
+ description: 'Quantity of shares/units',
6394
+ example: 100
6395
+ },
6396
+ price: {
6397
+ type: 'number',
6398
+ description: 'Unit price per share/unit',
6399
+ example: 1900
6400
+ },
6401
+ investmentAction: {
6402
+ type: 'string',
6403
+ description: 'Investment action',
6404
+ enum: ['buy', 'sell'],
6405
+ example: 'buy'
6406
+ },
6407
+ paymentSource: {
6408
+ type: 'string',
6409
+ description: 'Payment source: asset (default) or liability (credit card)',
6410
+ enum: ['asset', 'liability'],
6411
+ example: 'asset'
5585
6412
  },
5586
- provider: {
6413
+ liabilityHint: {
5587
6414
  type: 'string',
5588
- description: 'Filter by provider (query param)'
6415
+ description: 'Liability account hint (CreditCard/Huabei/Baitiao)',
6416
+ example: 'CreditCard'
6417
+ },
6418
+ warning: {
6419
+ type: 'string',
6420
+ description:
6421
+ 'Display-only warning from the prior response; accepted but ignored.',
6422
+ example: 'Cross-currency settlement applies.'
5589
6423
  }
5590
- },
5591
- required: ['items', 'total']
5592
- } as const;
5593
-
5594
- export const $ParserTelemetryReportDto = {
5595
- type: 'object',
5596
- properties: {}
5597
- } as const;
5598
-
5599
- export const $UncoveredFormatMissDto = {
5600
- type: 'object',
5601
- properties: {}
6424
+ }
5602
6425
  } as const;
5603
6426
 
5604
6427
  export const $ProcessNlpDto = {
@@ -5606,10 +6429,17 @@ export const $ProcessNlpDto = {
5606
6429
  properties: {
5607
6430
  message: {
5608
6431
  type: 'string',
5609
- description: 'Natural language text describing a transaction (Chinese)',
5610
- example: 'yesterday Starbucks spent 35 yuan',
6432
+ description:
6433
+ 'Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.',
6434
+ example: 'Starbucks 35',
5611
6435
  maxLength: 500
5612
6436
  },
6437
+ confirm: {
6438
+ type: 'boolean',
6439
+ description:
6440
+ 'Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.',
6441
+ example: true
6442
+ },
5613
6443
  sessionId: {
5614
6444
  type: 'string',
5615
6445
  description:
@@ -5617,17 +6447,51 @@ export const $ProcessNlpDto = {
5617
6447
  example: 'session_abc123'
5618
6448
  },
5619
6449
  parsedData: {
5620
- type: 'object',
5621
6450
  description:
5622
6451
  'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
5623
6452
  example: {
5624
6453
  amount: 35,
5625
6454
  currency: 'CNY',
5626
6455
  payee: 'Starbucks'
5627
- }
6456
+ },
6457
+ allOf: [
6458
+ {
6459
+ $ref: '#/components/schemas/ClientParsedDataDto'
6460
+ }
6461
+ ]
6462
+ },
6463
+ selectedRuleId: {
6464
+ type: 'string',
6465
+ description:
6466
+ '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.',
6467
+ example: 'rule_abc123'
6468
+ },
6469
+ selectedAccount: {
6470
+ type: 'string',
6471
+ description:
6472
+ 'confirm_account echo-back: account path selected from the prior confirm_account response (suggestedAccount, similarAccounts[i].path, or a typed path). Applied directly when the session is confirming_account — no NL re-parse.',
6473
+ example: 'Expenses:Food:Coffee'
6474
+ },
6475
+ viewpointAccount: {
6476
+ type: 'string',
6477
+ description:
6478
+ 'Viewpoint account hint: the beancount path the user drilled into (e.g. from an account drill-down). Tie-break only — never overrides accounts resolved from the text. Must be an owned, OPEN Assets:/Liabilities: account; unresolvable hints are silently ignored.',
6479
+ example: 'Assets:CN:Bank:ICBC'
6480
+ },
6481
+ viewpointCategory: {
6482
+ type: 'string',
6483
+ description:
6484
+ "Viewpoint category hint: the ADR-0075 Group segment the user drilled into (e.g. 'Food'). Resolved to a concrete OPEN account in that group; tie-break only — never overrides a category resolved from the text.",
6485
+ example: 'Food'
6486
+ },
6487
+ viewpointFlow: {
6488
+ type: 'string',
6489
+ description:
6490
+ "Companion flow root for viewpointCategory ('income' | 'expense'), mirroring the ADR-0126 list-endpoint invariant. Derived from the session's routed intent (multi-turn) when absent; a first-turn flow-less category hint is dropped — send the flow explicitly.",
6491
+ enum: ['income', 'expense'],
6492
+ example: 'expense'
5628
6493
  }
5629
- },
5630
- required: ['message']
6494
+ }
5631
6495
  } as const;
5632
6496
 
5633
6497
  export const $NlpTransactionInfoDto = {
@@ -5693,7 +6557,9 @@ export const $NlpParsedDataDto = {
5693
6557
  },
5694
6558
  category: {
5695
6559
  type: 'string',
5696
- description: 'Category'
6560
+ description:
6561
+ 'Category in canonical form: a CATEGORY_CATALOG slug (GET /{region}/bean/categories) or a Stage-2 rule categoryKeywords token (ADR-0116 D2). Never a locale display name or a beancount account path. Echo back verbatim on confirm.',
6562
+ example: 'food'
5697
6563
  },
5698
6564
  incomeType: {
5699
6565
  type: 'string',
@@ -5939,6 +6805,24 @@ export const $NlpRuleConfirmationDataDto = {
5939
6805
  ]
5940
6806
  } as const;
5941
6807
 
6808
+ export const $NlpAccountCandidateDto = {
6809
+ type: 'object',
6810
+ properties: {
6811
+ path: {
6812
+ type: 'string',
6813
+ description: 'Canonical beancount account path (echo back on selection)',
6814
+ example: 'Expenses:Food:Dining'
6815
+ },
6816
+ name: {
6817
+ type: 'string',
6818
+ description:
6819
+ 'Localized display name (ADR-0114 read-time projection, user locale)',
6820
+ example: '餐饮'
6821
+ }
6822
+ },
6823
+ required: ['path', 'name']
6824
+ } as const;
6825
+
5942
6826
  export const $NlpAccountConfirmationDataDto = {
5943
6827
  type: 'object',
5944
6828
  properties: {
@@ -5949,14 +6833,16 @@ export const $NlpAccountConfirmationDataDto = {
5949
6833
  },
5950
6834
  suggestedAccount: {
5951
6835
  type: 'string',
5952
- description: 'Suggested replacement account',
6836
+ description:
6837
+ 'Suggested replacement account (omitted when no clear candidate)',
5953
6838
  example: 'Expenses:Food:Drinks'
5954
6839
  },
5955
6840
  similarAccounts: {
5956
- description: 'Similar accounts for user selection',
6841
+ description:
6842
+ 'Similar accounts for user selection (path + localized name, #680)',
5957
6843
  type: 'array',
5958
6844
  items: {
5959
- type: 'string'
6845
+ $ref: '#/components/schemas/NlpAccountCandidateDto'
5960
6846
  }
5961
6847
  },
5962
6848
  errorMessage: {
@@ -5971,7 +6857,6 @@ export const $NlpAccountConfirmationDataDto = {
5971
6857
  },
5972
6858
  required: [
5973
6859
  'invalidAccount',
5974
- 'suggestedAccount',
5975
6860
  'similarAccounts',
5976
6861
  'errorMessage',
5977
6862
  'transactionContext'
@@ -6144,7 +7029,8 @@ export const $NlpSuggestedAccountDto = {
6144
7029
  },
6145
7030
  confidence: {
6146
7031
  type: 'number',
6147
- description: 'Confidence score for this suggestion (0-1)',
7032
+ description:
7033
+ 'Confidence score for this suggestion (0-1). Present = predicted (confirm/confirm_rule/confirm_account); omitted = actual persisted account (created). (#586)',
6148
7034
  example: 0.9
6149
7035
  }
6150
7036
  },
@@ -6180,23 +7066,31 @@ export const $NlpDefaultAccountsDto = {
6180
7066
  properties: {
6181
7067
  asset: {
6182
7068
  type: 'string',
6183
- description: 'Default asset account',
6184
- example: 'Assets:Checking'
7069
+ description:
7070
+ 'Default OPEN asset account (MRU when multiple), or null when none/ambiguous',
7071
+ example: 'Assets:Checking',
7072
+ nullable: true
6185
7073
  },
6186
7074
  expense: {
6187
7075
  type: 'string',
6188
- description: 'Default expense account',
6189
- example: 'Expenses:Uncategorized'
7076
+ description:
7077
+ 'Default OPEN expense account (MRU when multiple), or null when none/ambiguous',
7078
+ example: 'Expenses:Food:Coffee',
7079
+ nullable: true
6190
7080
  },
6191
7081
  income: {
6192
7082
  type: 'string',
6193
- description: 'Default income account',
6194
- example: 'Income:Uncategorized'
7083
+ description:
7084
+ 'Default OPEN income account (MRU when multiple), or null when none/ambiguous',
7085
+ example: 'Income:Salary',
7086
+ nullable: true
6195
7087
  },
6196
7088
  liability: {
6197
7089
  type: 'string',
6198
- description: 'Default liability account',
6199
- example: 'Liabilities:CreditCard'
7090
+ description:
7091
+ 'Default OPEN liability account (MRU when multiple), or null when none/ambiguous',
7092
+ example: 'Liabilities:CreditCard',
7093
+ nullable: true
6200
7094
  }
6201
7095
  },
6202
7096
  required: ['asset', 'expense', 'income', 'liability']
@@ -6221,7 +7115,8 @@ export const $NlpResponseDto = {
6221
7115
  'confirm_rule',
6222
7116
  'confirm_account',
6223
7117
  'confirm_payee',
6224
- 'cancel'
7118
+ 'cancel',
7119
+ 'aborted'
6225
7120
  ]
6226
7121
  },
6227
7122
  intent: {
@@ -6235,7 +7130,7 @@ export const $NlpResponseDto = {
6235
7130
  type: 'string',
6236
7131
  description:
6237
7132
  'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
6238
- enum: ['transfer', 'banking', 'investment'],
7133
+ enum: ['transfer', 'banking', 'investment', 'lend', 'lend_collect'],
6239
7134
  example: 'investment'
6240
7135
  },
6241
7136
  liabilitySubType: {
@@ -6316,91 +7211,336 @@ export const $NlpResponseDto = {
6316
7211
  }
6317
7212
  ]
6318
7213
  },
6319
- duplicateData: {
7214
+ duplicateData: {
7215
+ description:
7216
+ 'Duplicate detection data (when action is "confirm_duplicate"). Contains information about potential duplicate transaction for user confirmation.',
7217
+ allOf: [
7218
+ {
7219
+ $ref: '#/components/schemas/NlpDuplicateConfirmationDataDto'
7220
+ }
7221
+ ]
7222
+ },
7223
+ ruleData: {
7224
+ description:
7225
+ 'Rule match data (when action is "confirm_rule"). Contains information about medium-confidence rule match for user confirmation.',
7226
+ allOf: [
7227
+ {
7228
+ $ref: '#/components/schemas/NlpRuleConfirmationDataDto'
7229
+ }
7230
+ ]
7231
+ },
7232
+ accountData: {
7233
+ description:
7234
+ 'Account validation data (when action is "confirm_account"). Contains information about invalid account for user correction.',
7235
+ allOf: [
7236
+ {
7237
+ $ref: '#/components/schemas/NlpAccountConfirmationDataDto'
7238
+ }
7239
+ ]
7240
+ },
7241
+ payeeData: {
7242
+ description:
7243
+ 'Payee confirmation data (when action is "confirm_payee"). Contains information about medium/low confidence payee match for user confirmation.',
7244
+ allOf: [
7245
+ {
7246
+ $ref: '#/components/schemas/NlpPayeeConfirmationDataDto'
7247
+ }
7248
+ ]
7249
+ },
7250
+ confidence: {
7251
+ type: 'number',
7252
+ description: 'Overall confidence score (0-1)',
7253
+ example: 0.85
7254
+ },
7255
+ confidenceThreshold: {
7256
+ type: 'number',
7257
+ description:
7258
+ 'Confidence threshold for automatic creation (default: 0.75). When confidence < threshold, action will be "confirm" requiring user verification.',
7259
+ example: 0.75
7260
+ },
7261
+ recurringMatch: {
7262
+ description:
7263
+ 'Recurring transaction match info (when action is "created"). Contains match details when transaction matches a pending expected transaction.',
7264
+ allOf: [
7265
+ {
7266
+ $ref: '#/components/schemas/RecurringMatchInfoDto'
7267
+ }
7268
+ ]
7269
+ },
7270
+ recurringSuggestion: {
7271
+ description:
7272
+ 'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
7273
+ allOf: [
7274
+ {
7275
+ $ref: '#/components/schemas/RecurringSuggestionDto'
7276
+ }
7277
+ ]
7278
+ },
7279
+ suggestedAccounts: {
7280
+ description:
7281
+ '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.',
7282
+ allOf: [
7283
+ {
7284
+ $ref: '#/components/schemas/NlpSuggestedAccountsDto'
7285
+ }
7286
+ ]
7287
+ },
7288
+ defaultAccounts: {
7289
+ description:
7290
+ 'Default fallback accounts for the user/region (#586). v1 returns universal constants; per-user personalization is planned.',
7291
+ allOf: [
7292
+ {
7293
+ $ref: '#/components/schemas/NlpDefaultAccountsDto'
7294
+ }
7295
+ ]
7296
+ }
7297
+ },
7298
+ required: ['status', 'action']
7299
+ } as const;
7300
+
7301
+ export const $PlatformListItemDto = {
7302
+ type: 'object',
7303
+ properties: {
7304
+ id: {
7305
+ type: 'string',
7306
+ description: 'Global platform ID'
7307
+ },
7308
+ name: {
7309
+ type: 'string',
7310
+ description: 'Platform name'
7311
+ },
7312
+ url: {
7313
+ type: 'string',
7314
+ description: 'Platform URL'
7315
+ },
7316
+ type: {
7317
+ type: 'string',
7318
+ description: 'Platform type',
7319
+ enum: [
7320
+ 'BANK',
7321
+ 'BROKERAGE',
7322
+ 'CRYPTO_EXCHANGE',
7323
+ 'PAYMENT',
7324
+ 'INVESTMENT',
7325
+ 'INSURANCE',
7326
+ 'OTHER'
7327
+ ]
7328
+ },
7329
+ canonical: {
7330
+ type: 'string',
7331
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
7332
+ },
7333
+ suggestedSegment: {
7334
+ type: 'string',
7335
+ description:
7336
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
7337
+ },
7338
+ logoUrl: {
7339
+ type: 'string',
7340
+ description: 'Logo URL',
7341
+ nullable: true
7342
+ },
7343
+ countryCode: {
7344
+ type: 'string',
7345
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
7346
+ example: 'CN',
7347
+ nullable: true
7348
+ },
7349
+ category: {
7350
+ type: 'string',
7351
+ description:
7352
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
7353
+ nullable: true,
7354
+ example: 'DigitalWallet'
7355
+ },
7356
+ isBound: {
7357
+ type: 'boolean',
7358
+ description: 'Whether user has accounts using this platform'
7359
+ }
7360
+ },
7361
+ required: [
7362
+ 'id',
7363
+ 'name',
7364
+ 'url',
7365
+ 'type',
7366
+ 'canonical',
7367
+ 'suggestedSegment',
7368
+ 'logoUrl',
7369
+ 'countryCode',
7370
+ 'category',
7371
+ 'isBound'
7372
+ ]
7373
+ } as const;
7374
+
7375
+ export const $PlatformMatchResultDto = {
7376
+ type: 'object',
7377
+ properties: {
7378
+ id: {
7379
+ type: 'string',
7380
+ description: 'Global platform ID'
7381
+ },
7382
+ name: {
7383
+ type: 'string',
7384
+ description: 'Platform name (e.g., "ICBC")'
7385
+ },
7386
+ canonical: {
7387
+ type: 'string',
7388
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
7389
+ },
7390
+ type: {
7391
+ type: 'string',
7392
+ description: 'Platform type',
7393
+ enum: [
7394
+ 'BANK',
7395
+ 'BROKERAGE',
7396
+ 'CRYPTO_EXCHANGE',
7397
+ 'PAYMENT',
7398
+ 'INVESTMENT',
7399
+ 'INSURANCE',
7400
+ 'OTHER'
7401
+ ]
7402
+ },
7403
+ suggestedSegment: {
7404
+ type: 'string',
6320
7405
  description:
6321
- 'Duplicate detection data (when action is "confirm_duplicate"). Contains information about potential duplicate transaction for user confirmation.',
6322
- allOf: [
6323
- {
6324
- $ref: '#/components/schemas/NlpDuplicateConfirmationDataDto'
6325
- }
6326
- ]
7406
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
6327
7407
  },
6328
- ruleData: {
6329
- description:
6330
- 'Rule match data (when action is "confirm_rule"). Contains information about medium-confidence rule match for user confirmation.',
6331
- allOf: [
6332
- {
6333
- $ref: '#/components/schemas/NlpRuleConfirmationDataDto'
6334
- }
6335
- ]
7408
+ logoUrl: {
7409
+ type: 'string',
7410
+ description: 'Logo URL',
7411
+ nullable: true
6336
7412
  },
6337
- accountData: {
7413
+ countryCode: {
7414
+ type: 'string',
7415
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
7416
+ example: 'CN',
7417
+ nullable: true
7418
+ },
7419
+ category: {
7420
+ type: 'string',
6338
7421
  description:
6339
- 'Account validation data (when action is "confirm_account"). Contains information about invalid account for user correction.',
6340
- allOf: [
6341
- {
6342
- $ref: '#/components/schemas/NlpAccountConfirmationDataDto'
6343
- }
6344
- ]
7422
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
7423
+ nullable: true,
7424
+ example: 'DigitalWallet'
6345
7425
  },
6346
- payeeData: {
7426
+ matchType: {
7427
+ type: 'string',
7428
+ description: "How this row matched: 'exact' > 'prefix' > 'substring'",
7429
+ enum: ['exact', 'prefix', 'substring']
7430
+ }
7431
+ },
7432
+ required: [
7433
+ 'id',
7434
+ 'name',
7435
+ 'canonical',
7436
+ 'type',
7437
+ 'suggestedSegment',
7438
+ 'logoUrl',
7439
+ 'countryCode',
7440
+ 'category',
7441
+ 'matchType'
7442
+ ]
7443
+ } as const;
7444
+
7445
+ export const $PlatformMatchResponseDto = {
7446
+ type: 'object',
7447
+ properties: {
7448
+ platforms: {
7449
+ description: 'Ranked matches, best tier first (at most 10 rows)',
7450
+ type: 'array',
7451
+ items: {
7452
+ $ref: '#/components/schemas/PlatformMatchResultDto'
7453
+ }
7454
+ },
7455
+ matchType: {
7456
+ type: 'string',
6347
7457
  description:
6348
- 'Payee confirmation data (when action is "confirm_payee"). Contains information about medium/low confidence payee match for user confirmation.',
6349
- allOf: [
6350
- {
6351
- $ref: '#/components/schemas/NlpPayeeConfirmationDataDto'
6352
- }
6353
- ]
7458
+ "Overall match quality — top row's tier, or 'none' when no hits",
7459
+ enum: ['none', 'exact', 'prefix', 'substring']
6354
7460
  },
6355
- confidence: {
7461
+ total: {
6356
7462
  type: 'number',
6357
- description: 'Overall confidence score (0-1)',
6358
- example: 0.85
7463
+ description: 'Total matches before LIMIT (truncation transparency)'
6359
7464
  },
6360
- confidenceThreshold: {
6361
- type: 'number',
6362
- description:
6363
- 'Confidence threshold for automatic creation (default: 0.75). When confidence < threshold, action will be "confirm" requiring user verification.',
6364
- example: 0.75
7465
+ hasMore: {
7466
+ type: 'boolean',
7467
+ description: 'true when total > platforms.length (more matches exist)'
7468
+ }
7469
+ },
7470
+ required: ['platforms', 'matchType', 'total', 'hasMore']
7471
+ } as const;
7472
+
7473
+ export const $PlatformStandardsPlatformDto = {
7474
+ type: 'object',
7475
+ properties: {
7476
+ id: {
7477
+ type: 'string',
7478
+ description: 'Global platform ID'
6365
7479
  },
6366
- recurringMatch: {
7480
+ name: {
7481
+ type: 'string',
7482
+ description: 'Platform name (e.g., "ICBC")'
7483
+ },
7484
+ canonical: {
7485
+ type: 'string',
7486
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
7487
+ },
7488
+ suggestedSegment: {
7489
+ type: 'string',
6367
7490
  description:
6368
- 'Recurring transaction match info (when action is "created"). Contains match details when transaction matches a pending expected transaction.',
6369
- allOf: [
6370
- {
6371
- $ref: '#/components/schemas/RecurringMatchInfoDto'
6372
- }
7491
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
7492
+ },
7493
+ type: {
7494
+ type: 'string',
7495
+ description: 'Platform type',
7496
+ enum: [
7497
+ 'BANK',
7498
+ 'BROKERAGE',
7499
+ 'CRYPTO_EXCHANGE',
7500
+ 'PAYMENT',
7501
+ 'INVESTMENT',
7502
+ 'INSURANCE',
7503
+ 'OTHER'
6373
7504
  ]
6374
7505
  },
6375
- recurringSuggestion: {
7506
+ category: {
7507
+ type: 'string',
6376
7508
  description:
6377
- 'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
7509
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank) resolved against the final region. null = no region-aware suggestion; fall back to type.',
7510
+ nullable: true,
7511
+ example: 'Bank'
7512
+ }
7513
+ },
7514
+ required: ['id', 'name', 'canonical', 'suggestedSegment', 'type', 'category']
7515
+ } as const;
7516
+
7517
+ export const $PlatformStandardsResponseDto = {
7518
+ type: 'object',
7519
+ properties: {
7520
+ platform: {
7521
+ description: 'The selected platform (institution lock source)',
6378
7522
  allOf: [
6379
7523
  {
6380
- $ref: '#/components/schemas/RecurringSuggestionDto'
7524
+ $ref: '#/components/schemas/PlatformStandardsPlatformDto'
6381
7525
  }
6382
7526
  ]
6383
7527
  },
6384
- suggestedAccounts: {
7528
+ region: {
7529
+ type: 'string',
6385
7530
  description:
6386
- 'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
6387
- allOf: [
6388
- {
6389
- $ref: '#/components/schemas/NlpSuggestedAccountsDto'
6390
- }
6391
- ]
7531
+ "Resolved template region (ISO 3166-1 alpha-2, UPPERCASE): the platform's own countryCode when set, else the region query param. For regions without a regional template file the template list falls back to the universal-only catalog while region still echoes the code.",
7532
+ example: 'CN'
6392
7533
  },
6393
- defaultAccounts: {
7534
+ templates: {
6394
7535
  description:
6395
- 'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
6396
- allOf: [
6397
- {
6398
- $ref: '#/components/schemas/NlpDefaultAccountsDto'
6399
- }
6400
- ]
7536
+ 'Candidate account-standard templates of the resolved region (groupable by productCategory client-side)',
7537
+ type: 'array',
7538
+ items: {
7539
+ $ref: '#/components/schemas/AccountStandardResponseDto'
7540
+ }
6401
7541
  }
6402
7542
  },
6403
- required: ['status', 'action']
7543
+ required: ['platform', 'region', 'templates']
6404
7544
  } as const;
6405
7545
 
6406
7546
  export const $CreatePlatformDto = {
@@ -6504,7 +7644,8 @@ export const $UpdatePlatformDto = {
6504
7644
  },
6505
7645
  isActive: {
6506
7646
  type: 'boolean',
6507
- description: 'Whether the platform is active'
7647
+ description: 'Whether the platform is active',
7648
+ default: true
6508
7649
  }
6509
7650
  }
6510
7651
  } as const;
@@ -6667,7 +7808,8 @@ export const $AccountItemDto = {
6667
7808
  },
6668
7809
  displayName: {
6669
7810
  type: 'string',
6670
- description: 'Display name (last part of account path)',
7811
+ description:
7812
+ 'Display name: user-set name if provided (#762), else the ADR-0114 chain — request-locale catalog name, en pivot, then the last part of the account path (#771)',
6671
7813
  example: 'Savings'
6672
7814
  },
6673
7815
  balance: {
@@ -6703,7 +7845,8 @@ export const $PlatformGroupDto = {
6703
7845
  example: 'CMB Bank'
6704
7846
  },
6705
7847
  accounts: {
6706
- description: 'Accounts within this platform',
7848
+ description:
7849
+ 'Accounts within this platform (Assets and Liabilities rows, #696)',
6707
7850
  type: 'array',
6708
7851
  items: {
6709
7852
  $ref: '#/components/schemas/AccountItemDto'
@@ -6711,7 +7854,8 @@ export const $PlatformGroupDto = {
6711
7854
  },
6712
7855
  totalBalance: {
6713
7856
  type: 'string',
6714
- description: 'FX-converted total balance in base currency',
7857
+ description:
7858
+ 'FX-converted total balance in base currency (nets Assets + Liabilities rows; can be negative)',
6715
7859
  example: '100000.00'
6716
7860
  },
6717
7861
  balanceByCurrency: {
@@ -6730,7 +7874,7 @@ export const $PlatformGroupDto = {
6730
7874
  sharePct: {
6731
7875
  type: 'number',
6732
7876
  description:
6733
- 'Share of the grand converted total (0-100); 0 when grand total is 0',
7877
+ 'Share of the converted asset-side grand total (0-100); liability balances are excluded from the basis; 0 when grand total is 0 (#696)',
6734
7878
  example: 42.5
6735
7879
  }
6736
7880
  },
@@ -6778,7 +7922,8 @@ export const $AccountsSummaryDto = {
6778
7922
  properties: {
6779
7923
  totalAccounts: {
6780
7924
  type: 'number',
6781
- description: 'Total number of accounts'
7925
+ description:
7926
+ 'Total number of accounts (balance sheet: Assets + Liabilities, #696)'
6782
7927
  },
6783
7928
  totalPlatforms: {
6784
7929
  type: 'number',
@@ -6836,7 +7981,8 @@ export const $AccountItemWithAssetClassDto = {
6836
7981
  },
6837
7982
  displayName: {
6838
7983
  type: 'string',
6839
- description: 'Display name (last part of account path)',
7984
+ description:
7985
+ 'Display name: user-set name if provided (#762), else the ADR-0114 chain — request-locale catalog name, en pivot, then the last part of the account path (#771)',
6840
7986
  example: 'Savings'
6841
7987
  },
6842
7988
  balance: {
@@ -7322,7 +8468,7 @@ export const $MonetaryDto = {
7322
8468
  example: 'USD'
7323
8469
  },
7324
8470
  baseCcyEquivalent: {
7325
- type: 'object',
8471
+ type: 'string',
7326
8472
  description: 'Converted to user base currency (Decimal string)',
7327
8473
  example: '21600',
7328
8474
  nullable: true
@@ -7398,13 +8544,13 @@ export const $HoldingPnlRowDto = {
7398
8544
  example: 'Assets:US:Broker:AAPL'
7399
8545
  },
7400
8546
  accountCcy: {
7401
- type: 'object',
8547
+ type: 'string',
7402
8548
  description: 'Account settlement currency (ISO 4217), from cost currency',
7403
8549
  nullable: true,
7404
8550
  example: 'USD'
7405
8551
  },
7406
8552
  brokerType: {
7407
- type: 'object',
8553
+ type: 'string',
7408
8554
  description: 'Broker type derived from Platform.type',
7409
8555
  nullable: true,
7410
8556
  example: 'broker'
@@ -7425,7 +8571,7 @@ export const $HoldingPnlRowDto = {
7425
8571
  example: 'EQUITY'
7426
8572
  },
7427
8573
  assetSubClass: {
7428
- type: 'object',
8574
+ type: 'string',
7429
8575
  nullable: true,
7430
8576
  example: 'STOCK'
7431
8577
  },
@@ -7472,14 +8618,14 @@ export const $HoldingPnlRowDto = {
7472
8618
  ]
7473
8619
  },
7474
8620
  unrealizedPnlBase: {
7475
- type: 'object',
8621
+ type: 'string',
7476
8622
  description:
7477
8623
  'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
7478
8624
  nullable: true,
7479
8625
  example: '6000'
7480
8626
  },
7481
8627
  unrealizedPnlPct: {
7482
- type: 'object',
8628
+ type: 'string',
7483
8629
  description: 'Unrealized P&L % (Decimal string)',
7484
8630
  nullable: true,
7485
8631
  example: '25'
@@ -7503,7 +8649,7 @@ export const $HoldingPnlRowDto = {
7503
8649
  ]
7504
8650
  },
7505
8651
  pctOfInvestedAssets: {
7506
- type: 'object',
8652
+ type: 'string',
7507
8653
  description:
7508
8654
  'Share of invested assets % (Decimal string); only for invested chartTokens',
7509
8655
  nullable: true,
@@ -7548,15 +8694,15 @@ export const $HoldingPnlWarningDto = {
7548
8694
  ]
7549
8695
  },
7550
8696
  symbol: {
7551
- type: 'object',
8697
+ type: 'string',
7552
8698
  nullable: true
7553
8699
  },
7554
8700
  accountId: {
7555
- type: 'object',
8701
+ type: 'string',
7556
8702
  nullable: true
7557
8703
  },
7558
8704
  currency: {
7559
- type: 'object',
8705
+ type: 'string',
7560
8706
  nullable: true
7561
8707
  }
7562
8708
  },
@@ -7597,292 +8743,378 @@ export const $HoldingPnlResponseDto = {
7597
8743
  required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
7598
8744
  } as const;
7599
8745
 
7600
- export const $CurrencyBalanceDto = {
8746
+ export const $AnonymousLoginDto = {
7601
8747
  type: 'object',
7602
8748
  properties: {
7603
- currency: {
8749
+ accessToken: {
7604
8750
  type: 'string',
7605
- description: 'ISO 4217 currency code',
7606
- example: 'CNY'
7607
- },
7608
- balance: {
8751
+ description: 'Access token for anonymous login'
8752
+ }
8753
+ },
8754
+ required: ['accessToken']
8755
+ } as const;
8756
+
8757
+ export const $AnonymousLoginResponseDto = {
8758
+ type: 'object',
8759
+ properties: {
8760
+ authToken: {
7609
8761
  type: 'string',
7610
- description: 'Balance amount',
7611
- example: '500000.00'
8762
+ description: 'JWT auth token',
8763
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
7612
8764
  }
7613
8765
  },
7614
- required: ['currency', 'balance']
8766
+ required: ['authToken']
7615
8767
  } as const;
7616
8768
 
7617
- export const $TimeSeriesPointDto = {
8769
+ export const $ParserContributionMetaDto = {
7618
8770
  type: 'object',
7619
8771
  properties: {
7620
- date: {
8772
+ institution: {
7621
8773
  type: 'string',
7622
- description: 'Date in YYYY-MM-DD format',
7623
- example: '2024-06-15'
8774
+ description: 'Institution slug (lowercase kebab-case)',
8775
+ pattern: '^[a-z0-9]+(-[a-z0-9]+)*$',
8776
+ example: 'icbc'
7624
8777
  },
7625
- value: {
8778
+ region: {
7626
8779
  type: 'string',
7627
- description: 'Value at this date (in base currency)',
7628
- example: '500000.00'
8780
+ enum: [
8781
+ 'cn',
8782
+ 'us',
8783
+ 'de',
8784
+ 'fr',
8785
+ 'gb',
8786
+ 'hk',
8787
+ 'jp',
8788
+ 'sg',
8789
+ 'au',
8790
+ 'ca',
8791
+ 'other'
8792
+ ]
7629
8793
  },
7630
- change: {
7631
- type: 'object',
7632
- description: 'Change from previous point',
7633
- example: '5000.00'
8794
+ accountType: {
8795
+ type: 'string',
8796
+ enum: ['checking', 'savings', 'credit', 'debit', 'investment']
7634
8797
  },
7635
- assets: {
8798
+ format: {
7636
8799
  type: 'string',
7637
- description: 'Total assets at this date (in base currency)',
7638
- example: '494338.00'
8800
+ enum: ['csv', 'xlsx', 'pdf', 'ofx', 'qif']
7639
8801
  },
7640
- liabilities: {
8802
+ institutionDisplayName: {
7641
8803
  type: 'string',
7642
- description: 'Total liabilities at this date (in base currency)',
7643
- example: '310098.00'
8804
+ example: '中国工商银行'
7644
8805
  },
7645
- byCurrency: {
7646
- description: 'Multi-currency breakdown for this point',
8806
+ encoding: {
8807
+ type: 'string',
8808
+ example: 'utf-8'
8809
+ },
8810
+ delimiter: {
8811
+ type: 'string',
8812
+ description: 'CSV delimiter character: ",", ";", "\\t" or "|"'
8813
+ },
8814
+ headerRows: {
8815
+ type: 'number',
8816
+ default: 1,
8817
+ description: 'Header row count; the client omits the field when it is 1'
8818
+ },
8819
+ notes: {
8820
+ type: 'string',
8821
+ maxLength: 2000
8822
+ }
8823
+ },
8824
+ required: ['institution', 'region', 'accountType', 'format']
8825
+ } as const;
8826
+
8827
+ export const $ParserContributionSamplesDto = {
8828
+ type: 'object',
8829
+ properties: {
8830
+ rows: {
8831
+ description:
8832
+ 'Client-sanitized sample rows (key = column name, value = cell)',
7647
8833
  type: 'array',
7648
8834
  items: {
7649
- $ref: '#/components/schemas/CurrencyBalanceDto'
8835
+ type: 'object'
7650
8836
  }
8837
+ },
8838
+ rawHeaders: {
8839
+ type: 'array',
8840
+ items: {
8841
+ type: 'string'
8842
+ }
8843
+ }
8844
+ },
8845
+ required: ['rows']
8846
+ } as const;
8847
+
8848
+ export const $FieldHintDto = {
8849
+ type: 'object',
8850
+ properties: {
8851
+ columnName: {
8852
+ type: 'string',
8853
+ example: '交易日期'
8854
+ },
8855
+ format: {
8856
+ type: 'string',
8857
+ description: 'Date format, e.g. yyyy-MM-dd HH:mm',
8858
+ example: 'yyyy-MM-dd'
8859
+ },
8860
+ signConvention: {
8861
+ type: 'string',
8862
+ enum: ['negative-expense', 'positive-expense', 'separate-columns']
8863
+ },
8864
+ creditColumn: {
8865
+ type: 'string'
8866
+ },
8867
+ debitColumn: {
8868
+ type: 'string'
8869
+ }
8870
+ },
8871
+ required: ['columnName']
8872
+ } as const;
8873
+
8874
+ export const $ParserContributionFieldHintsDto = {
8875
+ type: 'object',
8876
+ properties: {
8877
+ date: {
8878
+ $ref: '#/components/schemas/FieldHintDto'
8879
+ },
8880
+ amount: {
8881
+ $ref: '#/components/schemas/FieldHintDto'
8882
+ },
8883
+ description: {
8884
+ $ref: '#/components/schemas/FieldHintDto'
8885
+ },
8886
+ balance: {
8887
+ $ref: '#/components/schemas/FieldHintDto'
8888
+ },
8889
+ payee: {
8890
+ $ref: '#/components/schemas/FieldHintDto'
8891
+ },
8892
+ reference: {
8893
+ $ref: '#/components/schemas/FieldHintDto'
8894
+ },
8895
+ category: {
8896
+ $ref: '#/components/schemas/FieldHintDto'
7651
8897
  }
7652
8898
  },
7653
- required: ['date', 'value']
8899
+ required: ['date', 'amount']
7654
8900
  } as const;
7655
8901
 
7656
- export const $TrendSummaryDto = {
8902
+ export const $ExpectedTransactionDto = {
7657
8903
  type: 'object',
7658
8904
  properties: {
7659
- startValue: {
8905
+ date: {
7660
8906
  type: 'string',
7661
- description: 'Value at start of period',
7662
- example: '450000.00'
8907
+ example: '2026-08-01'
7663
8908
  },
7664
- endValue: {
7665
- type: 'string',
7666
- description: 'Value at end of period',
7667
- example: '500000.00'
8909
+ amount: {
8910
+ type: 'number',
8911
+ example: -45.5
7668
8912
  },
7669
- totalChange: {
8913
+ description: {
7670
8914
  type: 'string',
7671
- description: 'Total change over period',
7672
- example: '50000.00'
8915
+ example: '星巴克-***店'
7673
8916
  },
7674
- totalChangePercentage: {
7675
- type: 'string',
7676
- description: 'Total change percentage',
7677
- example: '+11.11%'
8917
+ payee: {
8918
+ type: 'string'
8919
+ },
8920
+ category: {
8921
+ type: 'string'
7678
8922
  }
7679
8923
  },
7680
- required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
8924
+ required: ['date', 'amount', 'description']
7681
8925
  } as const;
7682
8926
 
7683
- export const $MultiCurrencyPointDto = {
8927
+ export const $ParserContributionExamplesDto = {
7684
8928
  type: 'object',
7685
8929
  properties: {
7686
- date: {
7687
- type: 'string',
7688
- description: 'Date in YYYY-MM-DD format',
7689
- example: '2024-06-15'
7690
- },
7691
- byCurrency: {
7692
- description: 'Balances by currency',
8930
+ expectedTransactions: {
7693
8931
  type: 'array',
7694
8932
  items: {
7695
- $ref: '#/components/schemas/CurrencyBalanceDto'
8933
+ $ref: '#/components/schemas/ExpectedTransactionDto'
7696
8934
  }
7697
8935
  }
7698
8936
  },
7699
- required: ['date', 'byCurrency']
8937
+ required: ['expectedTransactions']
7700
8938
  } as const;
7701
8939
 
7702
- export const $PortfolioTrendsResponseDto = {
8940
+ export const $ParserContributionRequestDto = {
7703
8941
  type: 'object',
7704
8942
  properties: {
7705
- series: {
7706
- description: 'Time series data points',
7707
- type: 'array',
7708
- items: {
7709
- $ref: '#/components/schemas/TimeSeriesPointDto'
7710
- }
8943
+ meta: {
8944
+ $ref: '#/components/schemas/ParserContributionMetaDto'
7711
8945
  },
7712
- summary: {
7713
- description: 'Period summary',
8946
+ samples: {
8947
+ $ref: '#/components/schemas/ParserContributionSamplesDto'
8948
+ },
8949
+ fieldHints: {
8950
+ $ref: '#/components/schemas/ParserContributionFieldHintsDto'
8951
+ },
8952
+ examples: {
8953
+ description: 'Omitted entirely by the client when empty',
7714
8954
  allOf: [
7715
8955
  {
7716
- $ref: '#/components/schemas/TrendSummaryDto'
8956
+ $ref: '#/components/schemas/ParserContributionExamplesDto'
7717
8957
  }
7718
8958
  ]
7719
- },
7720
- period: {
7721
- type: 'string',
7722
- description: 'Period requested',
7723
- example: '6m'
7724
- },
7725
- granularity: {
7726
- type: 'string',
7727
- description: 'Data granularity',
7728
- example: 'month'
7729
- },
7730
- currency: {
8959
+ }
8960
+ },
8961
+ required: ['meta', 'samples', 'fieldHints']
8962
+ } as const;
8963
+
8964
+ export const $ParserContributionRelayResponseDto = {
8965
+ type: 'object',
8966
+ properties: {
8967
+ issueUrl: {
7731
8968
  type: 'string',
7732
- description: 'Base currency for converted values',
7733
- example: 'CNY'
7734
- },
7735
- byCurrency: {
7736
- description:
7737
- 'Multi-currency time series (each point has currency breakdown)',
7738
- type: 'array',
7739
- items: {
7740
- $ref: '#/components/schemas/MultiCurrencyPointDto'
7741
- }
8969
+ example: 'https://github.com/fire-zu/firela-vlt/issues/42'
7742
8970
  },
7743
- warnings: {
7744
- description: 'Exchange rate warnings',
7745
- type: 'array',
7746
- items: {
7747
- $ref: '#/components/schemas/ExchangeRateWarningDto'
7748
- }
8971
+ issueNumber: {
8972
+ type: 'number',
8973
+ example: 42
7749
8974
  }
7750
8975
  },
7751
- required: ['series', 'summary', 'period', 'granularity', 'currency']
8976
+ required: ['issueUrl', 'issueNumber']
7752
8977
  } as const;
7753
8978
 
7754
- export const $CashFlowPointDto = {
8979
+ export const $SymbolSearchResultDto = {
7755
8980
  type: 'object',
7756
8981
  properties: {
7757
- month: {
8982
+ symbol: {
7758
8983
  type: 'string',
7759
- description: 'Month key (YYYY-MM)',
7760
- example: '2024-03'
8984
+ example: 'AAPL'
7761
8985
  },
7762
- income: {
8986
+ name: {
7763
8987
  type: 'string',
7764
- description: 'Income in base currency (absolute, converted)',
7765
- example: '10000.00'
8988
+ example: 'Apple Inc.',
8989
+ nullable: true
7766
8990
  },
7767
- expense: {
8991
+ exchange: {
7768
8992
  type: 'string',
7769
- description: 'Expense in base currency (absolute, converted)',
7770
- example: '5000.00'
8993
+ example: 'US',
8994
+ nullable: true
7771
8995
  },
7772
- netSavings: {
8996
+ assetType: {
7773
8997
  type: 'string',
7774
- description: 'netSavings = income − expense (savings positive)',
7775
- example: '5000.00'
8998
+ description: 'OpenBB asset_type (e.g. stock, etf)',
8999
+ example: 'stock',
9000
+ nullable: true
9001
+ },
9002
+ assetClass: {
9003
+ type: 'string',
9004
+ description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
9005
+ example: 'EQUITY',
9006
+ nullable: true
9007
+ },
9008
+ assetSubClass: {
9009
+ type: 'string',
9010
+ description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
9011
+ example: 'STOCK',
9012
+ nullable: true
9013
+ },
9014
+ currency: {
9015
+ type: 'string',
9016
+ description: 'Trading currency (extra_data or inferred from exchange)',
9017
+ example: 'USD',
9018
+ nullable: true
7776
9019
  }
7777
9020
  },
7778
- required: ['month', 'income', 'expense', 'netSavings']
9021
+ required: ['symbol']
7779
9022
  } as const;
7780
9023
 
7781
- export const $CashFlowTrendSummaryDto = {
9024
+ export const $SymbolQuoteDto = {
7782
9025
  type: 'object',
7783
9026
  properties: {
7784
- totalIncome: {
9027
+ symbol: {
7785
9028
  type: 'string',
7786
- description: 'Total income across the period',
7787
- example: '60000.00'
9029
+ example: 'AAPL'
7788
9030
  },
7789
- totalExpense: {
9031
+ name: {
7790
9032
  type: 'string',
7791
- description: 'Total expense across the period',
7792
- example: '30000.00'
9033
+ example: 'Apple Inc.',
9034
+ nullable: true
7793
9035
  },
7794
- totalNetSavings: {
9036
+ exchange: {
7795
9037
  type: 'string',
7796
- description: 'income − expense across the period',
7797
- example: '30000.00'
9038
+ example: 'US',
9039
+ nullable: true
7798
9040
  },
7799
- averageMonthlyNetSavings: {
9041
+ assetType: {
7800
9042
  type: 'string',
9043
+ description: 'OpenBB asset_type',
9044
+ example: 'stock',
9045
+ nullable: true
9046
+ },
9047
+ assetClass: {
9048
+ type: 'string',
9049
+ description: 'IGN asset class',
9050
+ example: 'EQUITY',
9051
+ nullable: true
9052
+ },
9053
+ assetSubClass: {
9054
+ type: 'string',
9055
+ description: 'IGN asset sub-class',
9056
+ example: 'STOCK',
9057
+ nullable: true
9058
+ },
9059
+ currency: {
9060
+ type: 'string',
9061
+ description: 'Trading currency (extra_data or inferred from exchange)',
9062
+ example: 'USD',
9063
+ nullable: true
9064
+ },
9065
+ price: {
9066
+ type: 'string',
9067
+ description: 'Latest price (Decimal string)',
9068
+ example: '189.84',
9069
+ nullable: true
9070
+ },
9071
+ priceDate: {
9072
+ type: 'string',
9073
+ description: 'Date the price was observed (ISO yyyy-MM-dd)',
9074
+ example: '2026-08-05',
9075
+ nullable: true
9076
+ },
9077
+ changePercent: {
9078
+ type: 'number',
7801
9079
  description:
7802
- 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
7803
- example: '5000.00'
7804
- }
7805
- },
7806
- required: [
7807
- 'totalIncome',
7808
- 'totalExpense',
7809
- 'totalNetSavings',
7810
- 'averageMonthlyNetSavings'
7811
- ]
7812
- } as const;
7813
-
7814
- export const $CashFlowTrendsResponseDto = {
7815
- type: 'object',
7816
- properties: {
7817
- series: {
7818
- description:
7819
- 'Monthly cash-flow series (fixed N-month window, zero-filled)',
7820
- type: 'array',
7821
- items: {
7822
- $ref: '#/components/schemas/CashFlowPointDto'
7823
- }
9080
+ '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.',
9081
+ example: 1.7,
9082
+ nullable: true
7824
9083
  },
7825
- summary: {
7826
- description: 'Period totals',
7827
- allOf: [
7828
- {
7829
- $ref: '#/components/schemas/CashFlowTrendSummaryDto'
7830
- }
7831
- ]
9084
+ prevClose: {
9085
+ type: 'string',
9086
+ description: 'Previous close (Decimal string)',
9087
+ nullable: true
7832
9088
  },
7833
- period: {
9089
+ open: {
7834
9090
  type: 'string',
7835
- description: 'Period requested',
7836
- example: '6m'
9091
+ description: 'Day open (Decimal string)',
9092
+ nullable: true
7837
9093
  },
7838
- granularity: {
9094
+ high: {
7839
9095
  type: 'string',
7840
- description: 'Data granularity (v1 returns month buckets)',
7841
- example: 'month'
9096
+ description: 'Day high (Decimal string)',
9097
+ nullable: true
7842
9098
  },
7843
- currency: {
9099
+ low: {
7844
9100
  type: 'string',
7845
- description: 'Base currency for converted values',
7846
- example: 'CNY'
9101
+ description: 'Day low (Decimal string)',
9102
+ nullable: true
7847
9103
  },
7848
- warnings: {
7849
- description: 'Exchange rate warnings (e.g. missing rate for a currency)',
7850
- type: 'array',
7851
- items: {
7852
- $ref: '#/components/schemas/ExchangeRateWarningDto'
7853
- }
7854
- }
7855
- },
7856
- required: ['series', 'summary', 'period', 'granularity', 'currency']
7857
- } as const;
7858
-
7859
- export const $GenerateSnapshotBody = {
7860
- type: 'object',
7861
- properties: {}
7862
- } as const;
7863
-
7864
- export const $GenerateSnapshotResponse = {
7865
- type: 'object',
7866
- properties: {}
7867
- } as const;
7868
-
7869
- export const $BackfillSnapshotsBody = {
7870
- type: 'object',
7871
- properties: {}
7872
- } as const;
7873
-
7874
- export const $BackfillSnapshotsResponse = {
7875
- type: 'object',
7876
- properties: {}
7877
- } as const;
7878
-
7879
- export const $AnonymousLoginDto = {
7880
- type: 'object',
7881
- properties: {
7882
- accessToken: {
9104
+ volume: {
7883
9105
  type: 'string',
7884
- description: 'Access token for anonymous login'
9106
+ description: 'Day volume (Decimal string)',
9107
+ nullable: true
9108
+ },
9109
+ yearHigh: {
9110
+ type: 'string',
9111
+ description: '52-week high (Decimal string)',
9112
+ nullable: true
9113
+ },
9114
+ yearLow: {
9115
+ type: 'string',
9116
+ description: '52-week low (Decimal string)',
9117
+ nullable: true
7885
9118
  }
7886
- },
7887
- required: ['accessToken']
9119
+ }
7888
9120
  } as const;