@firela/api-types 0.0.0-canary.1917579c → 0.0.0-canary.1f73c8b3

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.
@@ -6,18 +6,12 @@ export const $CreateAccountDto = {
6
6
  path: {
7
7
  type: 'string',
8
8
  description: 'Account path (hierarchical, colon-separated)',
9
- example: 'Assets:CN:Bank:ICBC:Checking'
10
- },
11
- displayName: {
12
- type: 'string',
13
- description:
14
- 'Display name to distinguish accounts at the same path (default: "")',
15
- example: '工资卡'
9
+ example: 'Assets:CN:ICBC:Checking'
16
10
  },
17
11
  openDate: {
18
12
  format: 'date-time',
19
13
  type: 'string',
20
- description: 'Account open date',
14
+ description: 'Account open date (server defaults to today)',
21
15
  example: '2024-01-01'
22
16
  },
23
17
  currencies: {
@@ -45,26 +39,22 @@ export const $CreateAccountDto = {
45
39
  templatePath: {
46
40
  type: 'string',
47
41
  description: 'Reference to account-standards template path',
48
- example: 'Assets:CN:Bank:ICBC:Checking'
42
+ example: 'Assets:CN:Checking'
49
43
  },
50
44
  isCustom: {
51
45
  type: 'boolean',
52
46
  description: 'Whether this is a custom (user-created) account',
53
47
  default: false
54
48
  },
55
- i18nKey: {
56
- type: 'string',
57
- description: 'i18n key for display name (overrides template)',
58
- example: 'account.custom.mybank'
59
- },
60
49
  icon: {
61
50
  type: 'string',
62
51
  description: 'Icon identifier (overrides template)',
63
52
  example: 'bank-custom'
64
53
  },
65
- openMeta: {
54
+ openDirectiveMeta: {
66
55
  type: 'object',
67
- description: 'Additional metadata',
56
+ description:
57
+ 'Open directive metadata (NOT an opening-balance amount — use the opening-balance endpoint)',
68
58
  example: {
69
59
  branch: 'Downtown',
70
60
  accountNumber: '1234'
@@ -76,7 +66,7 @@ export const $CreateAccountDto = {
76
66
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
77
67
  }
78
68
  },
79
- required: ['path', 'openDate']
69
+ required: ['path']
80
70
  } as const;
81
71
 
82
72
  export const $AccountResponseDto = {
@@ -90,13 +80,7 @@ export const $AccountResponseDto = {
90
80
  path: {
91
81
  type: 'string',
92
82
  description: 'Account path (hierarchical, colon-separated)',
93
- example: 'Assets:CN:Bank:ICBC:Checking'
94
- },
95
- displayName: {
96
- type: 'string',
97
- description:
98
- 'Display name distinguishing multiple accounts at the same path',
99
- example: '工资卡'
83
+ example: 'Assets:CN:ICBC:Checking'
100
84
  },
101
85
  type: {
102
86
  type: 'string',
@@ -104,6 +88,49 @@ export const $AccountResponseDto = {
104
88
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
105
89
  example: 'Assets'
106
90
  },
91
+ assetSubClass: {
92
+ type: 'string',
93
+ description:
94
+ 'Account-level asset sub-class (product type, e.g. STOCK/DEPOSIT/CREDIT_CARD/PERSONAL_LOAN). Computed from the account path via the asset-classifier (ADR-0077). Null for non-asset accounts (Income/Expenses/Equity) or unmatched paths.',
95
+ enum: [
96
+ 'DEPOSIT',
97
+ 'CASH',
98
+ 'MONEY_MARKET_FUND',
99
+ 'STOCK',
100
+ 'ETF',
101
+ 'MUTUAL_FUND',
102
+ 'EQUITY_COMPENSATION',
103
+ 'GOVERNMENT_BOND',
104
+ 'CORPORATE_BOND',
105
+ 'BOND_FUND',
106
+ 'PRIMARY_RESIDENCE',
107
+ 'INVESTMENT_PROPERTY',
108
+ 'REIT',
109
+ 'GOLD',
110
+ 'SILVER',
111
+ 'PRECIOUS_METAL',
112
+ 'PRECIOUS_METAL_FUND',
113
+ 'COMMODITY',
114
+ 'COMMODITY_FUND',
115
+ 'CRYPTOCURRENCY',
116
+ 'RETIREMENT_ACCOUNT',
117
+ 'HEALTH_ACCOUNT',
118
+ 'EDUCATION_ACCOUNT',
119
+ 'INSURANCE',
120
+ 'PRIVATE_EQUITY',
121
+ 'HEDGE_FUND',
122
+ 'COLLECTIBLES',
123
+ 'MORTGAGE',
124
+ 'STUDENT_LOAN',
125
+ 'CREDIT_CARD',
126
+ 'PERSONAL_LOAN',
127
+ 'ACCOUNTS_PAYABLE',
128
+ 'TAX_PAYABLE',
129
+ 'OTHER'
130
+ ],
131
+ nullable: true,
132
+ example: 'STOCK'
133
+ },
107
134
  status: {
108
135
  type: 'string',
109
136
  description: 'Account status',
@@ -145,26 +172,26 @@ export const $AccountResponseDto = {
145
172
  templatePath: {
146
173
  type: 'string',
147
174
  description: 'Template path reference',
148
- example: 'Assets:CN:Bank:ICBC:Checking'
175
+ example: 'Assets:CN:Checking'
149
176
  },
150
177
  isCustom: {
151
178
  type: 'boolean',
152
179
  description: 'Whether this is a custom (user-created) account',
153
180
  example: false
154
181
  },
155
- i18nKey: {
182
+ displayName: {
156
183
  type: 'string',
157
- description: 'i18n key for display name',
158
- example: 'account.assets.cn.bank.icbc.checking'
184
+ description: 'Localized display name (ADR-0114, read-time projection)',
185
+ example: 'Checking'
159
186
  },
160
187
  icon: {
161
188
  type: 'string',
162
189
  description: 'Icon identifier',
163
190
  example: 'bank-icbc'
164
191
  },
165
- openMeta: {
192
+ openDirectiveMeta: {
166
193
  type: 'object',
167
- description: 'Account metadata',
194
+ description: 'Open directive metadata (ADR-0115 Decision 9)',
168
195
  example: {
169
196
  branch: 'Downtown'
170
197
  }
@@ -192,7 +219,6 @@ export const $AccountResponseDto = {
192
219
  required: [
193
220
  'id',
194
221
  'path',
195
- 'displayName',
196
222
  'type',
197
223
  'status',
198
224
  'openDate',
@@ -225,11 +251,6 @@ export const $AccountListResponseDto = {
225
251
  export const $UpdateAccountDto = {
226
252
  type: 'object',
227
253
  properties: {
228
- displayName: {
229
- type: 'string',
230
- description: 'Display name to distinguish accounts at the same path',
231
- example: '招行工资卡'
232
- },
233
254
  currencies: {
234
255
  description: 'Allowed currencies (null = no restriction)',
235
256
  example: ['CNY', 'USD'],
@@ -251,19 +272,15 @@ export const $UpdateAccountDto = {
251
272
  'NONE'
252
273
  ]
253
274
  },
254
- i18nKey: {
255
- type: 'string',
256
- description: 'i18n key for display name',
257
- example: 'account.custom.mybank'
258
- },
259
275
  icon: {
260
276
  type: 'string',
261
277
  description: 'Icon identifier',
262
278
  example: 'bank-custom'
263
279
  },
264
- openMeta: {
280
+ openDirectiveMeta: {
265
281
  type: 'object',
266
- description: 'Additional metadata (merged with existing)',
282
+ description:
283
+ 'Open directive metadata (merged with existing; NOT an opening-balance amount)',
267
284
  example: {
268
285
  branch: 'Uptown'
269
286
  }
@@ -310,13 +327,47 @@ export const $ReopenAccountDto = {
310
327
  }
311
328
  } as const;
312
329
 
330
+ export const $CreateOpeningBalanceDto = {
331
+ type: 'object',
332
+ properties: {
333
+ amount: {
334
+ type: 'number',
335
+ description: 'Opening balance amount (non-negative)',
336
+ example: 1000
337
+ },
338
+ currency: {
339
+ type: 'string',
340
+ description: 'Currency code',
341
+ example: 'CNY'
342
+ },
343
+ date: {
344
+ format: 'date-time',
345
+ type: 'string',
346
+ description: 'Opening-balance date (defaults to now)',
347
+ example: '2024-01-01'
348
+ }
349
+ },
350
+ required: ['amount', 'currency']
351
+ } as const;
352
+
353
+ export const $OpeningBalanceResultDto = {
354
+ type: 'object',
355
+ properties: {
356
+ transactionId: {
357
+ type: 'string',
358
+ description: 'Created opening-balance transaction id.'
359
+ }
360
+ },
361
+ required: ['transactionId']
362
+ } as const;
363
+
313
364
  export const $AccountStandardResponseDto = {
314
365
  type: 'object',
315
366
  properties: {
316
367
  path: {
317
368
  type: 'string',
318
369
  description: 'Account path (hierarchical, colon-separated)',
319
- example: 'Assets:CN:Bank:ICBC:Checking'
370
+ example: 'Assets:CN:Checking'
320
371
  },
321
372
  type: {
322
373
  type: 'string',
@@ -324,11 +375,6 @@ export const $AccountStandardResponseDto = {
324
375
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
325
376
  example: 'Assets'
326
377
  },
327
- i18nKey: {
328
- type: 'string',
329
- description: 'i18n key for localized display name',
330
- example: 'account.assets.cn.bank.icbc.checking'
331
- },
332
378
  name: {
333
379
  type: 'string',
334
380
  description: 'Short localized display name',
@@ -351,9 +397,47 @@ export const $AccountStandardResponseDto = {
351
397
  type: 'string',
352
398
  description: 'Icon identifier for UI display',
353
399
  example: 'bank-icbc'
400
+ },
401
+ productCategory: {
402
+ type: 'string',
403
+ description:
404
+ 'Onboarding product category (coarse grouping derived from assetSubClass)',
405
+ enum: [
406
+ 'cash',
407
+ 'investment',
408
+ 'credit_card',
409
+ 'loan',
410
+ 'payable_tax',
411
+ 'other'
412
+ ],
413
+ example: 'investment'
414
+ },
415
+ assetClass: {
416
+ type: 'string',
417
+ description:
418
+ 'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
419
+ enum: [
420
+ 'LIQUIDITY',
421
+ 'EQUITY',
422
+ 'FIXED_INCOME',
423
+ 'PRECIOUS_METALS',
424
+ 'COMMODITY',
425
+ 'INSURANCE',
426
+ 'ALTERNATIVE_INVESTMENT',
427
+ 'PERSONAL_ASSETS',
428
+ 'LIABILITY',
429
+ 'REAL_ESTATE',
430
+ 'INDEX'
431
+ ]
432
+ },
433
+ assetSubClass: {
434
+ type: 'string',
435
+ description:
436
+ 'Asset sub-class (product type, derived at read time from classification rules)',
437
+ example: 'STOCK'
354
438
  }
355
439
  },
356
- required: ['path', 'type', 'description']
440
+ required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
357
441
  } as const;
358
442
 
359
443
  export const $AccountStandardListResponseDto = {
@@ -383,18 +467,13 @@ export const $AccountStandardListResponseDto = {
383
467
  export const $TemplateMetadataDto = {
384
468
  type: 'object',
385
469
  properties: {
386
- extendable: {
387
- type: 'boolean',
388
- description: 'Whether this path can be extended',
389
- example: true
390
- },
391
470
  rootType: {
392
471
  type: 'string',
393
472
  description: 'Root account type',
394
473
  example: 'Assets'
395
474
  }
396
475
  },
397
- required: ['extendable', 'rootType']
476
+ required: ['rootType']
398
477
  } as const;
399
478
 
400
479
  export const $TemplateMetadataResponseDto = {
@@ -466,6 +545,66 @@ export const $RegionsMetadataResponseDto = {
466
545
  required: ['regions']
467
546
  } as const;
468
547
 
548
+ export const $CostSpecDto = {
549
+ type: 'object',
550
+ properties: {
551
+ mode: {
552
+ type: 'string',
553
+ enum: ['per-unit', 'total', 'date', 'label', 'auto'],
554
+ description: 'Cost specification mode (mirrors engine CostSpec)'
555
+ },
556
+ numberPerUnit: {
557
+ type: 'string',
558
+ description: 'Per-unit cost (required when mode is "per-unit")',
559
+ example: '240'
560
+ },
561
+ totalNumber: {
562
+ type: 'string',
563
+ description: 'Total cost for all units (required when mode is "total")',
564
+ example: '12000'
565
+ },
566
+ currency: {
567
+ type: 'string',
568
+ description: 'Cost currency (required in all modes)',
569
+ example: 'USD'
570
+ },
571
+ date: {
572
+ type: 'string',
573
+ description:
574
+ 'Lot acquisition date, ISO 8601 (required when mode is "date")',
575
+ example: '2024-01-15'
576
+ },
577
+ label: {
578
+ type: 'string',
579
+ description:
580
+ 'Lot label (required when mode is "label"; optional tag in buy modes)'
581
+ },
582
+ merge: {
583
+ type: 'boolean',
584
+ description: 'Merge lots for AVERAGE booking (mode: auto)'
585
+ }
586
+ },
587
+ required: ['mode', 'currency']
588
+ } as const;
589
+
590
+ export const $AmountDto = {
591
+ type: 'object',
592
+ properties: {
593
+ number: {
594
+ type: 'string',
595
+ description:
596
+ 'Amount as decimal string (max 15 integer + 15 decimal digits)',
597
+ example: '170.50'
598
+ },
599
+ currency: {
600
+ type: 'string',
601
+ description: 'Currency/commodity code',
602
+ example: 'USD'
603
+ }
604
+ },
605
+ required: ['number', 'currency']
606
+ } as const;
607
+
469
608
  export const $CreatePostingDto = {
470
609
  type: 'object',
471
610
  properties: {
@@ -473,7 +612,7 @@ export const $CreatePostingDto = {
473
612
  type: 'string',
474
613
  description:
475
614
  'Account name in Beancount format (must start with uppercase, colon-separated)',
476
- example: 'Assets:Bank:Checking'
615
+ example: 'Assets:Checking'
477
616
  },
478
617
  units: {
479
618
  type: 'string',
@@ -495,6 +634,33 @@ export const $CreatePostingDto = {
495
634
  example: {
496
635
  'tax-lot': 'Q1-2024'
497
636
  }
637
+ },
638
+ cost: {
639
+ description:
640
+ 'Cost basis (Beancount `{...}`). Maps to engine costSpec. Required for commodity holdings so they carry a monetary weight that can balance.',
641
+ example: {
642
+ mode: 'per-unit',
643
+ numberPerUnit: '240',
644
+ currency: 'USD'
645
+ },
646
+ allOf: [
647
+ {
648
+ $ref: '#/components/schemas/CostSpecDto'
649
+ }
650
+ ]
651
+ },
652
+ price: {
653
+ description:
654
+ 'Price annotation (Beancount `@...`). Maps to engine price. Used for valuation; cost takes priority for balance weight.',
655
+ example: {
656
+ number: '170',
657
+ currency: 'USD'
658
+ },
659
+ allOf: [
660
+ {
661
+ $ref: '#/components/schemas/AmountDto'
662
+ }
663
+ ]
498
664
  }
499
665
  },
500
666
  required: ['account']
@@ -573,23 +739,59 @@ export const $CreateTransactionDto = {
573
739
  required: ['date', 'narration', 'postings']
574
740
  } as const;
575
741
 
742
+ export const $CostDetailDto = {
743
+ type: 'object',
744
+ properties: {
745
+ number: {
746
+ type: 'string',
747
+ description: 'Per-unit cost basis (mirrors engine Cost.number)',
748
+ example: '240'
749
+ },
750
+ currency: {
751
+ type: 'string',
752
+ description: 'Cost currency',
753
+ example: 'USD'
754
+ },
755
+ date: {
756
+ type: 'string',
757
+ description: 'Lot acquisition date (ISO yyyy-mm-dd)',
758
+ example: '2024-01-15'
759
+ },
760
+ label: {
761
+ type: 'string',
762
+ description: 'Lot label',
763
+ example: 'lot-2024-01'
764
+ }
765
+ }
766
+ } as const;
767
+
576
768
  export const $PostingResponseDto = {
577
769
  type: 'object',
578
770
  properties: {
579
771
  account: {
580
772
  type: 'string',
581
773
  description: 'Account name',
582
- example: 'Assets:Bank:Checking'
774
+ example: 'Assets:Checking'
583
775
  },
584
776
  units: {
585
777
  type: 'string',
586
- description: 'Amount (may be null if interpolated)',
778
+ description:
779
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
587
780
  example: '100.50'
588
781
  },
589
782
  currency: {
590
783
  type: 'string',
591
784
  description: 'Currency',
592
785
  example: 'USD'
786
+ },
787
+ cost: {
788
+ description:
789
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
790
+ allOf: [
791
+ {
792
+ $ref: '#/components/schemas/CostDetailDto'
793
+ }
794
+ ]
593
795
  }
594
796
  },
595
797
  required: ['account']
@@ -840,6 +1042,85 @@ export const $BatchTransactionResponseDto = {
840
1042
  required: ['succeeded', 'failed']
841
1043
  } as const;
842
1044
 
1045
+ export const $CorrectTransactionDto = {
1046
+ type: 'object',
1047
+ properties: {
1048
+ date: {
1049
+ type: 'string',
1050
+ description: 'Transaction date (ISO 8601 format)',
1051
+ example: '2024-11-28'
1052
+ },
1053
+ flag: {
1054
+ type: 'string',
1055
+ description: 'Transaction flag: * (cleared), ! (pending)',
1056
+ enum: ['*', '!'],
1057
+ example: '*'
1058
+ },
1059
+ payee: {
1060
+ type: 'string',
1061
+ description: 'Payee name',
1062
+ example: 'Whole Foods Market'
1063
+ },
1064
+ narration: {
1065
+ type: 'string',
1066
+ description: 'Transaction narration/description',
1067
+ example: 'Grocery shopping'
1068
+ },
1069
+ tags: {
1070
+ description: 'Transaction tags (without # prefix)',
1071
+ example: ['vacation', 'personal'],
1072
+ type: 'array',
1073
+ items: {
1074
+ type: 'string'
1075
+ }
1076
+ },
1077
+ links: {
1078
+ description: 'Transaction links (without ^ prefix)',
1079
+ example: ['invoice-123'],
1080
+ type: 'array',
1081
+ items: {
1082
+ type: 'string'
1083
+ }
1084
+ },
1085
+ postings: {
1086
+ description:
1087
+ 'Transaction postings (minimum 1, typically 2 for double-entry)',
1088
+ type: 'array',
1089
+ items: {
1090
+ $ref: '#/components/schemas/CreatePostingDto'
1091
+ }
1092
+ },
1093
+ meta: {
1094
+ type: 'object',
1095
+ description: 'Transaction-level metadata',
1096
+ example: {
1097
+ invoice: '12345'
1098
+ }
1099
+ },
1100
+ idempotencyKey: {
1101
+ type: 'string',
1102
+ description:
1103
+ 'Unique key for idempotent transaction creation. If provided, duplicate requests with the same key will return the existing transaction.',
1104
+ example: 'import-2024-01-15-batch-001',
1105
+ maxLength: 128
1106
+ },
1107
+ autoCreateAccounts: {
1108
+ type: 'boolean',
1109
+ description:
1110
+ 'Auto-create accounts if not found. When true, missing accounts will be automatically created. When false (default for API), missing accounts will cause a validation error. Set to true for quick entry scenarios where you want to create accounts on-the-fly.',
1111
+ default: true,
1112
+ example: true
1113
+ },
1114
+ correctionReason: {
1115
+ type: 'string',
1116
+ description: 'Reason for correcting/superseding the original transaction',
1117
+ example: 'Wrong amount — corrected from receipt',
1118
+ maxLength: 500
1119
+ }
1120
+ },
1121
+ required: ['date', 'narration', 'postings']
1122
+ } as const;
1123
+
843
1124
  export const $PostingDetailDto = {
844
1125
  type: 'object',
845
1126
  properties: {
@@ -853,14 +1134,15 @@ export const $PostingDetailDto = {
853
1134
  description: 'Account ID',
854
1135
  example: 'clh1234567890abcdef'
855
1136
  },
856
- accountName: {
1137
+ account: {
857
1138
  type: 'string',
858
- description: 'Account name',
859
- example: 'Assets:Bank:Checking'
1139
+ description: 'Fully-qualified Beancount account path',
1140
+ example: 'Assets:Checking'
860
1141
  },
861
1142
  units: {
862
1143
  type: 'string',
863
- description: 'Amount (may be null if interpolated)',
1144
+ description:
1145
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
864
1146
  example: '100.50'
865
1147
  },
866
1148
  currency: {
@@ -883,10 +1165,19 @@ export const $PostingDetailDto = {
883
1165
  description: 'Cost date',
884
1166
  example: '2024-01-15'
885
1167
  },
886
- priceAmount: {
887
- type: 'string',
888
- description: 'Price amount',
889
- example: '1.02'
1168
+ cost: {
1169
+ description:
1170
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
1171
+ allOf: [
1172
+ {
1173
+ $ref: '#/components/schemas/CostDetailDto'
1174
+ }
1175
+ ]
1176
+ },
1177
+ priceAmount: {
1178
+ type: 'string',
1179
+ description: 'Price amount',
1180
+ example: '1.02'
890
1181
  },
891
1182
  priceCurrency: {
892
1183
  type: 'string',
@@ -903,7 +1194,7 @@ export const $PostingDetailDto = {
903
1194
  description: 'Posting metadata'
904
1195
  }
905
1196
  },
906
- required: ['id', 'accountId', 'accountName']
1197
+ required: ['id', 'accountId', 'account']
907
1198
  } as const;
908
1199
 
909
1200
  export const $TransactionDetailDto = {
@@ -975,8 +1266,8 @@ export const $TransactionDetailDto = {
975
1266
  },
976
1267
  sourceType: {
977
1268
  type: 'string',
978
- description: 'Source type (how the transaction was created)',
979
- enum: ['NLP', 'CSV', 'OCR', 'API']
1269
+ description:
1270
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
980
1271
  },
981
1272
  sourcePlatform: {
982
1273
  type: 'string',
@@ -1009,6 +1300,18 @@ export const $TransactionDetailDto = {
1009
1300
  type: 'string',
1010
1301
  description: 'Correction reason (if voided or superseded)',
1011
1302
  example: 'Duplicate entry'
1303
+ },
1304
+ supersededBy: {
1305
+ type: 'string',
1306
+ description:
1307
+ 'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
1308
+ example: 'clh1234567890abcdef'
1309
+ },
1310
+ originalTxn: {
1311
+ type: 'string',
1312
+ description:
1313
+ 'ID of the transaction this one corrected/replaced (back-link on the replacement)',
1314
+ example: 'clh1234567890abcdef'
1012
1315
  }
1013
1316
  },
1014
1317
  required: [
@@ -1023,6 +1326,77 @@ export const $TransactionDetailDto = {
1023
1326
  ]
1024
1327
  } as const;
1025
1328
 
1329
+ export const $BalanceByCurrencyDto = {
1330
+ type: 'object',
1331
+ properties: {
1332
+ currency: {
1333
+ type: 'string',
1334
+ description: 'ISO 4217 currency code',
1335
+ example: 'CNY'
1336
+ },
1337
+ balance: {
1338
+ type: 'string',
1339
+ description: 'Balance amount',
1340
+ example: '50000.00'
1341
+ }
1342
+ },
1343
+ required: ['currency', 'balance']
1344
+ } as const;
1345
+
1346
+ export const $ExchangeRateWarningDto = {
1347
+ type: 'object',
1348
+ properties: {
1349
+ type: {
1350
+ type: 'string',
1351
+ description: 'Warning type',
1352
+ example: 'MISSING_EXCHANGE_RATE'
1353
+ },
1354
+ currency: {
1355
+ type: 'string',
1356
+ description: 'Currency without exchange rate',
1357
+ example: 'EUR'
1358
+ },
1359
+ totalAmount: {
1360
+ type: 'string',
1361
+ description: 'Total amount affected',
1362
+ example: '1000.00'
1363
+ }
1364
+ },
1365
+ required: ['type', 'currency', 'totalAmount']
1366
+ } as const;
1367
+
1368
+ export const $TransactionListSummaryDto = {
1369
+ type: 'object',
1370
+ properties: {
1371
+ totalAmount: {
1372
+ type: 'string',
1373
+ description:
1374
+ 'Partial converted total in base currency (rated currencies only, raw Beancount sign). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.',
1375
+ example: '-6000.00'
1376
+ },
1377
+ currency: {
1378
+ type: 'string',
1379
+ description: 'Base currency (ISO 4217)',
1380
+ example: 'CNY'
1381
+ },
1382
+ balanceByCurrency: {
1383
+ description: 'Raw (unconverted) balance per currency',
1384
+ type: 'array',
1385
+ items: {
1386
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
1387
+ }
1388
+ },
1389
+ warnings: {
1390
+ description: 'Currencies missing an FX rate (omitted when empty)',
1391
+ type: 'array',
1392
+ items: {
1393
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
1394
+ }
1395
+ }
1396
+ },
1397
+ required: ['totalAmount', 'currency', 'balanceByCurrency']
1398
+ } as const;
1399
+
1026
1400
  export const $TransactionListResponseDto = {
1027
1401
  type: 'object',
1028
1402
  properties: {
@@ -1047,11 +1421,51 @@ export const $TransactionListResponseDto = {
1047
1421
  type: 'number',
1048
1422
  description: 'Number of items skipped',
1049
1423
  example: 0
1424
+ },
1425
+ summary: {
1426
+ description:
1427
+ 'Amount summary for the full filtered set (#514). Present only when the request has a single account OR category viewpoint; omitted for search-only / plain-list / dual-perspective requests.',
1428
+ allOf: [
1429
+ {
1430
+ $ref: '#/components/schemas/TransactionListSummaryDto'
1431
+ }
1432
+ ]
1050
1433
  }
1051
1434
  },
1052
1435
  required: ['data', 'total', 'limit', 'offset']
1053
1436
  } as const;
1054
1437
 
1438
+ export const $TagSuggestionDto = {
1439
+ type: 'object',
1440
+ properties: {
1441
+ tag: {
1442
+ type: 'string',
1443
+ description: 'Tag name',
1444
+ example: 'Monthly'
1445
+ },
1446
+ count: {
1447
+ type: 'number',
1448
+ description: 'Usage count across ACTIVE transactions',
1449
+ example: 12
1450
+ }
1451
+ },
1452
+ required: ['tag', 'count']
1453
+ } as const;
1454
+
1455
+ export const $TagSuggestionsResponseDto = {
1456
+ type: 'object',
1457
+ properties: {
1458
+ data: {
1459
+ description: 'Tag suggestions sorted as requested',
1460
+ type: 'array',
1461
+ items: {
1462
+ $ref: '#/components/schemas/TagSuggestionDto'
1463
+ }
1464
+ }
1465
+ },
1466
+ required: ['data']
1467
+ } as const;
1468
+
1055
1469
  export const $UpdateTransactionDto = {
1056
1470
  type: 'object',
1057
1471
  properties: {
@@ -1115,7 +1529,7 @@ export const $BalanceResponseDto = {
1115
1529
  account: {
1116
1530
  type: 'string',
1117
1531
  description: 'Account name',
1118
- example: 'Assets:Bank:Checking'
1532
+ example: 'Assets:Checking'
1119
1533
  },
1120
1534
  balance: {
1121
1535
  type: 'string',
@@ -1142,7 +1556,7 @@ export const $MultiCurrencyBalanceResponseDto = {
1142
1556
  account: {
1143
1557
  type: 'string',
1144
1558
  description: 'Account name',
1145
- example: 'Assets:Bank:Checking'
1559
+ example: 'Assets:Checking'
1146
1560
  },
1147
1561
  balances: {
1148
1562
  type: 'object',
@@ -1198,12 +1612,12 @@ export const $TransactionSummaryDto = {
1198
1612
  accountName: {
1199
1613
  type: 'string',
1200
1614
  description: 'Source account name (first posting)',
1201
- example: 'Assets:Bank:Checking'
1615
+ example: 'Assets:Checking'
1202
1616
  },
1203
1617
  sourceType: {
1204
1618
  type: 'string',
1205
- description: 'Source type (NLP, CSV, OCR, API)',
1206
- enum: ['NLP', 'CSV', 'OCR', 'API']
1619
+ description:
1620
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1207
1621
  },
1208
1622
  sourcePlatform: {
1209
1623
  type: 'string',
@@ -1243,8 +1657,10 @@ export const $ReviewSummaryDto = {
1243
1657
  },
1244
1658
  confidenceLevel: {
1245
1659
  type: 'string',
1246
- description: 'Confidence level derived from score',
1247
- enum: ['HIGH', 'MEDIUM', 'LOW']
1660
+ description:
1661
+ 'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
1662
+ enum: ['HIGH', 'MEDIUM', 'LOW'],
1663
+ nullable: true
1248
1664
  },
1249
1665
  summaryKey: {
1250
1666
  type: 'string',
@@ -1268,7 +1684,8 @@ export const $ReviewSummaryDto = {
1268
1684
  },
1269
1685
  sourceType: {
1270
1686
  type: 'string',
1271
- description: 'Source type (NLP, CSV, OCR, API)'
1687
+ description:
1688
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1272
1689
  },
1273
1690
  sourcePlatform: {
1274
1691
  type: 'string',
@@ -1378,7 +1795,20 @@ export const $DecisionOptionDto = {
1378
1795
  properties: {
1379
1796
  value: {
1380
1797
  type: 'string',
1381
- description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)'
1798
+ description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)',
1799
+ enum: [
1800
+ 'UPGRADE_REPLACE',
1801
+ 'LINK_KEEP_BOTH',
1802
+ 'IGNORE_NEW',
1803
+ 'CONFIRM_DIFFERENT',
1804
+ 'ACCEPT',
1805
+ 'REJECT',
1806
+ 'ACCEPT_AND_LEARN',
1807
+ 'CHOOSE_OTHER',
1808
+ 'CANCEL',
1809
+ 'FIX',
1810
+ 'IGNORE'
1811
+ ]
1382
1812
  },
1383
1813
  labelKey: {
1384
1814
  type: 'string',
@@ -1426,8 +1856,10 @@ export const $ReviewDetailDto = {
1426
1856
  },
1427
1857
  confidenceLevel: {
1428
1858
  type: 'string',
1429
- description: 'Confidence level derived from score',
1430
- enum: ['HIGH', 'MEDIUM', 'LOW']
1859
+ description:
1860
+ 'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
1861
+ enum: ['HIGH', 'MEDIUM', 'LOW'],
1862
+ nullable: true
1431
1863
  },
1432
1864
  summaryKey: {
1433
1865
  type: 'string',
@@ -1451,7 +1883,8 @@ export const $ReviewDetailDto = {
1451
1883
  },
1452
1884
  sourceType: {
1453
1885
  type: 'string',
1454
- description: 'Source type (NLP, CSV, OCR, API)'
1886
+ description:
1887
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1455
1888
  },
1456
1889
  sourcePlatform: {
1457
1890
  type: 'string',
@@ -1531,7 +1964,20 @@ export const $ResolveReviewDto = {
1531
1964
  action: {
1532
1965
  type: 'string',
1533
1966
  description:
1534
- 'Decision action. Available actions vary by review type: DUPLICATE: UPGRADE_REPLACE, KEEP_EXISTING, KEEP_BOTH | PAYEE_MATCH: ACCEPT, REJECT, ACCEPT_AND_LEARN | ACCOUNT_VALIDATION: FIX, REJECT | RULE_MATCH: ACCEPT, REJECT, ACCEPT_AND_LEARN',
1967
+ 'Decision action. Valid actions vary by review type — see DecisionOptionDto.value returned by the review detail endpoint.',
1968
+ enum: [
1969
+ 'UPGRADE_REPLACE',
1970
+ 'LINK_KEEP_BOTH',
1971
+ 'IGNORE_NEW',
1972
+ 'CONFIRM_DIFFERENT',
1973
+ 'ACCEPT',
1974
+ 'REJECT',
1975
+ 'ACCEPT_AND_LEARN',
1976
+ 'CHOOSE_OTHER',
1977
+ 'CANCEL',
1978
+ 'FIX',
1979
+ 'IGNORE'
1980
+ ],
1535
1981
  example: 'ACCEPT'
1536
1982
  },
1537
1983
  data: {
@@ -1568,7 +2014,8 @@ export const $ResolveResultDto = {
1568
2014
  },
1569
2015
  resolutionId: {
1570
2016
  type: 'string',
1571
- description: 'Resolution ID for undo'
2017
+ description:
2018
+ 'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
1572
2019
  },
1573
2020
  canUndo: {
1574
2021
  type: 'boolean',
@@ -1586,7 +2033,7 @@ export const $ResolveResultDto = {
1586
2033
  example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
1587
2034
  }
1588
2035
  },
1589
- required: ['success', 'resolutionId', 'canUndo', 'undoDeadline']
2036
+ required: ['success']
1590
2037
  } as const;
1591
2038
 
1592
2039
  export const $UndoResultDto = {
@@ -1622,6 +2069,19 @@ export const $BatchResolveDto = {
1622
2069
  action: {
1623
2070
  type: 'string',
1624
2071
  description: 'Decision action to apply to all items',
2072
+ enum: [
2073
+ 'UPGRADE_REPLACE',
2074
+ 'LINK_KEEP_BOTH',
2075
+ 'IGNORE_NEW',
2076
+ 'CONFIRM_DIFFERENT',
2077
+ 'ACCEPT',
2078
+ 'REJECT',
2079
+ 'ACCEPT_AND_LEARN',
2080
+ 'CHOOSE_OTHER',
2081
+ 'CANCEL',
2082
+ 'FIX',
2083
+ 'IGNORE'
2084
+ ],
1625
2085
  example: 'ACCEPT'
1626
2086
  },
1627
2087
  data: {
@@ -2444,6 +2904,163 @@ export const $UpdateCommodityDto = {
2444
2904
  }
2445
2905
  } as const;
2446
2906
 
2907
+ export const $CreateBeanPriceDto = {
2908
+ type: 'object',
2909
+ properties: {
2910
+ currency: {
2911
+ type: 'string',
2912
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2913
+ example: 'USD'
2914
+ },
2915
+ quoteCurrency: {
2916
+ type: 'string',
2917
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
2918
+ example: 'CNY'
2919
+ },
2920
+ amount: {
2921
+ type: 'number',
2922
+ description:
2923
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
2924
+ example: 175.5,
2925
+ minimum: 0
2926
+ },
2927
+ date: {
2928
+ type: 'string',
2929
+ description: 'Price date (ISO 8601 format)',
2930
+ example: '2024-11-05'
2931
+ },
2932
+ metadata: {
2933
+ type: 'object',
2934
+ description:
2935
+ 'Metadata (validated by Zod schema, max field lengths enforced)',
2936
+ example: {
2937
+ source: 'MANUAL',
2938
+ note: 'Bank valuation report',
2939
+ confidence: 0.95
2940
+ }
2941
+ }
2942
+ },
2943
+ required: ['currency', 'quoteCurrency', 'amount', 'date']
2944
+ } as const;
2945
+
2946
+ export const $PriceResponseDto = {
2947
+ type: 'object',
2948
+ properties: {
2949
+ id: {
2950
+ type: 'string',
2951
+ description: 'Unique identifier',
2952
+ example: 'uuid-123-456'
2953
+ },
2954
+ userId: {
2955
+ type: 'string',
2956
+ description: 'User ID (owner of the price)',
2957
+ example: 'user-123'
2958
+ },
2959
+ currency: {
2960
+ type: 'string',
2961
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2962
+ example: 'BTC'
2963
+ },
2964
+ quoteCurrency: {
2965
+ type: 'string',
2966
+ description: 'Quote currency (pricing currency, e.g., USD, CNY)',
2967
+ example: 'USD'
2968
+ },
2969
+ amount: {
2970
+ type: 'number',
2971
+ description:
2972
+ 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
2973
+ example: 50000
2974
+ },
2975
+ date: {
2976
+ type: 'string',
2977
+ description:
2978
+ 'Price date (ISO 8601 format). Represents the date this price was valid.',
2979
+ example: '2024-01-01',
2980
+ format: 'date'
2981
+ },
2982
+ meta: {
2983
+ type: 'object',
2984
+ description:
2985
+ 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
2986
+ example: {
2987
+ source: 'MANUAL',
2988
+ note: 'User-defined price',
2989
+ confidence: 1
2990
+ }
2991
+ },
2992
+ createdAt: {
2993
+ format: 'date-time',
2994
+ type: 'string',
2995
+ description: 'Creation timestamp',
2996
+ example: '2024-11-03T10:00:00Z'
2997
+ },
2998
+ updatedAt: {
2999
+ format: 'date-time',
3000
+ type: 'string',
3001
+ description: 'Last update timestamp',
3002
+ example: '2024-11-03T10:00:00Z'
3003
+ }
3004
+ },
3005
+ required: [
3006
+ 'id',
3007
+ 'userId',
3008
+ 'currency',
3009
+ 'quoteCurrency',
3010
+ 'amount',
3011
+ 'date',
3012
+ 'meta',
3013
+ 'createdAt',
3014
+ 'updatedAt'
3015
+ ]
3016
+ } as const;
3017
+
3018
+ export const $PriceListResponseDto = {
3019
+ type: 'object',
3020
+ properties: {
3021
+ items: {
3022
+ description: 'List of prices',
3023
+ type: 'array',
3024
+ items: {
3025
+ $ref: '#/components/schemas/PriceResponseDto'
3026
+ }
3027
+ },
3028
+ total: {
3029
+ type: 'number',
3030
+ description: 'Total number of prices',
3031
+ example: 42
3032
+ }
3033
+ },
3034
+ required: ['items', 'total']
3035
+ } as const;
3036
+
3037
+ export const $UpdateBeanPriceDto = {
3038
+ type: 'object',
3039
+ properties: {
3040
+ currency: {
3041
+ type: 'string',
3042
+ description: 'Currency being priced'
3043
+ },
3044
+ quoteCurrency: {
3045
+ type: 'string',
3046
+ description: 'Quote currency (pricing currency)'
3047
+ },
3048
+ amount: {
3049
+ type: 'number',
3050
+ description: 'Price amount (MUST be >= 0 per Beancount spec)',
3051
+ minimum: 0
3052
+ },
3053
+ date: {
3054
+ type: 'string',
3055
+ description: 'Price date (ISO 8601 format)'
3056
+ },
3057
+ metadata: {
3058
+ type: 'object',
3059
+ description: 'Metadata'
3060
+ }
3061
+ }
3062
+ } as const;
3063
+
2447
3064
  export const $CreateRecurringRuleDto = {
2448
3065
  type: 'object',
2449
3066
  properties: {
@@ -3215,21 +3832,468 @@ export const $ForecastResponseDto = {
3215
3832
  ]
3216
3833
  } as const;
3217
3834
 
3218
- export const $CreateTransactionRuleDto = {
3835
+ export const $CurrencyBalanceDto = {
3219
3836
  type: 'object',
3220
3837
  properties: {
3221
- name: {
3838
+ currency: {
3222
3839
  type: 'string',
3223
- minLength: 1,
3224
- maxLength: 100
3840
+ description: 'ISO 4217 currency code',
3841
+ example: 'CNY'
3225
3842
  },
3226
- description: {
3843
+ balance: {
3227
3844
  type: 'string',
3228
- maxLength: 500
3229
- },
3230
- narrationKeywords: {
3231
- items: {
3232
- type: 'array'
3845
+ description: 'Balance amount',
3846
+ example: '500000.00'
3847
+ }
3848
+ },
3849
+ required: ['currency', 'balance']
3850
+ } as const;
3851
+
3852
+ export const $TimeSeriesPointDto = {
3853
+ type: 'object',
3854
+ properties: {
3855
+ date: {
3856
+ type: 'string',
3857
+ description: 'Date in YYYY-MM-DD format',
3858
+ example: '2024-06-15'
3859
+ },
3860
+ value: {
3861
+ type: 'string',
3862
+ description: 'Value at this date (in base currency)',
3863
+ example: '500000.00'
3864
+ },
3865
+ change: {
3866
+ type: 'object',
3867
+ description: 'Change from previous point',
3868
+ example: '5000.00'
3869
+ },
3870
+ assets: {
3871
+ type: 'string',
3872
+ description: 'Total assets at this date (in base currency)',
3873
+ example: '494338.00'
3874
+ },
3875
+ liabilities: {
3876
+ type: 'string',
3877
+ description: 'Total liabilities at this date (in base currency)',
3878
+ example: '310098.00'
3879
+ },
3880
+ byCurrency: {
3881
+ description: 'Multi-currency breakdown for this point',
3882
+ type: 'array',
3883
+ items: {
3884
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3885
+ }
3886
+ }
3887
+ },
3888
+ required: ['date', 'value']
3889
+ } as const;
3890
+
3891
+ export const $TrendSummaryDto = {
3892
+ type: 'object',
3893
+ properties: {
3894
+ startValue: {
3895
+ type: 'string',
3896
+ description: 'Value at start of period',
3897
+ example: '450000.00'
3898
+ },
3899
+ endValue: {
3900
+ type: 'string',
3901
+ description: 'Value at end of period',
3902
+ example: '500000.00'
3903
+ },
3904
+ totalChange: {
3905
+ type: 'string',
3906
+ description: 'Total change over period',
3907
+ example: '50000.00'
3908
+ },
3909
+ totalChangePercentage: {
3910
+ type: 'string',
3911
+ description: 'Total change percentage',
3912
+ example: '+11.11%'
3913
+ }
3914
+ },
3915
+ required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
3916
+ } as const;
3917
+
3918
+ export const $MultiCurrencyPointDto = {
3919
+ type: 'object',
3920
+ properties: {
3921
+ date: {
3922
+ type: 'string',
3923
+ description: 'Date in YYYY-MM-DD format',
3924
+ example: '2024-06-15'
3925
+ },
3926
+ byCurrency: {
3927
+ description: 'Balances by currency',
3928
+ type: 'array',
3929
+ items: {
3930
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3931
+ }
3932
+ }
3933
+ },
3934
+ required: ['date', 'byCurrency']
3935
+ } as const;
3936
+
3937
+ export const $PortfolioTrendsResponseDto = {
3938
+ type: 'object',
3939
+ properties: {
3940
+ series: {
3941
+ description: 'Time series data points',
3942
+ type: 'array',
3943
+ items: {
3944
+ $ref: '#/components/schemas/TimeSeriesPointDto'
3945
+ }
3946
+ },
3947
+ summary: {
3948
+ description: 'Period summary',
3949
+ allOf: [
3950
+ {
3951
+ $ref: '#/components/schemas/TrendSummaryDto'
3952
+ }
3953
+ ]
3954
+ },
3955
+ period: {
3956
+ type: 'string',
3957
+ description: 'Period requested',
3958
+ example: '6m'
3959
+ },
3960
+ granularity: {
3961
+ type: 'string',
3962
+ description: 'Data granularity',
3963
+ example: 'month'
3964
+ },
3965
+ currency: {
3966
+ type: 'string',
3967
+ description: 'Base currency for converted values',
3968
+ example: 'CNY'
3969
+ },
3970
+ byCurrency: {
3971
+ description:
3972
+ 'Multi-currency time series (each point has currency breakdown)',
3973
+ type: 'array',
3974
+ items: {
3975
+ $ref: '#/components/schemas/MultiCurrencyPointDto'
3976
+ }
3977
+ },
3978
+ warnings: {
3979
+ description: 'Exchange rate warnings',
3980
+ type: 'array',
3981
+ items: {
3982
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
3983
+ }
3984
+ }
3985
+ },
3986
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3987
+ } as const;
3988
+
3989
+ export const $CashFlowPointDto = {
3990
+ type: 'object',
3991
+ properties: {
3992
+ month: {
3993
+ type: 'string',
3994
+ description: 'Month key (YYYY-MM)',
3995
+ example: '2024-03'
3996
+ },
3997
+ income: {
3998
+ type: 'string',
3999
+ description: 'Income in base currency (absolute, converted)',
4000
+ example: '10000.00'
4001
+ },
4002
+ expense: {
4003
+ type: 'string',
4004
+ description: 'Expense in base currency (absolute, converted)',
4005
+ example: '5000.00'
4006
+ },
4007
+ netSavings: {
4008
+ type: 'string',
4009
+ description: 'netSavings = income − expense (savings positive)',
4010
+ example: '5000.00'
4011
+ }
4012
+ },
4013
+ required: ['month', 'income', 'expense', 'netSavings']
4014
+ } as const;
4015
+
4016
+ export const $CashFlowTrendSummaryDto = {
4017
+ type: 'object',
4018
+ properties: {
4019
+ totalIncome: {
4020
+ type: 'string',
4021
+ description: 'Total income across the period',
4022
+ example: '60000.00'
4023
+ },
4024
+ totalExpense: {
4025
+ type: 'string',
4026
+ description: 'Total expense across the period',
4027
+ example: '30000.00'
4028
+ },
4029
+ totalNetSavings: {
4030
+ type: 'string',
4031
+ description: 'income − expense across the period',
4032
+ example: '30000.00'
4033
+ },
4034
+ averageMonthlyNetSavings: {
4035
+ type: 'string',
4036
+ description:
4037
+ 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
4038
+ example: '5000.00'
4039
+ }
4040
+ },
4041
+ required: [
4042
+ 'totalIncome',
4043
+ 'totalExpense',
4044
+ 'totalNetSavings',
4045
+ 'averageMonthlyNetSavings'
4046
+ ]
4047
+ } as const;
4048
+
4049
+ export const $CashFlowTrendsResponseDto = {
4050
+ type: 'object',
4051
+ properties: {
4052
+ series: {
4053
+ description:
4054
+ 'Monthly cash-flow series (fixed N-month window, zero-filled)',
4055
+ type: 'array',
4056
+ items: {
4057
+ $ref: '#/components/schemas/CashFlowPointDto'
4058
+ }
4059
+ },
4060
+ summary: {
4061
+ description: 'Period totals',
4062
+ allOf: [
4063
+ {
4064
+ $ref: '#/components/schemas/CashFlowTrendSummaryDto'
4065
+ }
4066
+ ]
4067
+ },
4068
+ period: {
4069
+ type: 'string',
4070
+ description: 'Period requested',
4071
+ example: '6m'
4072
+ },
4073
+ granularity: {
4074
+ type: 'string',
4075
+ description: 'Data granularity (v1 returns month buckets)',
4076
+ example: 'month'
4077
+ },
4078
+ currency: {
4079
+ type: 'string',
4080
+ description: 'Base currency for converted values',
4081
+ example: 'CNY'
4082
+ },
4083
+ warnings: {
4084
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
4085
+ type: 'array',
4086
+ items: {
4087
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
4088
+ }
4089
+ }
4090
+ },
4091
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
4092
+ } as const;
4093
+
4094
+ export const $GenerateSnapshotBody = {
4095
+ type: 'object',
4096
+ properties: {}
4097
+ } as const;
4098
+
4099
+ export const $GenerateSnapshotResponse = {
4100
+ type: 'object',
4101
+ properties: {}
4102
+ } as const;
4103
+
4104
+ export const $BackfillSnapshotsBody = {
4105
+ type: 'object',
4106
+ properties: {}
4107
+ } as const;
4108
+
4109
+ export const $BackfillSnapshotsResponse = {
4110
+ type: 'object',
4111
+ properties: {}
4112
+ } as const;
4113
+
4114
+ export const $DeleteOwnUserDto = {
4115
+ type: 'object',
4116
+ properties: {
4117
+ accessToken: {
4118
+ type: 'string',
4119
+ description: 'Access token for user verification',
4120
+ example: 'abc123xyz'
4121
+ }
4122
+ },
4123
+ required: ['accessToken']
4124
+ } as const;
4125
+
4126
+ export const $SignupDto = {
4127
+ type: 'object',
4128
+ properties: {
4129
+ turnstileToken: {
4130
+ type: 'string',
4131
+ description:
4132
+ 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4133
+ example: '0.abc123def456...'
4134
+ }
4135
+ }
4136
+ } as const;
4137
+
4138
+ export const $SignupResponseDto = {
4139
+ type: 'object',
4140
+ properties: {
4141
+ authToken: {
4142
+ type: 'string',
4143
+ description: 'JWT auth token',
4144
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
4145
+ },
4146
+ accessToken: {
4147
+ type: 'string',
4148
+ description: 'Auto-generated access token'
4149
+ },
4150
+ role: {
4151
+ type: 'string',
4152
+ description: 'Assigned user role',
4153
+ enum: ['USER', 'ADMIN', 'DEMO', 'INACTIVE', 'PAID', 'OPS']
4154
+ }
4155
+ },
4156
+ required: ['authToken', 'accessToken', 'role']
4157
+ } as const;
4158
+
4159
+ export const $UpdateUserSettingDto = {
4160
+ type: 'object',
4161
+ properties: {
4162
+ secId: {
4163
+ type: 'number',
4164
+ description: 'Security ID'
4165
+ },
4166
+ annualInterestRate: {
4167
+ type: 'number',
4168
+ description: 'Annual interest rate',
4169
+ example: 0.05
4170
+ },
4171
+ currency: {
4172
+ type: 'string',
4173
+ description: 'Currency code',
4174
+ example: 'USD'
4175
+ },
4176
+ baseCurrency: {
4177
+ type: 'string',
4178
+ description: 'Base currency code',
4179
+ example: 'USD'
4180
+ },
4181
+ benchmark: {
4182
+ type: 'string',
4183
+ description: 'Benchmark symbol',
4184
+ example: 'SPY'
4185
+ },
4186
+ colorScheme: {
4187
+ type: 'string',
4188
+ description: 'Color scheme',
4189
+ enum: ['DARK', 'LIGHT']
4190
+ },
4191
+ dateRange: {
4192
+ type: 'string',
4193
+ description: 'Date range filter',
4194
+ example: '1y'
4195
+ },
4196
+ emergencyFund: {
4197
+ type: 'number',
4198
+ description: 'Emergency fund amount',
4199
+ example: 10000
4200
+ },
4201
+ 'filters.accounts': {
4202
+ description: 'Account filter IDs',
4203
+ type: 'array',
4204
+ items: {
4205
+ type: 'string'
4206
+ }
4207
+ },
4208
+ 'filters.assetClasses': {
4209
+ description: 'Asset class filters',
4210
+ type: 'array',
4211
+ items: {
4212
+ type: 'string'
4213
+ }
4214
+ },
4215
+ 'filters.dataSource': {
4216
+ type: 'string',
4217
+ description: 'Data source filter'
4218
+ },
4219
+ 'filters.symbol': {
4220
+ type: 'string',
4221
+ description: 'Symbol filter'
4222
+ },
4223
+ 'filters.tags': {
4224
+ description: 'Tag filters',
4225
+ type: 'array',
4226
+ items: {
4227
+ type: 'string'
4228
+ }
4229
+ },
4230
+ isExperimentalFeatures: {
4231
+ type: 'boolean',
4232
+ description: 'Enable experimental features'
4233
+ },
4234
+ isRestrictedView: {
4235
+ type: 'boolean',
4236
+ description: 'Enable restricted view mode'
4237
+ },
4238
+ language: {
4239
+ type: 'string',
4240
+ description: 'Language code',
4241
+ example: 'en'
4242
+ },
4243
+ locale: {
4244
+ type: 'string',
4245
+ description: 'Locale code',
4246
+ example: 'en-US'
4247
+ },
4248
+ projectedTotalAmount: {
4249
+ type: 'number',
4250
+ description: 'Projected total amount',
4251
+ example: 1000000
4252
+ },
4253
+ retirementDate: {
4254
+ type: 'string',
4255
+ description: 'Retirement date in ISO 8601 format',
4256
+ example: '2050-01-01'
4257
+ },
4258
+ savingsRate: {
4259
+ type: 'number',
4260
+ description: 'Savings rate percentage',
4261
+ example: 0.2
4262
+ },
4263
+ viewMode: {
4264
+ type: 'string',
4265
+ description: 'View mode',
4266
+ enum: ['DEFAULT', 'ZEN']
4267
+ }
4268
+ }
4269
+ } as const;
4270
+
4271
+ export const $UpdatePropertyDto = {
4272
+ type: 'object',
4273
+ properties: {
4274
+ value: {
4275
+ type: 'string',
4276
+ description: 'Property value'
4277
+ }
4278
+ },
4279
+ required: ['value']
4280
+ } as const;
4281
+
4282
+ export const $CreateTransactionRuleDto = {
4283
+ type: 'object',
4284
+ properties: {
4285
+ name: {
4286
+ type: 'string',
4287
+ minLength: 1,
4288
+ maxLength: 100
4289
+ },
4290
+ description: {
4291
+ type: 'string',
4292
+ maxLength: 500
4293
+ },
4294
+ narrationKeywords: {
4295
+ items: {
4296
+ type: 'array'
3233
4297
  },
3234
4298
  maxItems: 50,
3235
4299
  type: 'array'
@@ -3864,151 +4928,393 @@ export const $TestRuleResponseDto = {
3864
4928
  required: ['ruleId', 'matches', 'confidence', 'matchDetails']
3865
4929
  } as const;
3866
4930
 
3867
- export const $DeleteOwnUserDto = {
4931
+ export const $CreateBeanEventDto = {
3868
4932
  type: 'object',
3869
4933
  properties: {
3870
- accessToken: {
4934
+ date: {
3871
4935
  type: 'string',
3872
- description: 'Access token for user verification',
3873
- example: 'abc123xyz'
4936
+ description: 'Life event date (ISO 8601)',
4937
+ example: '2024-03-15'
4938
+ },
4939
+ type: {
4940
+ type: 'string',
4941
+ description:
4942
+ 'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
4943
+ example: 'employer'
4944
+ },
4945
+ description: {
4946
+ type: 'string',
4947
+ description:
4948
+ 'Life event description. Empty string is a VALID value (distinct from absence).',
4949
+ example: 'Acme Corp'
4950
+ },
4951
+ meta: {
4952
+ type: 'object',
4953
+ description:
4954
+ 'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
4955
+ example: {
4956
+ note: 'Promotion'
4957
+ }
3874
4958
  }
3875
4959
  },
3876
- required: ['accessToken']
4960
+ required: ['date', 'type', 'description']
3877
4961
  } as const;
3878
4962
 
3879
- export const $SignupDto = {
4963
+ export const $EventResponseDto = {
3880
4964
  type: 'object',
3881
4965
  properties: {
3882
- turnstileToken: {
4966
+ id: {
4967
+ type: 'string',
4968
+ description: 'Unique identifier',
4969
+ example: 'uuid-123-456'
4970
+ },
4971
+ userId: {
4972
+ type: 'string',
4973
+ description: 'User ID (owner of the life event)',
4974
+ example: 'user-123'
4975
+ },
4976
+ date: {
4977
+ type: 'string',
4978
+ description: 'Life event date (ISO 8601 format)',
4979
+ example: '2024-03-15',
4980
+ format: 'date'
4981
+ },
4982
+ type: {
3883
4983
  type: 'string',
3884
4984
  description:
3885
- 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
3886
- example: '0.abc123def456...'
4985
+ 'Life event type (user-defined, e.g., "employer", "location")',
4986
+ example: 'employer'
4987
+ },
4988
+ description: {
4989
+ type: 'string',
4990
+ description:
4991
+ 'Life event description. May be an empty string (a valid value distinct from absence).',
4992
+ example: 'Acme Corp'
4993
+ },
4994
+ meta: {
4995
+ type: 'object',
4996
+ description: 'Product-side metadata (free-form JSON)',
4997
+ example: {
4998
+ note: 'Promotion'
4999
+ }
5000
+ },
5001
+ createdAt: {
5002
+ format: 'date-time',
5003
+ type: 'string',
5004
+ description: 'Creation timestamp',
5005
+ example: '2024-03-15T10:00:00Z'
5006
+ },
5007
+ updatedAt: {
5008
+ format: 'date-time',
5009
+ type: 'string',
5010
+ description:
5011
+ 'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
5012
+ example: '2024-03-15T10:00:00Z'
5013
+ }
5014
+ },
5015
+ required: [
5016
+ 'id',
5017
+ 'userId',
5018
+ 'date',
5019
+ 'type',
5020
+ 'description',
5021
+ 'meta',
5022
+ 'createdAt',
5023
+ 'updatedAt'
5024
+ ]
5025
+ } as const;
5026
+
5027
+ export const $EventListResponseDto = {
5028
+ type: 'object',
5029
+ properties: {
5030
+ items: {
5031
+ description: 'List of life events',
5032
+ type: 'array',
5033
+ items: {
5034
+ $ref: '#/components/schemas/EventResponseDto'
5035
+ }
5036
+ },
5037
+ total: {
5038
+ type: 'number',
5039
+ description: 'Total number of life events matching the query',
5040
+ example: 42
5041
+ }
5042
+ },
5043
+ required: ['items', 'total']
5044
+ } as const;
5045
+
5046
+ export const $UpdateBeanEventDto = {
5047
+ type: 'object',
5048
+ properties: {
5049
+ date: {
5050
+ type: 'string',
5051
+ description: 'Life event date (ISO 8601)'
5052
+ },
5053
+ type: {
5054
+ type: 'string',
5055
+ description: 'Life event type (user-defined)'
5056
+ },
5057
+ description: {
5058
+ type: 'string',
5059
+ description:
5060
+ 'Life event description. Empty string is a VALID value (distinct from absence).'
5061
+ },
5062
+ meta: {
5063
+ type: 'object',
5064
+ description: 'Product-side metadata (free-form JSON)'
5065
+ }
5066
+ }
5067
+ } as const;
5068
+
5069
+ export const $OnboardingAccountDto = {
5070
+ type: 'object',
5071
+ properties: {
5072
+ path: {
5073
+ type: 'string',
5074
+ description:
5075
+ 'Account path (Assets/Liabilities only; format validated by the account service)',
5076
+ example: 'Assets:Checking'
5077
+ },
5078
+ currency: {
5079
+ type: 'string',
5080
+ description: 'ISO 4217 currency code (3 letters)',
5081
+ example: 'USD'
5082
+ },
5083
+ openingBalance: {
5084
+ type: 'string',
5085
+ description:
5086
+ 'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
5087
+ example: '1000.00'
5088
+ },
5089
+ platformId: {
5090
+ type: 'string',
5091
+ description:
5092
+ 'Platform ID to bind the account to (references Platform.id); omit for unbound',
5093
+ example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
5094
+ }
5095
+ },
5096
+ required: ['path', 'currency']
5097
+ } as const;
5098
+
5099
+ export const $OnboardingDto = {
5100
+ type: 'object',
5101
+ properties: {
5102
+ accounts: {
5103
+ description: 'Asset/Liability accounts to register with opening balances',
5104
+ type: 'array',
5105
+ items: {
5106
+ $ref: '#/components/schemas/OnboardingAccountDto'
5107
+ }
5108
+ },
5109
+ skipAssetRegistration: {
5110
+ type: 'boolean',
5111
+ description:
5112
+ 'Skip asset registration; only bootstrap the core account set',
5113
+ default: false
5114
+ }
5115
+ }
5116
+ } as const;
5117
+
5118
+ export const $ActualBalanceDto = {
5119
+ type: 'object',
5120
+ properties: {
5121
+ amount: {
5122
+ type: 'string',
5123
+ description:
5124
+ 'Actual balance amount as a decimal string (preserves precision for tolerance inference).',
5125
+ example: '1234.56'
5126
+ },
5127
+ ccy: {
5128
+ type: 'string',
5129
+ description: 'Currency code (ISO 4217 or commodity ticker).',
5130
+ example: 'CNY'
5131
+ }
5132
+ },
5133
+ required: ['amount', 'ccy']
5134
+ } as const;
5135
+
5136
+ export const $ComputeReconciliationDto = {
5137
+ type: 'object',
5138
+ properties: {
5139
+ accountId: {
5140
+ type: 'string',
5141
+ description: 'BeanAccount id to reconcile.'
5142
+ },
5143
+ asOfDate: {
5144
+ type: 'string',
5145
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5146
+ example: '2026-07-24'
5147
+ },
5148
+ actualBalance: {
5149
+ description: 'Actual balance from the external statement.',
5150
+ allOf: [
5151
+ {
5152
+ $ref: '#/components/schemas/ActualBalanceDto'
5153
+ }
5154
+ ]
3887
5155
  }
3888
- }
5156
+ },
5157
+ required: ['accountId', 'asOfDate', 'actualBalance']
3889
5158
  } as const;
3890
5159
 
3891
- export const $UpdateUserSettingDto = {
5160
+ export const $ReconciliationComputeResultDto = {
3892
5161
  type: 'object',
3893
5162
  properties: {
3894
- secId: {
3895
- type: 'number',
3896
- description: 'Security ID'
5163
+ accountId: {
5164
+ type: 'string'
3897
5165
  },
3898
- annualInterestRate: {
3899
- type: 'number',
3900
- description: 'Annual interest rate',
3901
- example: 0.05
5166
+ asOfDate: {
5167
+ type: 'string'
3902
5168
  },
3903
- currency: {
5169
+ bookBalance: {
3904
5170
  type: 'string',
3905
- description: 'Currency code',
3906
- example: 'USD'
5171
+ description: 'System-computed book balance (decimal string).'
3907
5172
  },
3908
- baseCurrency: {
5173
+ actualBalance: {
3909
5174
  type: 'string',
3910
- description: 'Base currency code',
3911
- example: 'USD'
5175
+ description: 'User-entered actual balance (decimal string).'
3912
5176
  },
3913
- benchmark: {
3914
- type: 'string',
3915
- description: 'Benchmark symbol',
3916
- example: 'SPY'
5177
+ currency: {
5178
+ type: 'string'
3917
5179
  },
3918
- colorScheme: {
5180
+ diff: {
3919
5181
  type: 'string',
3920
- description: 'Color scheme',
3921
- enum: ['DARK', 'LIGHT']
5182
+ description: 'Diff = book − actual (decimal string).'
3922
5183
  },
3923
- dateRange: {
5184
+ tolerance: {
3924
5185
  type: 'string',
3925
- description: 'Date range filter',
3926
- example: '1y'
5186
+ description: 'Applied tolerance (decimal string).'
3927
5187
  },
3928
- emergencyFund: {
3929
- type: 'number',
3930
- description: 'Emergency fund amount',
3931
- example: 10000
3932
- },
3933
- 'filters.accounts': {
3934
- description: 'Account filter IDs',
3935
- type: 'array',
3936
- items: {
3937
- type: 'string'
3938
- }
3939
- },
3940
- 'filters.assetClasses': {
3941
- description: 'Asset class filters',
3942
- type: 'array',
3943
- items: {
3944
- type: 'string'
3945
- }
5188
+ withinTolerance: {
5189
+ type: 'boolean',
5190
+ description: 'true when |diff| ≤ tolerance.'
3946
5191
  },
3947
- 'filters.dataSource': {
5192
+ suggestedAction: {
3948
5193
  type: 'string',
3949
- description: 'Data source filter'
5194
+ enum: ['assert', 'pad'],
5195
+ description:
5196
+ 'Suggested next action: assert when within tolerance, pad otherwise.'
5197
+ }
5198
+ },
5199
+ required: [
5200
+ 'accountId',
5201
+ 'asOfDate',
5202
+ 'bookBalance',
5203
+ 'actualBalance',
5204
+ 'currency',
5205
+ 'diff',
5206
+ 'tolerance',
5207
+ 'withinTolerance',
5208
+ 'suggestedAction'
5209
+ ]
5210
+ } as const;
5211
+
5212
+ export const $AssertReconciliationDto = {
5213
+ type: 'object',
5214
+ properties: {
5215
+ accountId: {
5216
+ type: 'string',
5217
+ description: 'BeanAccount id to reconcile.'
3950
5218
  },
3951
- 'filters.symbol': {
5219
+ asOfDate: {
3952
5220
  type: 'string',
3953
- description: 'Symbol filter'
5221
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5222
+ example: '2026-07-24'
3954
5223
  },
3955
- 'filters.tags': {
3956
- description: 'Tag filters',
3957
- type: 'array',
3958
- items: {
3959
- type: 'string'
3960
- }
5224
+ actualBalance: {
5225
+ description: 'Actual balance from the external statement.',
5226
+ allOf: [
5227
+ {
5228
+ $ref: '#/components/schemas/ActualBalanceDto'
5229
+ }
5230
+ ]
3961
5231
  },
3962
- isExperimentalFeatures: {
3963
- type: 'boolean',
3964
- description: 'Enable experimental features'
5232
+ tolerance: {
5233
+ type: 'string',
5234
+ description:
5235
+ 'Optional explicit tolerance override. Omit to infer from amount precision (Beancount default).',
5236
+ example: '0.01'
5237
+ }
5238
+ },
5239
+ required: ['accountId', 'asOfDate', 'actualBalance']
5240
+ } as const;
5241
+
5242
+ export const $ReconciliationRecordDto = {
5243
+ type: 'object',
5244
+ properties: {
5245
+ id: {
5246
+ type: 'string'
3965
5247
  },
3966
- isRestrictedView: {
3967
- type: 'boolean',
3968
- description: 'Enable restricted view mode'
5248
+ accountId: {
5249
+ type: 'string'
3969
5250
  },
3970
- language: {
5251
+ date: {
5252
+ type: 'string'
5253
+ },
5254
+ amount: {
3971
5255
  type: 'string',
3972
- description: 'Language code',
3973
- example: 'en'
5256
+ description: 'Asserted (actual) amount.'
3974
5257
  },
3975
- locale: {
5258
+ currency: {
5259
+ type: 'string'
5260
+ },
5261
+ tolerance: {
5262
+ type: 'string'
5263
+ },
5264
+ diffAmount: {
3976
5265
  type: 'string',
3977
- description: 'Locale code',
3978
- example: 'en-US'
5266
+ description: 'book − actual.'
3979
5267
  },
3980
- projectedTotalAmount: {
3981
- type: 'number',
3982
- description: 'Projected total amount',
3983
- example: 1000000
5268
+ diffCurrency: {
5269
+ type: 'string'
3984
5270
  },
3985
- retirementDate: {
5271
+ createdAt: {
5272
+ type: 'string'
5273
+ }
5274
+ },
5275
+ required: ['id', 'accountId', 'date', 'amount', 'currency', 'createdAt']
5276
+ } as const;
5277
+
5278
+ export const $PadReconciliationDto = {
5279
+ type: 'object',
5280
+ properties: {
5281
+ accountId: {
3986
5282
  type: 'string',
3987
- description: 'Retirement date in ISO 8601 format',
3988
- example: '2050-01-01'
5283
+ description: 'BeanAccount id to reconcile.'
3989
5284
  },
3990
- savingsRate: {
3991
- type: 'number',
3992
- description: 'Savings rate percentage',
3993
- example: 0.2
5285
+ asOfDate: {
5286
+ type: 'string',
5287
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5288
+ example: '2026-07-24'
3994
5289
  },
3995
- viewMode: {
5290
+ actualBalance: {
5291
+ description: 'Actual balance from the external statement.',
5292
+ allOf: [
5293
+ {
5294
+ $ref: '#/components/schemas/ActualBalanceDto'
5295
+ }
5296
+ ]
5297
+ },
5298
+ sourceAccount: {
3996
5299
  type: 'string',
3997
- description: 'View mode',
3998
- enum: ['DEFAULT', 'ZEN']
5300
+ description:
5301
+ 'Pad source account. Defaults to Equity:Opening-Balances (official Beancount convention).',
5302
+ example: 'Equity:Opening-Balances',
5303
+ default: 'Equity:Opening-Balances'
3999
5304
  }
4000
- }
5305
+ },
5306
+ required: ['accountId', 'asOfDate', 'actualBalance']
4001
5307
  } as const;
4002
5308
 
4003
- export const $UpdatePropertyDto = {
5309
+ export const $PadResultDto = {
4004
5310
  type: 'object',
4005
5311
  properties: {
4006
- value: {
5312
+ transactionId: {
4007
5313
  type: 'string',
4008
- description: 'Property value'
5314
+ description: 'Created pad adjusting transaction id.'
4009
5315
  }
4010
5316
  },
4011
- required: ['value']
5317
+ required: ['transactionId']
4012
5318
  } as const;
4013
5319
 
4014
5320
  export const $FileImportDto = {
@@ -4177,7 +5483,7 @@ export const $IdentifyResultDto = {
4177
5483
  account: {
4178
5484
  type: 'string',
4179
5485
  description: 'Default account used by this importer',
4180
- example: 'Assets:Alipay:Balance'
5486
+ example: 'Assets:CN:Alipay:Balance'
4181
5487
  },
4182
5488
  message: {
4183
5489
  type: 'string',
@@ -4194,7 +5500,7 @@ export const $MapperDefaultsDto = {
4194
5500
  sourceAccount: {
4195
5501
  type: 'string',
4196
5502
  description: 'Source account for transactions (Beancount format)',
4197
- example: 'Assets:Alipay:Balance'
5503
+ example: 'Assets:CN:Alipay:Balance'
4198
5504
  },
4199
5505
  currency: {
4200
5506
  type: 'string',
@@ -4231,7 +5537,7 @@ export const $MapperDefaultsDto = {
4231
5537
  description:
4232
5538
  'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
4233
5539
  example: {
4234
- HuaBei: 'Liabilities:Alipay:Huabei',
5540
+ HuaBei: 'Liabilities:CN:CreditLine',
4235
5541
  CreditCard: 'Liabilities:CreditCard'
4236
5542
  }
4237
5543
  }
@@ -4363,7 +5669,7 @@ export const $UpdateMapperDefaultsDto = {
4363
5669
  sourceAccount: {
4364
5670
  type: 'string',
4365
5671
  description: 'Source account for transactions (Beancount format)',
4366
- example: 'Assets:Alipay:Balance',
5672
+ example: 'Assets:CN:Alipay:Balance',
4367
5673
  pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
4368
5674
  },
4369
5675
  currency: {
@@ -4391,7 +5697,7 @@ export const $UpdateMapperDefaultsDto = {
4391
5697
  description:
4392
5698
  'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
4393
5699
  example: {
4394
- HuaBei: 'Liabilities:Alipay:Huabei',
5700
+ HuaBei: 'Liabilities:CN:CreditLine',
4395
5701
  CreditCard: 'Liabilities:CreditCard'
4396
5702
  }
4397
5703
  }
@@ -4426,119 +5732,13 @@ export const $UpdateImporterConfigDto = {
4426
5732
  }
4427
5733
  } as const;
4428
5734
 
4429
- export const $CreatePlatformDto = {
4430
- type: 'object',
4431
- properties: {
4432
- name: {
4433
- type: 'string',
4434
- description: 'Platform name',
4435
- example: 'Binance'
4436
- },
4437
- canonical: {
4438
- type: 'string',
4439
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4440
- example: 'binance'
4441
- },
4442
- aliases: {
4443
- description: 'Platform aliases (multi-language names for lookup)',
4444
- example: ['Binance', 'Binance Exchange', 'BNB'],
4445
- type: 'array',
4446
- items: {
4447
- type: 'string'
4448
- }
4449
- },
4450
- url: {
4451
- type: 'string',
4452
- description: 'Platform URL',
4453
- example: 'https://www.binance.com'
4454
- },
4455
- type: {
4456
- type: 'string',
4457
- description: 'Platform type',
4458
- enum: [
4459
- 'BANK',
4460
- 'BROKERAGE',
4461
- 'CRYPTO_EXCHANGE',
4462
- 'PAYMENT',
4463
- 'INVESTMENT',
4464
- 'INSURANCE',
4465
- 'OTHER'
4466
- ],
4467
- example: 'CRYPTO_EXCHANGE'
4468
- },
4469
- logoUrl: {
4470
- type: 'string',
4471
- description: 'Platform logo URL',
4472
- example: 'https://example.com/logos/binance.png'
4473
- },
4474
- isActive: {
4475
- type: 'boolean',
4476
- description: 'Whether the platform is active',
4477
- default: true
4478
- }
4479
- },
4480
- required: ['name', 'canonical', 'aliases', 'url', 'type']
4481
- } as const;
4482
-
4483
- export const $UpdatePlatformDto = {
4484
- type: 'object',
4485
- properties: {
4486
- name: {
4487
- type: 'string',
4488
- description: 'Platform name',
4489
- example: 'Binance'
4490
- },
4491
- canonical: {
4492
- type: 'string',
4493
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4494
- example: 'binance'
4495
- },
4496
- aliases: {
4497
- description: 'Platform aliases (multi-language names for lookup)',
4498
- example: ['Binance', 'Binance Exchange', 'BNB'],
4499
- type: 'array',
4500
- items: {
4501
- type: 'string'
4502
- }
4503
- },
4504
- url: {
4505
- type: 'string',
4506
- description: 'Platform URL',
4507
- example: 'https://www.binance.com'
4508
- },
4509
- type: {
4510
- type: 'string',
4511
- description: 'Platform type',
4512
- enum: [
4513
- 'BANK',
4514
- 'BROKERAGE',
4515
- 'CRYPTO_EXCHANGE',
4516
- 'PAYMENT',
4517
- 'INVESTMENT',
4518
- 'INSURANCE',
4519
- 'OTHER'
4520
- ],
4521
- example: 'CRYPTO_EXCHANGE'
4522
- },
4523
- logoUrl: {
4524
- type: 'string',
4525
- description: 'Platform logo URL',
4526
- example: 'https://example.com/logos/binance.png'
4527
- },
4528
- isActive: {
4529
- type: 'boolean',
4530
- description: 'Whether the platform is active'
4531
- }
4532
- }
4533
- } as const;
4534
-
4535
5735
  export const $ProviderSyncConfigDto = {
4536
5736
  type: 'object',
4537
5737
  properties: {
4538
5738
  sourceAccount: {
4539
5739
  type: 'string',
4540
5740
  description: 'Source account for the first posting',
4541
- example: 'Assets:Bank:Chase'
5741
+ example: 'Assets:US:Chase:Checking'
4542
5742
  },
4543
5743
  defaultCurrency: {
4544
5744
  type: 'string',
@@ -4547,26 +5747,29 @@ export const $ProviderSyncConfigDto = {
4547
5747
  },
4548
5748
  defaultExpenseAccount: {
4549
5749
  type: 'string',
4550
- description: 'Default expense account for the second posting',
5750
+ description:
5751
+ 'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4551
5752
  example: 'Expenses:Unknown'
4552
5753
  },
4553
5754
  defaultIncomeAccount: {
4554
5755
  type: 'string',
4555
- description: 'Default income account for the second posting',
5756
+ description:
5757
+ 'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4556
5758
  example: 'Income:Unknown'
4557
5759
  },
4558
5760
  filterPending: {
4559
5761
  type: 'boolean',
4560
5762
  description: 'Filter pending transactions',
4561
5763
  default: true
5764
+ },
5765
+ externalAccountId: {
5766
+ type: 'string',
5767
+ description:
5768
+ 'External account ID for per-batch providers (e.g. GoCardless). Overrides sourceAccount when an ExternalAccountLink mapping exists.',
5769
+ example: 'acc_gocardless_001'
4562
5770
  }
4563
5771
  },
4564
- required: [
4565
- 'sourceAccount',
4566
- 'defaultCurrency',
4567
- 'defaultExpenseAccount',
4568
- 'defaultIncomeAccount'
4569
- ]
5772
+ required: ['sourceAccount', 'defaultCurrency']
4570
5773
  } as const;
4571
5774
 
4572
5775
  export const $ProviderSyncDto = {
@@ -4678,11 +5881,104 @@ export const $SupportedProvidersResponseDto = {
4678
5881
  required: ['providers']
4679
5882
  } as const;
4680
5883
 
5884
+ export const $CreateExternalAccountLinkDto = {
5885
+ type: 'object',
5886
+ properties: {
5887
+ provider: {
5888
+ type: 'string',
5889
+ enum: [
5890
+ 'plaid',
5891
+ 'teller',
5892
+ 'truelayer',
5893
+ 'gocardless',
5894
+ 'simplefin',
5895
+ 'yodlee',
5896
+ 'beancount-direct',
5897
+ 'parsed-bill'
5898
+ ],
5899
+ example: 'plaid',
5900
+ description: 'Open Banking provider (whitelist)'
5901
+ },
5902
+ externalAccountId: {
5903
+ type: 'string',
5904
+ example: 'acc-plaid-001',
5905
+ description: 'External account ID from the provider'
5906
+ },
5907
+ beanAccountId: {
5908
+ type: 'string',
5909
+ example: '550e8400-e29b-41d4-a716-446655440000',
5910
+ description: 'Target BeanAccount ID (must belong to the JWT user)'
5911
+ }
5912
+ },
5913
+ required: ['provider', 'externalAccountId', 'beanAccountId']
5914
+ } as const;
5915
+
5916
+ export const $ExternalAccountLinkResponseDto = {
5917
+ type: 'object',
5918
+ properties: {
5919
+ id: {
5920
+ type: 'string'
5921
+ },
5922
+ provider: {
5923
+ type: 'string'
5924
+ },
5925
+ externalAccountId: {
5926
+ type: 'string'
5927
+ },
5928
+ beanAccountId: {
5929
+ type: 'string'
5930
+ },
5931
+ isActive: {
5932
+ type: 'boolean'
5933
+ },
5934
+ createdAt: {
5935
+ type: 'string'
5936
+ },
5937
+ updatedAt: {
5938
+ type: 'string'
5939
+ }
5940
+ },
5941
+ required: [
5942
+ 'id',
5943
+ 'provider',
5944
+ 'externalAccountId',
5945
+ 'beanAccountId',
5946
+ 'isActive',
5947
+ 'createdAt',
5948
+ 'updatedAt'
5949
+ ]
5950
+ } as const;
5951
+
5952
+ export const $ExternalAccountLinkListResponseDto = {
5953
+ type: 'object',
5954
+ properties: {
5955
+ items: {
5956
+ type: 'array',
5957
+ items: {
5958
+ $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
5959
+ }
5960
+ },
5961
+ total: {
5962
+ type: 'number'
5963
+ },
5964
+ provider: {
5965
+ type: 'string',
5966
+ description: 'Filter by provider (query param)'
5967
+ }
5968
+ },
5969
+ required: ['items', 'total']
5970
+ } as const;
5971
+
4681
5972
  export const $ParserTelemetryReportDto = {
4682
5973
  type: 'object',
4683
5974
  properties: {}
4684
5975
  } as const;
4685
5976
 
5977
+ export const $UncoveredFormatMissDto = {
5978
+ type: 'object',
5979
+ properties: {}
5980
+ } as const;
5981
+
4686
5982
  export const $ProcessNlpDto = {
4687
5983
  type: 'object',
4688
5984
  properties: {
@@ -4707,6 +6003,18 @@ export const $ProcessNlpDto = {
4707
6003
  currency: 'CNY',
4708
6004
  payee: 'Starbucks'
4709
6005
  }
6006
+ },
6007
+ selectedRuleId: {
6008
+ type: 'string',
6009
+ description:
6010
+ '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.',
6011
+ example: 'rule_abc123'
6012
+ },
6013
+ selectedAccount: {
6014
+ type: 'string',
6015
+ description:
6016
+ 'confirm_account echo-back: account path selected from the prior confirm_account response (suggestedAccount, similarAccounts[i], or a typed path). Applied directly when the session is confirming_account — no NL re-parse.',
6017
+ example: 'Expenses:Food:Coffee'
4710
6018
  }
4711
6019
  },
4712
6020
  required: ['message']
@@ -5031,7 +6339,8 @@ export const $NlpAccountConfirmationDataDto = {
5031
6339
  },
5032
6340
  suggestedAccount: {
5033
6341
  type: 'string',
5034
- description: 'Suggested replacement account',
6342
+ description:
6343
+ 'Suggested replacement account (omitted when no clear candidate)',
5035
6344
  example: 'Expenses:Food:Drinks'
5036
6345
  },
5037
6346
  similarAccounts: {
@@ -5053,7 +6362,6 @@ export const $NlpAccountConfirmationDataDto = {
5053
6362
  },
5054
6363
  required: [
5055
6364
  'invalidAccount',
5056
- 'suggestedAccount',
5057
6365
  'similarAccounts',
5058
6366
  'errorMessage',
5059
6367
  'transactionContext'
@@ -5222,11 +6530,12 @@ export const $NlpSuggestedAccountDto = {
5222
6530
  account: {
5223
6531
  type: 'string',
5224
6532
  description: 'Suggested account path',
5225
- example: 'Assets:Bank:Checking'
6533
+ example: 'Assets:Checking'
5226
6534
  },
5227
6535
  confidence: {
5228
6536
  type: 'number',
5229
- description: 'Confidence score for this suggestion (0-1)',
6537
+ description:
6538
+ 'Confidence score for this suggestion (0-1). Present = predicted (confirm/confirm_rule/confirm_account); omitted = actual persisted account (created). (#586)',
5230
6539
  example: 0.9
5231
6540
  }
5232
6541
  },
@@ -5262,23 +6571,31 @@ export const $NlpDefaultAccountsDto = {
5262
6571
  properties: {
5263
6572
  asset: {
5264
6573
  type: 'string',
5265
- description: 'Default asset account',
5266
- example: 'Assets:Bank:Checking'
6574
+ description:
6575
+ 'Default OPEN asset account (MRU when multiple), or null when none/ambiguous',
6576
+ example: 'Assets:Checking',
6577
+ nullable: true
5267
6578
  },
5268
6579
  expense: {
5269
6580
  type: 'string',
5270
- description: 'Default expense account',
5271
- example: 'Expenses:Uncategorized'
6581
+ description:
6582
+ 'Default OPEN expense account (MRU when multiple), or null when none/ambiguous',
6583
+ example: 'Expenses:Food:Coffee',
6584
+ nullable: true
5272
6585
  },
5273
6586
  income: {
5274
6587
  type: 'string',
5275
- description: 'Default income account',
5276
- example: 'Income:Uncategorized'
6588
+ description:
6589
+ 'Default OPEN income account (MRU when multiple), or null when none/ambiguous',
6590
+ example: 'Income:Salary',
6591
+ nullable: true
5277
6592
  },
5278
6593
  liability: {
5279
6594
  type: 'string',
5280
- description: 'Default liability account',
5281
- example: 'Liabilities:CreditCard'
6595
+ description:
6596
+ 'Default OPEN liability account (MRU when multiple), or null when none/ambiguous',
6597
+ example: 'Liabilities:CreditCard',
6598
+ nullable: true
5282
6599
  }
5283
6600
  },
5284
6601
  required: ['asset', 'expense', 'income', 'liability']
@@ -5303,7 +6620,8 @@ export const $NlpResponseDto = {
5303
6620
  'confirm_rule',
5304
6621
  'confirm_account',
5305
6622
  'confirm_payee',
5306
- 'cancel'
6623
+ 'cancel',
6624
+ 'aborted'
5307
6625
  ]
5308
6626
  },
5309
6627
  intent: {
@@ -5463,43 +6781,274 @@ export const $NlpResponseDto = {
5463
6781
  }
5464
6782
  ]
5465
6783
  },
5466
- suggestedAccounts: {
5467
- description:
5468
- 'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
5469
- allOf: [
5470
- {
5471
- $ref: '#/components/schemas/NlpSuggestedAccountsDto'
5472
- }
5473
- ]
6784
+ suggestedAccounts: {
6785
+ description:
6786
+ '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.',
6787
+ allOf: [
6788
+ {
6789
+ $ref: '#/components/schemas/NlpSuggestedAccountsDto'
6790
+ }
6791
+ ]
6792
+ },
6793
+ defaultAccounts: {
6794
+ description:
6795
+ 'Default fallback accounts for the user/region (#586). v1 returns universal constants; per-user personalization is planned.',
6796
+ allOf: [
6797
+ {
6798
+ $ref: '#/components/schemas/NlpDefaultAccountsDto'
6799
+ }
6800
+ ]
6801
+ }
6802
+ },
6803
+ required: ['status', 'action']
6804
+ } as const;
6805
+
6806
+ export const $PlatformListItemDto = {
6807
+ type: 'object',
6808
+ properties: {
6809
+ id: {
6810
+ type: 'string',
6811
+ description: 'Global platform ID'
6812
+ },
6813
+ name: {
6814
+ type: 'string',
6815
+ description: 'Platform name'
6816
+ },
6817
+ url: {
6818
+ type: 'string',
6819
+ description: 'Platform URL'
6820
+ },
6821
+ type: {
6822
+ type: 'string',
6823
+ description: 'Platform type',
6824
+ enum: [
6825
+ 'BANK',
6826
+ 'BROKERAGE',
6827
+ 'CRYPTO_EXCHANGE',
6828
+ 'PAYMENT',
6829
+ 'INVESTMENT',
6830
+ 'INSURANCE',
6831
+ 'OTHER'
6832
+ ]
6833
+ },
6834
+ canonical: {
6835
+ type: 'string',
6836
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
6837
+ },
6838
+ suggestedSegment: {
6839
+ type: 'string',
6840
+ description:
6841
+ 'Suggested path segment — canonical with first char uppercased (ACC_COMP_NAME_RE)'
6842
+ },
6843
+ logoUrl: {
6844
+ type: 'string',
6845
+ description: 'Logo URL',
6846
+ nullable: true
6847
+ },
6848
+ isBound: {
6849
+ type: 'boolean',
6850
+ description: 'Whether user has accounts using this platform'
6851
+ }
6852
+ },
6853
+ required: [
6854
+ 'id',
6855
+ 'name',
6856
+ 'url',
6857
+ 'type',
6858
+ 'canonical',
6859
+ 'suggestedSegment',
6860
+ 'logoUrl',
6861
+ 'isBound'
6862
+ ]
6863
+ } as const;
6864
+
6865
+ export const $PlatformMatchResultDto = {
6866
+ type: 'object',
6867
+ properties: {
6868
+ id: {
6869
+ type: 'string',
6870
+ description: 'Global platform ID'
6871
+ },
6872
+ name: {
6873
+ type: 'string',
6874
+ description: 'Platform name (e.g., "ICBC")'
6875
+ },
6876
+ canonical: {
6877
+ type: 'string',
6878
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
6879
+ },
6880
+ type: {
6881
+ type: 'string',
6882
+ description: 'Platform type',
6883
+ enum: [
6884
+ 'BANK',
6885
+ 'BROKERAGE',
6886
+ 'CRYPTO_EXCHANGE',
6887
+ 'PAYMENT',
6888
+ 'INVESTMENT',
6889
+ 'INSURANCE',
6890
+ 'OTHER'
6891
+ ]
6892
+ },
6893
+ suggestedSegment: {
6894
+ type: 'string',
6895
+ description:
6896
+ 'Suggested path segment — canonical, already in ACCOUNT_RE format'
6897
+ },
6898
+ logoUrl: {
6899
+ type: 'string',
6900
+ description: 'Logo URL',
6901
+ nullable: true
6902
+ },
6903
+ matchType: {
6904
+ type: 'string',
6905
+ description: "How this row matched: 'exact' > 'prefix' > 'substring'",
6906
+ enum: ['exact', 'prefix', 'substring']
6907
+ }
6908
+ },
6909
+ required: [
6910
+ 'id',
6911
+ 'name',
6912
+ 'canonical',
6913
+ 'type',
6914
+ 'suggestedSegment',
6915
+ 'logoUrl',
6916
+ 'matchType'
6917
+ ]
6918
+ } as const;
6919
+
6920
+ export const $PlatformMatchResponseDto = {
6921
+ type: 'object',
6922
+ properties: {
6923
+ platforms: {
6924
+ description: 'Ranked matches, best tier first (at most 10 rows)',
6925
+ type: 'array',
6926
+ items: {
6927
+ $ref: '#/components/schemas/PlatformMatchResultDto'
6928
+ }
6929
+ },
6930
+ matchType: {
6931
+ type: 'string',
6932
+ description:
6933
+ "Overall match quality — top row's tier, or 'none' when no hits",
6934
+ enum: ['none', 'exact', 'prefix', 'substring']
6935
+ },
6936
+ total: {
6937
+ type: 'number',
6938
+ description: 'Total matches before LIMIT (truncation transparency)'
6939
+ },
6940
+ hasMore: {
6941
+ type: 'boolean',
6942
+ description: 'true when total > platforms.length (more matches exist)'
6943
+ }
6944
+ },
6945
+ required: ['platforms', 'matchType', 'total', 'hasMore']
6946
+ } as const;
6947
+
6948
+ export const $CreatePlatformDto = {
6949
+ type: 'object',
6950
+ properties: {
6951
+ name: {
6952
+ type: 'string',
6953
+ description: 'Platform name',
6954
+ example: 'Binance'
6955
+ },
6956
+ canonical: {
6957
+ type: 'string',
6958
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
6959
+ example: 'binance'
6960
+ },
6961
+ aliases: {
6962
+ description: 'Platform aliases (multi-language names for lookup)',
6963
+ example: ['Binance', 'Binance Exchange', 'BNB'],
6964
+ type: 'array',
6965
+ items: {
6966
+ type: 'string'
6967
+ }
6968
+ },
6969
+ url: {
6970
+ type: 'string',
6971
+ description: 'Platform URL',
6972
+ example: 'https://www.binance.com'
6973
+ },
6974
+ type: {
6975
+ type: 'string',
6976
+ description: 'Platform type',
6977
+ enum: [
6978
+ 'BANK',
6979
+ 'BROKERAGE',
6980
+ 'CRYPTO_EXCHANGE',
6981
+ 'PAYMENT',
6982
+ 'INVESTMENT',
6983
+ 'INSURANCE',
6984
+ 'OTHER'
6985
+ ],
6986
+ example: 'CRYPTO_EXCHANGE'
6987
+ },
6988
+ logoUrl: {
6989
+ type: 'string',
6990
+ description: 'Platform logo URL',
6991
+ example: 'https://example.com/logos/binance.png'
5474
6992
  },
5475
- defaultAccounts: {
5476
- description:
5477
- 'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
5478
- allOf: [
5479
- {
5480
- $ref: '#/components/schemas/NlpDefaultAccountsDto'
5481
- }
5482
- ]
6993
+ isActive: {
6994
+ type: 'boolean',
6995
+ description: 'Whether the platform is active',
6996
+ default: true
5483
6997
  }
5484
6998
  },
5485
- required: ['status', 'action']
6999
+ required: ['name', 'canonical', 'aliases', 'url', 'type']
5486
7000
  } as const;
5487
7001
 
5488
- export const $BalanceByCurrencyDto = {
7002
+ export const $UpdatePlatformDto = {
5489
7003
  type: 'object',
5490
7004
  properties: {
5491
- currency: {
7005
+ name: {
5492
7006
  type: 'string',
5493
- description: 'ISO 4217 currency code',
5494
- example: 'CNY'
7007
+ description: 'Platform name',
7008
+ example: 'Binance'
5495
7009
  },
5496
- balance: {
7010
+ canonical: {
5497
7011
  type: 'string',
5498
- description: 'Balance amount',
5499
- example: '50000.00'
7012
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
7013
+ example: 'binance'
7014
+ },
7015
+ aliases: {
7016
+ description: 'Platform aliases (multi-language names for lookup)',
7017
+ example: ['Binance', 'Binance Exchange', 'BNB'],
7018
+ type: 'array',
7019
+ items: {
7020
+ type: 'string'
7021
+ }
7022
+ },
7023
+ url: {
7024
+ type: 'string',
7025
+ description: 'Platform URL',
7026
+ example: 'https://www.binance.com'
7027
+ },
7028
+ type: {
7029
+ type: 'string',
7030
+ description: 'Platform type',
7031
+ enum: [
7032
+ 'BANK',
7033
+ 'BROKERAGE',
7034
+ 'CRYPTO_EXCHANGE',
7035
+ 'PAYMENT',
7036
+ 'INVESTMENT',
7037
+ 'INSURANCE',
7038
+ 'OTHER'
7039
+ ],
7040
+ example: 'CRYPTO_EXCHANGE'
7041
+ },
7042
+ logoUrl: {
7043
+ type: 'string',
7044
+ description: 'Platform logo URL',
7045
+ example: 'https://example.com/logos/binance.png'
7046
+ },
7047
+ isActive: {
7048
+ type: 'boolean',
7049
+ description: 'Whether the platform is active'
5500
7050
  }
5501
- },
5502
- required: ['currency', 'balance']
7051
+ }
5503
7052
  } as const;
5504
7053
 
5505
7054
  export const $NetWorthByCurrencyDto = {
@@ -5571,28 +7120,6 @@ export const $ConvertedNetWorthDto = {
5571
7120
  ]
5572
7121
  } as const;
5573
7122
 
5574
- export const $ExchangeRateWarningDto = {
5575
- type: 'object',
5576
- properties: {
5577
- type: {
5578
- type: 'string',
5579
- description: 'Warning type',
5580
- example: 'MISSING_EXCHANGE_RATE'
5581
- },
5582
- currency: {
5583
- type: 'string',
5584
- description: 'Currency without exchange rate',
5585
- example: 'EUR'
5586
- },
5587
- totalAmount: {
5588
- type: 'string',
5589
- description: 'Total amount affected',
5590
- example: '1000.00'
5591
- }
5592
- },
5593
- required: ['type', 'currency', 'totalAmount']
5594
- } as const;
5595
-
5596
7123
  export const $NetWorthResponseDto = {
5597
7124
  type: 'object',
5598
7125
  properties: {
@@ -5678,7 +7205,7 @@ export const $AccountItemDto = {
5678
7205
  name: {
5679
7206
  type: 'string',
5680
7207
  description: 'Full account name',
5681
- example: 'Assets:Bank:CMB:Savings'
7208
+ example: 'Assets:CN:CMB:Savings'
5682
7209
  },
5683
7210
  displayName: {
5684
7211
  type: 'string',
@@ -5694,6 +7221,12 @@ export const $AccountItemDto = {
5694
7221
  type: 'string',
5695
7222
  description: 'Currency code',
5696
7223
  example: 'CNY'
7224
+ },
7225
+ convertedBalance: {
7226
+ type: 'string',
7227
+ description:
7228
+ 'FX-converted balance in base currency; omitted when not convertible',
7229
+ example: '50000.00'
5697
7230
  }
5698
7231
  },
5699
7232
  required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -5720,11 +7253,66 @@ export const $PlatformGroupDto = {
5720
7253
  },
5721
7254
  totalBalance: {
5722
7255
  type: 'string',
5723
- description: 'Total balance across all accounts in platform',
7256
+ description: 'FX-converted total balance in base currency',
7257
+ example: '100000.00'
7258
+ },
7259
+ balanceByCurrency: {
7260
+ description: 'Raw (unconverted) balances grouped by currency',
7261
+ type: 'array',
7262
+ items: {
7263
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
7264
+ }
7265
+ },
7266
+ convertedBalance: {
7267
+ type: 'string',
7268
+ description:
7269
+ 'Converted balance in base currency (omitted when no currency is convertible)',
5724
7270
  example: '100000.00'
7271
+ },
7272
+ sharePct: {
7273
+ type: 'number',
7274
+ description:
7275
+ 'Share of the grand converted total (0-100); 0 when grand total is 0',
7276
+ example: 42.5
7277
+ }
7278
+ },
7279
+ required: [
7280
+ 'platformId',
7281
+ 'platformName',
7282
+ 'accounts',
7283
+ 'totalBalance',
7284
+ 'balanceByCurrency',
7285
+ 'sharePct'
7286
+ ]
7287
+ } as const;
7288
+
7289
+ export const $AccountExchangeRateWarningDto = {
7290
+ type: 'object',
7291
+ properties: {
7292
+ type: {
7293
+ type: 'string',
7294
+ description: 'Warning type',
7295
+ example: 'MISSING_EXCHANGE_RATE'
7296
+ },
7297
+ currency: {
7298
+ type: 'string',
7299
+ description: 'Currency without exchange rate',
7300
+ example: 'USD'
7301
+ },
7302
+ accounts: {
7303
+ description: 'Affected account paths',
7304
+ type: 'array',
7305
+ items: {
7306
+ type: 'string'
7307
+ }
7308
+ },
7309
+ totalAmount: {
7310
+ type: 'string',
7311
+ description: 'Total amount in this currency',
7312
+ example: '5000.00'
5725
7313
  }
5726
7314
  },
5727
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
7315
+ required: ['type', 'currency', 'accounts', 'totalAmount']
5728
7316
  } as const;
5729
7317
 
5730
7318
  export const $AccountsSummaryDto = {
@@ -5737,9 +7325,21 @@ export const $AccountsSummaryDto = {
5737
7325
  totalPlatforms: {
5738
7326
  type: 'number',
5739
7327
  description: 'Total number of platforms'
7328
+ },
7329
+ baseCurrency: {
7330
+ type: 'string',
7331
+ description: 'Base currency for conversion',
7332
+ example: 'CNY'
7333
+ },
7334
+ warnings: {
7335
+ description: 'Per-account exchange rate warnings',
7336
+ type: 'array',
7337
+ items: {
7338
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
7339
+ }
5740
7340
  }
5741
7341
  },
5742
- required: ['totalAccounts', 'totalPlatforms']
7342
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
5743
7343
  } as const;
5744
7344
 
5745
7345
  export const $AccountsResponseDto = {
@@ -5774,7 +7374,7 @@ export const $AccountItemWithAssetClassDto = {
5774
7374
  name: {
5775
7375
  type: 'string',
5776
7376
  description: 'Full account name',
5777
- example: 'Assets:Bank:CMB:Savings'
7377
+ example: 'Assets:CN:CMB:Savings'
5778
7378
  },
5779
7379
  displayName: {
5780
7380
  type: 'string',
@@ -5791,6 +7391,12 @@ export const $AccountItemWithAssetClassDto = {
5791
7391
  description: 'Currency code',
5792
7392
  example: 'CNY'
5793
7393
  },
7394
+ convertedBalance: {
7395
+ type: 'string',
7396
+ description:
7397
+ 'FX-converted balance in base currency; omitted when not convertible',
7398
+ example: '50000.00'
7399
+ },
5794
7400
  assetClass: {
5795
7401
  type: 'string',
5796
7402
  description: 'Asset class',
@@ -5810,6 +7416,12 @@ export const $AccountItemWithAssetClassDto = {
5810
7416
  type: 'string',
5811
7417
  description: 'Risk level',
5812
7418
  example: 'LOW'
7419
+ },
7420
+ source: {
7421
+ type: 'string',
7422
+ description:
7423
+ 'ADR-0105 classification provenance (holding level always; account level only on FALLBACK)',
7424
+ enum: ['USER_META', 'FIAT_CURRENCY', 'OPENBB_MAPPING', 'FALLBACK']
5813
7425
  }
5814
7426
  },
5815
7427
  required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
@@ -5864,82 +7476,154 @@ export const $AssetClassGroupDto = {
5864
7476
  required: ['assetClass', 'accounts', 'balanceByCurrency']
5865
7477
  } as const;
5866
7478
 
5867
- export const $AccountExchangeRateWarningDto = {
7479
+ export const $AssetClassSummaryDto = {
5868
7480
  type: 'object',
5869
7481
  properties: {
5870
- type: {
5871
- type: 'string',
5872
- description: 'Warning type',
5873
- example: 'MISSING_EXCHANGE_RATE'
7482
+ totalAccounts: {
7483
+ type: 'number',
7484
+ description: 'Total number of accounts'
5874
7485
  },
5875
- currency: {
7486
+ totalAssetClasses: {
7487
+ type: 'number',
7488
+ description: 'Total number of asset classes'
7489
+ },
7490
+ baseCurrency: {
5876
7491
  type: 'string',
5877
- description: 'Currency without exchange rate',
5878
- example: 'USD'
7492
+ description: 'Base currency for conversion',
7493
+ example: 'CNY'
5879
7494
  },
5880
- accounts: {
5881
- description: 'Affected account paths',
7495
+ warnings: {
7496
+ description: 'Exchange rate warnings',
5882
7497
  type: 'array',
5883
7498
  items: {
5884
- type: 'string'
7499
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
5885
7500
  }
5886
7501
  },
5887
- totalAmount: {
5888
- type: 'string',
5889
- description: 'Total amount in this currency',
5890
- example: '5000.00'
7502
+ fallback: {
7503
+ type: 'object',
7504
+ description:
7505
+ 'ADR-0105 §4 fallback provenance stats (holding level only). valueRatio is the grey-area share of total converted value; count is the number of source=FALLBACK holdings.'
5891
7506
  }
5892
7507
  },
5893
- required: ['type', 'currency', 'accounts', 'totalAmount']
7508
+ required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
5894
7509
  } as const;
5895
7510
 
5896
- export const $AssetClassSummaryDto = {
7511
+ export const $AssetClassAccountsResponseDto = {
5897
7512
  type: 'object',
5898
7513
  properties: {
5899
- totalAccounts: {
5900
- type: 'number',
5901
- description: 'Total number of accounts'
7514
+ groups: {
7515
+ description: 'Account groups by asset class',
7516
+ type: 'array',
7517
+ items: {
7518
+ $ref: '#/components/schemas/AssetClassGroupDto'
7519
+ }
7520
+ },
7521
+ summary: {
7522
+ description: 'Summary statistics',
7523
+ allOf: [
7524
+ {
7525
+ $ref: '#/components/schemas/AssetClassSummaryDto'
7526
+ }
7527
+ ]
7528
+ },
7529
+ uncategorized: {
7530
+ description:
7531
+ 'ADR-0105 §6 holding-level grey-area bucket (source=FALLBACK holdings peeled out of groups). Present only for groupBy=holdingAssetClass when FALLBACK holdings exist.',
7532
+ allOf: [
7533
+ {
7534
+ $ref: '#/components/schemas/AssetClassGroupDto'
7535
+ }
7536
+ ]
7537
+ }
7538
+ },
7539
+ required: ['groups', 'summary']
7540
+ } as const;
7541
+
7542
+ export const $HoldingAssetClassAccountSliceDto = {
7543
+ type: 'object',
7544
+ properties: {
7545
+ accountId: {
7546
+ type: 'string',
7547
+ description: 'Account ID'
7548
+ },
7549
+ accountPath: {
7550
+ type: 'string',
7551
+ description: 'Full account path',
7552
+ example: 'Assets:US:Fidelity:Brokerage'
7553
+ },
7554
+ accountCurrency: {
7555
+ type: 'string',
7556
+ description:
7557
+ 'Currency of the holding with the largest converted base value; undefined when no holding is convertible',
7558
+ example: 'USD'
7559
+ },
7560
+ marketValueBase: {
7561
+ type: 'string',
7562
+ description:
7563
+ "Account's market value in base currency (Σ converted holdings; grey bucket included)",
7564
+ example: '50000.00'
5902
7565
  },
5903
- totalAssetClasses: {
7566
+ shareOfTotalPct: {
5904
7567
  type: 'number',
5905
- description: 'Total number of asset classes'
7568
+ description:
7569
+ 'Share of the global total (0-100). 0 when globalTotal is zero (no NaN/Infinity).',
7570
+ example: 42.5
5906
7571
  },
5907
- baseCurrency: {
5908
- type: 'string',
5909
- description: 'Base currency for conversion',
5910
- example: 'CNY'
7572
+ groups: {
7573
+ description: 'Per-account asset-class breakdown',
7574
+ type: 'array',
7575
+ items: {
7576
+ $ref: '#/components/schemas/AssetClassGroupDto'
7577
+ }
5911
7578
  },
5912
- warnings: {
5913
- description: 'Exchange rate warnings',
7579
+ uncategorized: {
7580
+ description:
7581
+ 'Per-account grey bucket (source=FALLBACK holdings, incl. broker cash)',
7582
+ allOf: [
7583
+ {
7584
+ $ref: '#/components/schemas/AssetClassGroupDto'
7585
+ }
7586
+ ]
7587
+ },
7588
+ holdings: {
7589
+ description:
7590
+ 'Every holding row for this account (account ID in each row’s `id` field)',
5914
7591
  type: 'array',
5915
7592
  items: {
5916
- $ref: '#/components/schemas/AccountExchangeRateWarningDto'
7593
+ $ref: '#/components/schemas/AccountItemWithAssetClassDto'
5917
7594
  }
5918
7595
  }
5919
7596
  },
5920
- required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
7597
+ required: [
7598
+ 'accountId',
7599
+ 'accountPath',
7600
+ 'marketValueBase',
7601
+ 'shareOfTotalPct',
7602
+ 'groups',
7603
+ 'holdings'
7604
+ ]
5921
7605
  } as const;
5922
7606
 
5923
- export const $AssetClassAccountsResponseDto = {
7607
+ export const $HoldingAssetClassCrossAccountResponseDto = {
5924
7608
  type: 'object',
5925
7609
  properties: {
5926
- groups: {
5927
- description: 'Account groups by asset class',
5928
- type: 'array',
5929
- items: {
5930
- $ref: '#/components/schemas/AssetClassGroupDto'
5931
- }
5932
- },
5933
- summary: {
5934
- description: 'Summary statistics',
7610
+ global: {
7611
+ description: 'Merged cross-account holding aggregation',
5935
7612
  allOf: [
5936
7613
  {
5937
- $ref: '#/components/schemas/AssetClassSummaryDto'
7614
+ $ref: '#/components/schemas/AssetClassAccountsResponseDto'
5938
7615
  }
5939
7616
  ]
7617
+ },
7618
+ byAccount: {
7619
+ description: 'Per-account slices',
7620
+ type: 'array',
7621
+ items: {
7622
+ $ref: '#/components/schemas/HoldingAssetClassAccountSliceDto'
7623
+ }
5940
7624
  }
5941
7625
  },
5942
- required: ['groups', 'summary']
7626
+ required: ['global', 'byAccount']
5943
7627
  } as const;
5944
7628
 
5945
7629
  export const $CashFlowByCurrencyDto = {
@@ -6041,207 +7725,582 @@ export const $CashFlowResponseDto = {
6041
7725
  description: 'Cash flow grouped by original currency',
6042
7726
  allOf: [
6043
7727
  {
6044
- $ref: '#/components/schemas/CashFlowByCurrencyDto'
7728
+ $ref: '#/components/schemas/CashFlowByCurrencyDto'
7729
+ }
7730
+ ]
7731
+ },
7732
+ converted: {
7733
+ description: 'Converted values in base currency',
7734
+ allOf: [
7735
+ {
7736
+ $ref: '#/components/schemas/ConvertedCashFlowDto'
7737
+ }
7738
+ ]
7739
+ },
7740
+ warnings: {
7741
+ description: 'Exchange rate warnings',
7742
+ type: 'array',
7743
+ items: {
7744
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
7745
+ }
7746
+ }
7747
+ },
7748
+ required: [
7749
+ 'period',
7750
+ 'income',
7751
+ 'expense',
7752
+ 'netSavings',
7753
+ 'savingsRate',
7754
+ 'currency'
7755
+ ]
7756
+ } as const;
7757
+
7758
+ export const $CategoryGroupDto = {
7759
+ type: 'object',
7760
+ properties: {
7761
+ category: {
7762
+ type: 'string',
7763
+ description:
7764
+ 'Functional category (account-path Group segment); regional and universal account paths merge under it',
7765
+ example: 'Food'
7766
+ },
7767
+ totalExpense: {
7768
+ type: 'string',
7769
+ description:
7770
+ 'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
7771
+ example: '1200.00'
7772
+ },
7773
+ sharePct: {
7774
+ type: 'number',
7775
+ description: 'Share of grand total (0-100); 0 when grand total is 0',
7776
+ example: 42.5
7777
+ },
7778
+ balanceByCurrency: {
7779
+ description: 'Raw (unconverted) expense per currency',
7780
+ type: 'array',
7781
+ items: {
7782
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
7783
+ }
7784
+ },
7785
+ convertedBalance: {
7786
+ type: 'string',
7787
+ description:
7788
+ 'Converted total in base currency (omitted when FX missing for all currencies in this category)',
7789
+ example: '1200.00'
7790
+ }
7791
+ },
7792
+ required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
7793
+ } as const;
7794
+
7795
+ export const $ExpensesByCategorySummaryDto = {
7796
+ type: 'object',
7797
+ properties: {
7798
+ totalExpense: {
7799
+ type: 'string',
7800
+ description:
7801
+ 'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
7802
+ example: '5000.00'
7803
+ },
7804
+ categoryCount: {
7805
+ type: 'number',
7806
+ description: 'Number of categories',
7807
+ example: 8
7808
+ }
7809
+ },
7810
+ required: ['totalExpense', 'categoryCount']
7811
+ } as const;
7812
+
7813
+ export const $ExpensesByCategoryResponseDto = {
7814
+ type: 'object',
7815
+ properties: {
7816
+ period: {
7817
+ type: 'string',
7818
+ description: 'Period requested',
7819
+ example: '1m'
7820
+ },
7821
+ baseCurrency: {
7822
+ type: 'string',
7823
+ description: 'Base currency for converted values',
7824
+ example: 'CNY'
7825
+ },
7826
+ groups: {
7827
+ description:
7828
+ 'Expense groups by functional category, sorted by converted total desc',
7829
+ type: 'array',
7830
+ items: {
7831
+ $ref: '#/components/schemas/CategoryGroupDto'
7832
+ }
7833
+ },
7834
+ summary: {
7835
+ description: 'Summary statistics',
7836
+ allOf: [
7837
+ {
7838
+ $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
7839
+ }
7840
+ ]
7841
+ },
7842
+ warnings: {
7843
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
7844
+ type: 'array',
7845
+ items: {
7846
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
7847
+ }
7848
+ }
7849
+ },
7850
+ required: ['period', 'baseCurrency', 'groups', 'summary']
7851
+ } as const;
7852
+
7853
+ export const $MonetaryDto = {
7854
+ type: 'object',
7855
+ properties: {
7856
+ amount: {
7857
+ type: 'string',
7858
+ description: 'Amount (Decimal string)',
7859
+ example: '3000'
7860
+ },
7861
+ currency: {
7862
+ type: 'string',
7863
+ description: 'ISO 4217 currency',
7864
+ example: 'USD'
7865
+ },
7866
+ baseCcyEquivalent: {
7867
+ type: 'object',
7868
+ description: 'Converted to user base currency (Decimal string)',
7869
+ example: '21600',
7870
+ nullable: true
7871
+ }
7872
+ },
7873
+ required: ['amount', 'currency']
7874
+ } as const;
7875
+
7876
+ export const $CurrentPriceDto = {
7877
+ type: 'object',
7878
+ properties: {
7879
+ amount: {
7880
+ type: 'string',
7881
+ description: 'Price amount (Decimal string)',
7882
+ example: '250'
7883
+ },
7884
+ currency: {
7885
+ type: 'string',
7886
+ description: 'Price currency (ISO 4217)',
7887
+ example: 'USD'
7888
+ },
7889
+ date: {
7890
+ type: 'string',
7891
+ description: 'Price date (ISO 8601)',
7892
+ example: '2024-06-01'
7893
+ },
7894
+ source: {
7895
+ type: 'string',
7896
+ description: 'Price source',
7897
+ example: 'USER_OVERRIDE',
7898
+ enum: ['USER_OVERRIDE', 'OPENBB_EQUITY', 'OPENBB_CURRENCY']
7899
+ }
7900
+ },
7901
+ required: ['amount', 'currency', 'date', 'source']
7902
+ } as const;
7903
+
7904
+ export const $FxRateDto = {
7905
+ type: 'object',
7906
+ properties: {
7907
+ from: {
7908
+ type: 'string',
7909
+ example: 'USD'
7910
+ },
7911
+ to: {
7912
+ type: 'string',
7913
+ example: 'CNY'
7914
+ },
7915
+ rate: {
7916
+ type: 'string',
7917
+ description: 'FX rate (Decimal string)',
7918
+ example: '7.2'
7919
+ },
7920
+ date: {
7921
+ type: 'string',
7922
+ description: 'Rate date (ISO 8601)',
7923
+ example: '2024-01-15'
7924
+ }
7925
+ },
7926
+ required: ['from', 'to', 'rate', 'date']
7927
+ } as const;
7928
+
7929
+ export const $HoldingPnlRowDto = {
7930
+ type: 'object',
7931
+ properties: {
7932
+ accountId: {
7933
+ type: 'string',
7934
+ description: 'Account UUID',
7935
+ example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
7936
+ },
7937
+ accountPath: {
7938
+ type: 'string',
7939
+ description: 'Full account path',
7940
+ example: 'Assets:US:Broker:AAPL'
7941
+ },
7942
+ accountCcy: {
7943
+ type: 'object',
7944
+ description: 'Account settlement currency (ISO 4217), from cost currency',
7945
+ nullable: true,
7946
+ example: 'USD'
7947
+ },
7948
+ brokerType: {
7949
+ type: 'object',
7950
+ description: 'Broker type derived from Platform.type',
7951
+ nullable: true,
7952
+ example: 'broker'
7953
+ },
7954
+ symbol: {
7955
+ type: 'string',
7956
+ description: 'Commodity symbol',
7957
+ example: 'AAPL'
7958
+ },
7959
+ chartToken: {
7960
+ type: 'string',
7961
+ description: 'Chart segment token (libs/common resolver)',
7962
+ example: 'equity',
7963
+ enum: ['equity', 'fund', 'bond', 'cash', 'other']
7964
+ },
7965
+ assetClass: {
7966
+ type: 'string',
7967
+ example: 'EQUITY'
7968
+ },
7969
+ assetSubClass: {
7970
+ type: 'object',
7971
+ nullable: true,
7972
+ example: 'STOCK'
7973
+ },
7974
+ units: {
7975
+ type: 'string',
7976
+ description: 'Net held units (Decimal string)',
7977
+ example: '12'
7978
+ },
7979
+ averageCostPerUnit: {
7980
+ description:
7981
+ 'Average cost per unit; null when cost currency conflicts or no cost',
7982
+ nullable: true,
7983
+ allOf: [
7984
+ {
7985
+ $ref: '#/components/schemas/MonetaryDto'
7986
+ }
7987
+ ]
7988
+ },
7989
+ costBasis: {
7990
+ description: 'Cost basis of held units',
7991
+ nullable: true,
7992
+ allOf: [
7993
+ {
7994
+ $ref: '#/components/schemas/MonetaryDto'
7995
+ }
7996
+ ]
7997
+ },
7998
+ marketValue: {
7999
+ description: 'Market value at asOf price',
8000
+ nullable: true,
8001
+ allOf: [
8002
+ {
8003
+ $ref: '#/components/schemas/MonetaryDto'
8004
+ }
8005
+ ]
8006
+ },
8007
+ currentPrice: {
8008
+ description: 'Price used for market value',
8009
+ nullable: true,
8010
+ allOf: [
8011
+ {
8012
+ $ref: '#/components/schemas/CurrentPriceDto'
8013
+ }
8014
+ ]
8015
+ },
8016
+ unrealizedPnlBase: {
8017
+ type: 'object',
8018
+ description:
8019
+ 'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
8020
+ nullable: true,
8021
+ example: '6000'
8022
+ },
8023
+ unrealizedPnlPct: {
8024
+ type: 'object',
8025
+ description: 'Unrealized P&L % (Decimal string)',
8026
+ nullable: true,
8027
+ example: '25'
8028
+ },
8029
+ costFxRate: {
8030
+ description: 'Historical FX rate applied to cost basis',
8031
+ nullable: true,
8032
+ allOf: [
8033
+ {
8034
+ $ref: '#/components/schemas/FxRateDto'
6045
8035
  }
6046
8036
  ]
6047
8037
  },
6048
- converted: {
6049
- description: 'Converted values in base currency',
8038
+ marketFxRate: {
8039
+ description: 'FX rate applied to market value',
8040
+ nullable: true,
6050
8041
  allOf: [
6051
8042
  {
6052
- $ref: '#/components/schemas/ConvertedCashFlowDto'
8043
+ $ref: '#/components/schemas/FxRateDto'
6053
8044
  }
6054
8045
  ]
6055
8046
  },
6056
- warnings: {
6057
- description: 'Exchange rate warnings',
6058
- type: 'array',
6059
- items: {
6060
- $ref: '#/components/schemas/ExchangeRateWarningDto'
6061
- }
8047
+ pctOfInvestedAssets: {
8048
+ type: 'object',
8049
+ description:
8050
+ 'Share of invested assets % (Decimal string); only for invested chartTokens',
8051
+ nullable: true,
8052
+ example: '40'
8053
+ },
8054
+ realizedPnl: {
8055
+ description:
8056
+ 'Cumulative realized P&L on sold lots (asOf-date cutoff); null when the method has no applicable sells, a sell lacks a price, or any required FX rate is missing (never-mix). When a sell spans multiple currencies (cross-currency sale), amount and currency reflect the base currency; baseCcyEquivalent is always the authoritative dual-FX figure',
8057
+ nullable: true,
8058
+ allOf: [
8059
+ {
8060
+ $ref: '#/components/schemas/MonetaryDto'
8061
+ }
8062
+ ]
6062
8063
  }
6063
8064
  },
6064
8065
  required: [
6065
- 'period',
6066
- 'income',
6067
- 'expense',
6068
- 'netSavings',
6069
- 'savingsRate',
6070
- 'currency'
8066
+ 'accountId',
8067
+ 'accountPath',
8068
+ 'symbol',
8069
+ 'chartToken',
8070
+ 'assetClass',
8071
+ 'units'
6071
8072
  ]
6072
8073
  } as const;
6073
8074
 
6074
- export const $CurrencyBalanceDto = {
8075
+ export const $HoldingPnlWarningDto = {
6075
8076
  type: 'object',
6076
8077
  properties: {
6077
- currency: {
8078
+ type: {
6078
8079
  type: 'string',
6079
- description: 'ISO 4217 currency code',
6080
- example: 'CNY'
8080
+ description: 'Warning type',
8081
+ example: 'MISSING_COST_FX_RATE',
8082
+ enum: [
8083
+ 'MISSING_COST_FX_RATE',
8084
+ 'MISSING_MARKET_FX_RATE',
8085
+ 'MISSING_SALE_PRICE',
8086
+ 'MISSING_REALIZED_FX_RATE',
8087
+ 'OVERSOLD_LOTS',
8088
+ 'NO_PRICE',
8089
+ 'MIXED_COST_CURRENCY'
8090
+ ]
6081
8091
  },
6082
- balance: {
6083
- type: 'string',
6084
- description: 'Balance amount',
6085
- example: '500000.00'
8092
+ symbol: {
8093
+ type: 'object',
8094
+ nullable: true
8095
+ },
8096
+ accountId: {
8097
+ type: 'object',
8098
+ nullable: true
8099
+ },
8100
+ currency: {
8101
+ type: 'object',
8102
+ nullable: true
6086
8103
  }
6087
8104
  },
6088
- required: ['currency', 'balance']
8105
+ required: ['type']
6089
8106
  } as const;
6090
8107
 
6091
- export const $TimeSeriesPointDto = {
8108
+ export const $HoldingPnlResponseDto = {
6092
8109
  type: 'object',
6093
8110
  properties: {
6094
- date: {
8111
+ asOfDate: {
6095
8112
  type: 'string',
6096
- description: 'Date in YYYY-MM-DD format',
6097
- example: '2024-06-15'
8113
+ example: '2026-07-08'
6098
8114
  },
6099
- value: {
8115
+ baseCurrency: {
6100
8116
  type: 'string',
6101
- description: 'Value at this date (in base currency)',
6102
- example: '500000.00'
8117
+ example: 'CNY'
6103
8118
  },
6104
- change: {
6105
- type: 'object',
6106
- description: 'Change from previous point',
6107
- example: '5000.00'
8119
+ method: {
8120
+ type: 'string',
8121
+ description:
8122
+ 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
8123
+ enum: ['average', 'FIFO'],
8124
+ example: 'average'
6108
8125
  },
6109
- byCurrency: {
6110
- description: 'Multi-currency breakdown for this point',
8126
+ rows: {
6111
8127
  type: 'array',
6112
8128
  items: {
6113
- $ref: '#/components/schemas/CurrencyBalanceDto'
8129
+ $ref: '#/components/schemas/HoldingPnlRowDto'
8130
+ }
8131
+ },
8132
+ warnings: {
8133
+ type: 'array',
8134
+ items: {
8135
+ $ref: '#/components/schemas/HoldingPnlWarningDto'
6114
8136
  }
6115
8137
  }
6116
8138
  },
6117
- required: ['date', 'value']
8139
+ required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6118
8140
  } as const;
6119
8141
 
6120
- export const $TrendSummaryDto = {
8142
+ export const $AnonymousLoginDto = {
6121
8143
  type: 'object',
6122
8144
  properties: {
6123
- startValue: {
6124
- type: 'string',
6125
- description: 'Value at start of period',
6126
- example: '450000.00'
6127
- },
6128
- endValue: {
6129
- type: 'string',
6130
- description: 'Value at end of period',
6131
- example: '500000.00'
6132
- },
6133
- totalChange: {
6134
- type: 'string',
6135
- description: 'Total change over period',
6136
- example: '50000.00'
6137
- },
6138
- totalChangePercentage: {
8145
+ accessToken: {
6139
8146
  type: 'string',
6140
- description: 'Total change percentage',
6141
- example: '+11.11%'
8147
+ description: 'Access token for anonymous login'
6142
8148
  }
6143
8149
  },
6144
- required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
8150
+ required: ['accessToken']
6145
8151
  } as const;
6146
8152
 
6147
- export const $MultiCurrencyPointDto = {
8153
+ export const $AnonymousLoginResponseDto = {
6148
8154
  type: 'object',
6149
8155
  properties: {
6150
- date: {
8156
+ authToken: {
6151
8157
  type: 'string',
6152
- description: 'Date in YYYY-MM-DD format',
6153
- example: '2024-06-15'
6154
- },
6155
- byCurrency: {
6156
- description: 'Balances by currency',
6157
- type: 'array',
6158
- items: {
6159
- $ref: '#/components/schemas/CurrencyBalanceDto'
6160
- }
8158
+ description: 'JWT auth token',
8159
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
6161
8160
  }
6162
8161
  },
6163
- required: ['date', 'byCurrency']
8162
+ required: ['authToken']
6164
8163
  } as const;
6165
8164
 
6166
- export const $PortfolioTrendsResponseDto = {
8165
+ export const $SymbolSearchResultDto = {
6167
8166
  type: 'object',
6168
8167
  properties: {
6169
- series: {
6170
- description: 'Time series data points',
6171
- type: 'array',
6172
- items: {
6173
- $ref: '#/components/schemas/TimeSeriesPointDto'
6174
- }
8168
+ symbol: {
8169
+ type: 'string',
8170
+ example: 'AAPL'
6175
8171
  },
6176
- summary: {
6177
- description: 'Period summary',
6178
- allOf: [
6179
- {
6180
- $ref: '#/components/schemas/TrendSummaryDto'
6181
- }
6182
- ]
8172
+ name: {
8173
+ type: 'object',
8174
+ example: 'Apple Inc.',
8175
+ nullable: true
6183
8176
  },
6184
- period: {
6185
- type: 'string',
6186
- description: 'Period requested',
6187
- example: '6m'
8177
+ exchange: {
8178
+ type: 'object',
8179
+ example: 'US',
8180
+ nullable: true
6188
8181
  },
6189
- granularity: {
6190
- type: 'string',
6191
- description: 'Data granularity',
6192
- example: 'month'
8182
+ assetType: {
8183
+ type: 'object',
8184
+ description: 'OpenBB asset_type (e.g. stock, etf)',
8185
+ example: 'stock',
8186
+ nullable: true
6193
8187
  },
6194
- currency: {
6195
- type: 'string',
6196
- description: 'Base currency for converted values',
6197
- example: 'CNY'
8188
+ assetClass: {
8189
+ type: 'object',
8190
+ description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
8191
+ example: 'EQUITY',
8192
+ nullable: true
6198
8193
  },
6199
- byCurrency: {
6200
- description:
6201
- 'Multi-currency time series (each point has currency breakdown)',
6202
- type: 'array',
6203
- items: {
6204
- $ref: '#/components/schemas/MultiCurrencyPointDto'
6205
- }
8194
+ assetSubClass: {
8195
+ type: 'object',
8196
+ description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
8197
+ example: 'STOCK',
8198
+ nullable: true
6206
8199
  },
6207
- warnings: {
6208
- description: 'Exchange rate warnings',
6209
- type: 'array',
6210
- items: {
6211
- $ref: '#/components/schemas/ExchangeRateWarningDto'
6212
- }
8200
+ currency: {
8201
+ type: 'object',
8202
+ description: 'Trading currency (extra_data or inferred from exchange)',
8203
+ example: 'USD',
8204
+ nullable: true
6213
8205
  }
6214
8206
  },
6215
- required: ['series', 'summary', 'period', 'granularity', 'currency']
6216
- } as const;
6217
-
6218
- export const $GenerateSnapshotBody = {
6219
- type: 'object',
6220
- properties: {}
6221
- } as const;
6222
-
6223
- export const $GenerateSnapshotResponse = {
6224
- type: 'object',
6225
- properties: {}
6226
- } as const;
6227
-
6228
- export const $BackfillSnapshotsBody = {
6229
- type: 'object',
6230
- properties: {}
6231
- } as const;
6232
-
6233
- export const $BackfillSnapshotsResponse = {
6234
- type: 'object',
6235
- properties: {}
8207
+ required: ['symbol']
6236
8208
  } as const;
6237
8209
 
6238
- export const $AnonymousLoginDto = {
8210
+ export const $SymbolQuoteDto = {
6239
8211
  type: 'object',
6240
8212
  properties: {
6241
- accessToken: {
8213
+ symbol: {
6242
8214
  type: 'string',
6243
- description: 'Access token for anonymous login'
8215
+ example: 'AAPL'
8216
+ },
8217
+ name: {
8218
+ type: 'object',
8219
+ example: 'Apple Inc.',
8220
+ nullable: true
8221
+ },
8222
+ exchange: {
8223
+ type: 'object',
8224
+ example: 'US',
8225
+ nullable: true
8226
+ },
8227
+ assetType: {
8228
+ type: 'object',
8229
+ description: 'OpenBB asset_type',
8230
+ example: 'stock',
8231
+ nullable: true
8232
+ },
8233
+ assetClass: {
8234
+ type: 'object',
8235
+ description: 'IGN asset class',
8236
+ example: 'EQUITY',
8237
+ nullable: true
8238
+ },
8239
+ assetSubClass: {
8240
+ type: 'object',
8241
+ description: 'IGN asset sub-class',
8242
+ example: 'STOCK',
8243
+ nullable: true
8244
+ },
8245
+ currency: {
8246
+ type: 'object',
8247
+ description: 'Trading currency (extra_data or inferred from exchange)',
8248
+ example: 'USD',
8249
+ nullable: true
8250
+ },
8251
+ price: {
8252
+ type: 'object',
8253
+ description: 'Latest price (Decimal string)',
8254
+ example: '189.84',
8255
+ nullable: true
8256
+ },
8257
+ priceDate: {
8258
+ type: 'object',
8259
+ description: 'Date the price was observed (ISO yyyy-MM-dd)',
8260
+ example: '2026-08-05',
8261
+ nullable: true
8262
+ },
8263
+ changePercent: {
8264
+ type: 'object',
8265
+ description:
8266
+ '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.',
8267
+ example: 1.7,
8268
+ nullable: true
8269
+ },
8270
+ prevClose: {
8271
+ type: 'object',
8272
+ description: 'Previous close (Decimal string)',
8273
+ nullable: true
8274
+ },
8275
+ open: {
8276
+ type: 'object',
8277
+ description: 'Day open (Decimal string)',
8278
+ nullable: true
8279
+ },
8280
+ high: {
8281
+ type: 'object',
8282
+ description: 'Day high (Decimal string)',
8283
+ nullable: true
8284
+ },
8285
+ low: {
8286
+ type: 'object',
8287
+ description: 'Day low (Decimal string)',
8288
+ nullable: true
8289
+ },
8290
+ volume: {
8291
+ type: 'object',
8292
+ description: 'Day volume (Decimal string)',
8293
+ nullable: true
8294
+ },
8295
+ yearHigh: {
8296
+ type: 'object',
8297
+ description: '52-week high (Decimal string)',
8298
+ nullable: true
8299
+ },
8300
+ yearLow: {
8301
+ type: 'object',
8302
+ description: '52-week low (Decimal string)',
8303
+ nullable: true
6244
8304
  }
6245
- },
6246
- required: ['accessToken']
8305
+ }
6247
8306
  } as const;