@firela/api-types 0.0.0-canary.ba0a88d9 → 0.0.0-canary.c5520a90

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.
@@ -329,9 +329,14 @@ export const $AccountStandardResponseDto = {
329
329
  description: 'i18n key for localized display name',
330
330
  example: 'account.assets.cn.bank.icbc.checking'
331
331
  },
332
+ name: {
333
+ type: 'string',
334
+ description: 'Short localized display name',
335
+ example: 'Housing Fund'
336
+ },
332
337
  description: {
333
338
  type: 'string',
334
- description: 'Account description',
339
+ description: 'Account description (stable semantics only)',
335
340
  example: 'ICBC checking account for daily transactions'
336
341
  },
337
342
  tags: {
@@ -348,7 +353,7 @@ export const $AccountStandardResponseDto = {
348
353
  example: 'bank-icbc'
349
354
  }
350
355
  },
351
- required: ['path', 'type']
356
+ required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
352
357
  } as const;
353
358
 
354
359
  export const $AccountStandardListResponseDto = {
@@ -432,11 +437,10 @@ export const $RegionInfoDto = {
432
437
  example: 'Germany'
433
438
  },
434
439
  parent: {
435
- type: 'string',
436
- example: 'eu-core'
440
+ type: 'string'
437
441
  },
438
442
  chain: {
439
- example: ['eu-core', 'de'],
443
+ example: ['de'],
440
444
  type: 'array',
441
445
  items: {
442
446
  type: 'string'
@@ -462,6 +466,66 @@ export const $RegionsMetadataResponseDto = {
462
466
  required: ['regions']
463
467
  } as const;
464
468
 
469
+ export const $CostSpecDto = {
470
+ type: 'object',
471
+ properties: {
472
+ mode: {
473
+ type: 'string',
474
+ enum: ['per-unit', 'total', 'date', 'label', 'auto'],
475
+ description: 'Cost specification mode (mirrors engine CostSpec)'
476
+ },
477
+ numberPerUnit: {
478
+ type: 'string',
479
+ description: 'Per-unit cost (required when mode is "per-unit")',
480
+ example: '240'
481
+ },
482
+ totalNumber: {
483
+ type: 'string',
484
+ description: 'Total cost for all units (required when mode is "total")',
485
+ example: '12000'
486
+ },
487
+ currency: {
488
+ type: 'string',
489
+ description: 'Cost currency (required in all modes)',
490
+ example: 'USD'
491
+ },
492
+ date: {
493
+ type: 'string',
494
+ description:
495
+ 'Lot acquisition date, ISO 8601 (required when mode is "date")',
496
+ example: '2024-01-15'
497
+ },
498
+ label: {
499
+ type: 'string',
500
+ description:
501
+ 'Lot label (required when mode is "label"; optional tag in buy modes)'
502
+ },
503
+ merge: {
504
+ type: 'boolean',
505
+ description: 'Merge lots for AVERAGE booking (mode: auto)'
506
+ }
507
+ },
508
+ required: ['mode', 'currency']
509
+ } as const;
510
+
511
+ export const $AmountDto = {
512
+ type: 'object',
513
+ properties: {
514
+ number: {
515
+ type: 'string',
516
+ description:
517
+ 'Amount as decimal string (max 15 integer + 15 decimal digits)',
518
+ example: '170.50'
519
+ },
520
+ currency: {
521
+ type: 'string',
522
+ description: 'Currency/commodity code',
523
+ example: 'USD'
524
+ }
525
+ },
526
+ required: ['number', 'currency']
527
+ } as const;
528
+
465
529
  export const $CreatePostingDto = {
466
530
  type: 'object',
467
531
  properties: {
@@ -491,6 +555,33 @@ export const $CreatePostingDto = {
491
555
  example: {
492
556
  'tax-lot': 'Q1-2024'
493
557
  }
558
+ },
559
+ cost: {
560
+ description:
561
+ 'Cost basis (Beancount `{...}`). Maps to engine costSpec. Required for commodity holdings so they carry a monetary weight that can balance.',
562
+ example: {
563
+ mode: 'per-unit',
564
+ numberPerUnit: '240',
565
+ currency: 'USD'
566
+ },
567
+ allOf: [
568
+ {
569
+ $ref: '#/components/schemas/CostSpecDto'
570
+ }
571
+ ]
572
+ },
573
+ price: {
574
+ description:
575
+ 'Price annotation (Beancount `@...`). Maps to engine price. Used for valuation; cost takes priority for balance weight.',
576
+ example: {
577
+ number: '170',
578
+ currency: 'USD'
579
+ },
580
+ allOf: [
581
+ {
582
+ $ref: '#/components/schemas/AmountDto'
583
+ }
584
+ ]
494
585
  }
495
586
  },
496
587
  required: ['account']
@@ -569,6 +660,32 @@ export const $CreateTransactionDto = {
569
660
  required: ['date', 'narration', 'postings']
570
661
  } as const;
571
662
 
663
+ export const $CostDetailDto = {
664
+ type: 'object',
665
+ properties: {
666
+ number: {
667
+ type: 'string',
668
+ description: 'Per-unit cost basis (mirrors engine Cost.number)',
669
+ example: '240'
670
+ },
671
+ currency: {
672
+ type: 'string',
673
+ description: 'Cost currency',
674
+ example: 'USD'
675
+ },
676
+ date: {
677
+ type: 'string',
678
+ description: 'Lot acquisition date (ISO yyyy-mm-dd)',
679
+ example: '2024-01-15'
680
+ },
681
+ label: {
682
+ type: 'string',
683
+ description: 'Lot label',
684
+ example: 'lot-2024-01'
685
+ }
686
+ }
687
+ } as const;
688
+
572
689
  export const $PostingResponseDto = {
573
690
  type: 'object',
574
691
  properties: {
@@ -579,13 +696,23 @@ export const $PostingResponseDto = {
579
696
  },
580
697
  units: {
581
698
  type: 'string',
582
- description: 'Amount (may be null if interpolated)',
699
+ description:
700
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
583
701
  example: '100.50'
584
702
  },
585
703
  currency: {
586
704
  type: 'string',
587
705
  description: 'Currency',
588
706
  example: 'USD'
707
+ },
708
+ cost: {
709
+ description:
710
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
711
+ allOf: [
712
+ {
713
+ $ref: '#/components/schemas/CostDetailDto'
714
+ }
715
+ ]
589
716
  }
590
717
  },
591
718
  required: ['account']
@@ -805,6 +932,11 @@ export const $BatchTransactionErrorDto = {
805
932
  type: 'string',
806
933
  description: 'Error message describing the failure',
807
934
  example: 'Transaction does not balance'
935
+ },
936
+ errorCode: {
937
+ type: 'string',
938
+ description: 'Structured error code for programmatic handling',
939
+ example: 'INSUFFICIENT_QUANTITY'
808
940
  }
809
941
  },
810
942
  required: ['index', 'error']
@@ -831,6 +963,85 @@ export const $BatchTransactionResponseDto = {
831
963
  required: ['succeeded', 'failed']
832
964
  } as const;
833
965
 
966
+ export const $CorrectTransactionDto = {
967
+ type: 'object',
968
+ properties: {
969
+ date: {
970
+ type: 'string',
971
+ description: 'Transaction date (ISO 8601 format)',
972
+ example: '2024-11-28'
973
+ },
974
+ flag: {
975
+ type: 'string',
976
+ description: 'Transaction flag: * (cleared), ! (pending)',
977
+ enum: ['*', '!'],
978
+ example: '*'
979
+ },
980
+ payee: {
981
+ type: 'string',
982
+ description: 'Payee name',
983
+ example: 'Whole Foods Market'
984
+ },
985
+ narration: {
986
+ type: 'string',
987
+ description: 'Transaction narration/description',
988
+ example: 'Grocery shopping'
989
+ },
990
+ tags: {
991
+ description: 'Transaction tags (without # prefix)',
992
+ example: ['vacation', 'personal'],
993
+ type: 'array',
994
+ items: {
995
+ type: 'string'
996
+ }
997
+ },
998
+ links: {
999
+ description: 'Transaction links (without ^ prefix)',
1000
+ example: ['invoice-123'],
1001
+ type: 'array',
1002
+ items: {
1003
+ type: 'string'
1004
+ }
1005
+ },
1006
+ postings: {
1007
+ description:
1008
+ 'Transaction postings (minimum 1, typically 2 for double-entry)',
1009
+ type: 'array',
1010
+ items: {
1011
+ $ref: '#/components/schemas/CreatePostingDto'
1012
+ }
1013
+ },
1014
+ meta: {
1015
+ type: 'object',
1016
+ description: 'Transaction-level metadata',
1017
+ example: {
1018
+ invoice: '12345'
1019
+ }
1020
+ },
1021
+ idempotencyKey: {
1022
+ type: 'string',
1023
+ description:
1024
+ 'Unique key for idempotent transaction creation. If provided, duplicate requests with the same key will return the existing transaction.',
1025
+ example: 'import-2024-01-15-batch-001',
1026
+ maxLength: 128
1027
+ },
1028
+ autoCreateAccounts: {
1029
+ type: 'boolean',
1030
+ description:
1031
+ '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.',
1032
+ default: true,
1033
+ example: true
1034
+ },
1035
+ correctionReason: {
1036
+ type: 'string',
1037
+ description: 'Reason for correcting/superseding the original transaction',
1038
+ example: 'Wrong amount — corrected from receipt',
1039
+ maxLength: 500
1040
+ }
1041
+ },
1042
+ required: ['date', 'narration', 'postings']
1043
+ } as const;
1044
+
834
1045
  export const $PostingDetailDto = {
835
1046
  type: 'object',
836
1047
  properties: {
@@ -844,14 +1055,15 @@ export const $PostingDetailDto = {
844
1055
  description: 'Account ID',
845
1056
  example: 'clh1234567890abcdef'
846
1057
  },
847
- accountName: {
1058
+ account: {
848
1059
  type: 'string',
849
- description: 'Account name',
1060
+ description: 'Fully-qualified Beancount account path',
850
1061
  example: 'Assets:Bank:Checking'
851
1062
  },
852
1063
  units: {
853
1064
  type: 'string',
854
- description: 'Amount (may be null if interpolated)',
1065
+ description:
1066
+ 'Amount as decimal string. Typed optional but always present in responses: interpolation fills any MISSING posting before it is persisted or returned.',
855
1067
  example: '100.50'
856
1068
  },
857
1069
  currency: {
@@ -874,6 +1086,15 @@ export const $PostingDetailDto = {
874
1086
  description: 'Cost date',
875
1087
  example: '2024-01-15'
876
1088
  },
1089
+ cost: {
1090
+ description:
1091
+ 'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
1092
+ allOf: [
1093
+ {
1094
+ $ref: '#/components/schemas/CostDetailDto'
1095
+ }
1096
+ ]
1097
+ },
877
1098
  priceAmount: {
878
1099
  type: 'string',
879
1100
  description: 'Price amount',
@@ -894,7 +1115,7 @@ export const $PostingDetailDto = {
894
1115
  description: 'Posting metadata'
895
1116
  }
896
1117
  },
897
- required: ['id', 'accountId', 'accountName']
1118
+ required: ['id', 'accountId', 'account']
898
1119
  } as const;
899
1120
 
900
1121
  export const $TransactionDetailDto = {
@@ -966,8 +1187,8 @@ export const $TransactionDetailDto = {
966
1187
  },
967
1188
  sourceType: {
968
1189
  type: 'string',
969
- description: 'Source type (how the transaction was created)',
970
- enum: ['NLP', 'CSV', 'OCR', 'API']
1190
+ description:
1191
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
971
1192
  },
972
1193
  sourcePlatform: {
973
1194
  type: 'string',
@@ -1000,6 +1221,18 @@ export const $TransactionDetailDto = {
1000
1221
  type: 'string',
1001
1222
  description: 'Correction reason (if voided or superseded)',
1002
1223
  example: 'Duplicate entry'
1224
+ },
1225
+ supersededBy: {
1226
+ type: 'string',
1227
+ description:
1228
+ 'ID of the transaction that supersedes this one (set when status=SUPERSEDED)',
1229
+ example: 'clh1234567890abcdef'
1230
+ },
1231
+ originalTxn: {
1232
+ type: 'string',
1233
+ description:
1234
+ 'ID of the transaction this one corrected/replaced (back-link on the replacement)',
1235
+ example: 'clh1234567890abcdef'
1003
1236
  }
1004
1237
  },
1005
1238
  required: [
@@ -1043,6 +1276,37 @@ export const $TransactionListResponseDto = {
1043
1276
  required: ['data', 'total', 'limit', 'offset']
1044
1277
  } as const;
1045
1278
 
1279
+ export const $TagSuggestionDto = {
1280
+ type: 'object',
1281
+ properties: {
1282
+ tag: {
1283
+ type: 'string',
1284
+ description: 'Tag name',
1285
+ example: 'Monthly'
1286
+ },
1287
+ count: {
1288
+ type: 'number',
1289
+ description: 'Usage count across ACTIVE transactions',
1290
+ example: 12
1291
+ }
1292
+ },
1293
+ required: ['tag', 'count']
1294
+ } as const;
1295
+
1296
+ export const $TagSuggestionsResponseDto = {
1297
+ type: 'object',
1298
+ properties: {
1299
+ data: {
1300
+ description: 'Tag suggestions sorted as requested',
1301
+ type: 'array',
1302
+ items: {
1303
+ $ref: '#/components/schemas/TagSuggestionDto'
1304
+ }
1305
+ }
1306
+ },
1307
+ required: ['data']
1308
+ } as const;
1309
+
1046
1310
  export const $UpdateTransactionDto = {
1047
1311
  type: 'object',
1048
1312
  properties: {
@@ -1193,8 +1457,8 @@ export const $TransactionSummaryDto = {
1193
1457
  },
1194
1458
  sourceType: {
1195
1459
  type: 'string',
1196
- description: 'Source type (NLP, CSV, OCR, API)',
1197
- enum: ['NLP', 'CSV', 'OCR', 'API']
1460
+ description:
1461
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1198
1462
  },
1199
1463
  sourcePlatform: {
1200
1464
  type: 'string',
@@ -1234,8 +1498,10 @@ export const $ReviewSummaryDto = {
1234
1498
  },
1235
1499
  confidenceLevel: {
1236
1500
  type: 'string',
1237
- description: 'Confidence level derived from score',
1238
- enum: ['HIGH', 'MEDIUM', 'LOW']
1501
+ description:
1502
+ 'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
1503
+ enum: ['HIGH', 'MEDIUM', 'LOW'],
1504
+ nullable: true
1239
1505
  },
1240
1506
  summaryKey: {
1241
1507
  type: 'string',
@@ -1259,7 +1525,8 @@ export const $ReviewSummaryDto = {
1259
1525
  },
1260
1526
  sourceType: {
1261
1527
  type: 'string',
1262
- description: 'Source type (NLP, CSV, OCR, API)'
1528
+ description:
1529
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1263
1530
  },
1264
1531
  sourcePlatform: {
1265
1532
  type: 'string',
@@ -1369,7 +1636,20 @@ export const $DecisionOptionDto = {
1369
1636
  properties: {
1370
1637
  value: {
1371
1638
  type: 'string',
1372
- description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)'
1639
+ description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)',
1640
+ enum: [
1641
+ 'UPGRADE_REPLACE',
1642
+ 'LINK_KEEP_BOTH',
1643
+ 'IGNORE_NEW',
1644
+ 'CONFIRM_DIFFERENT',
1645
+ 'ACCEPT',
1646
+ 'REJECT',
1647
+ 'ACCEPT_AND_LEARN',
1648
+ 'CHOOSE_OTHER',
1649
+ 'CANCEL',
1650
+ 'FIX',
1651
+ 'IGNORE'
1652
+ ]
1373
1653
  },
1374
1654
  labelKey: {
1375
1655
  type: 'string',
@@ -1417,8 +1697,10 @@ export const $ReviewDetailDto = {
1417
1697
  },
1418
1698
  confidenceLevel: {
1419
1699
  type: 'string',
1420
- description: 'Confidence level derived from score',
1421
- enum: ['HIGH', 'MEDIUM', 'LOW']
1700
+ description:
1701
+ 'Confidence level derived from score. Null for error-type reviews (ACCOUNT_VALIDATION/PIPELINE_ERROR) which carry no confidence.',
1702
+ enum: ['HIGH', 'MEDIUM', 'LOW'],
1703
+ nullable: true
1422
1704
  },
1423
1705
  summaryKey: {
1424
1706
  type: 'string',
@@ -1442,7 +1724,8 @@ export const $ReviewDetailDto = {
1442
1724
  },
1443
1725
  sourceType: {
1444
1726
  type: 'string',
1445
- description: 'Source type (NLP, CSV, OCR, API)'
1727
+ description:
1728
+ 'Source type (free-form string from transaction metadata, e.g. import, api)'
1446
1729
  },
1447
1730
  sourcePlatform: {
1448
1731
  type: 'string',
@@ -1522,7 +1805,20 @@ export const $ResolveReviewDto = {
1522
1805
  action: {
1523
1806
  type: 'string',
1524
1807
  description:
1525
- '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',
1808
+ 'Decision action. Valid actions vary by review type — see DecisionOptionDto.value returned by the review detail endpoint.',
1809
+ enum: [
1810
+ 'UPGRADE_REPLACE',
1811
+ 'LINK_KEEP_BOTH',
1812
+ 'IGNORE_NEW',
1813
+ 'CONFIRM_DIFFERENT',
1814
+ 'ACCEPT',
1815
+ 'REJECT',
1816
+ 'ACCEPT_AND_LEARN',
1817
+ 'CHOOSE_OTHER',
1818
+ 'CANCEL',
1819
+ 'FIX',
1820
+ 'IGNORE'
1821
+ ],
1526
1822
  example: 'ACCEPT'
1527
1823
  },
1528
1824
  data: {
@@ -1559,7 +1855,8 @@ export const $ResolveResultDto = {
1559
1855
  },
1560
1856
  resolutionId: {
1561
1857
  type: 'string',
1562
- description: 'Resolution ID for undo'
1858
+ description:
1859
+ 'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
1563
1860
  },
1564
1861
  canUndo: {
1565
1862
  type: 'boolean',
@@ -1577,7 +1874,7 @@ export const $ResolveResultDto = {
1577
1874
  example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
1578
1875
  }
1579
1876
  },
1580
- required: ['success', 'resolutionId', 'canUndo', 'undoDeadline']
1877
+ required: ['success']
1581
1878
  } as const;
1582
1879
 
1583
1880
  export const $UndoResultDto = {
@@ -1613,6 +1910,19 @@ export const $BatchResolveDto = {
1613
1910
  action: {
1614
1911
  type: 'string',
1615
1912
  description: 'Decision action to apply to all items',
1913
+ enum: [
1914
+ 'UPGRADE_REPLACE',
1915
+ 'LINK_KEEP_BOTH',
1916
+ 'IGNORE_NEW',
1917
+ 'CONFIRM_DIFFERENT',
1918
+ 'ACCEPT',
1919
+ 'REJECT',
1920
+ 'ACCEPT_AND_LEARN',
1921
+ 'CHOOSE_OTHER',
1922
+ 'CANCEL',
1923
+ 'FIX',
1924
+ 'IGNORE'
1925
+ ],
1616
1926
  example: 'ACCEPT'
1617
1927
  },
1618
1928
  data: {
@@ -4002,45 +4312,183 @@ export const $UpdatePropertyDto = {
4002
4312
  required: ['value']
4003
4313
  } as const;
4004
4314
 
4005
- export const $FileImportDto = {
4315
+ export const $CreateBeanEventDto = {
4006
4316
  type: 'object',
4007
4317
  properties: {
4008
- file: {
4318
+ date: {
4009
4319
  type: 'string',
4010
- format: 'binary',
4011
- description: 'Bill file to import (CSV, PDF, OFX, etc.)',
4012
- example: 'alipay.csv'
4013
- }
4014
- },
4015
- required: ['file']
4016
- } as const;
4017
-
4018
- export const $ImportErrorDto = {
4019
- type: 'object',
4020
- properties: {
4021
- index: {
4022
- type: 'number',
4023
- description: 'Index of failed transaction in the file',
4024
- example: 5
4320
+ description: 'Life event date (ISO 8601)',
4321
+ example: '2024-03-15'
4025
4322
  },
4026
- error: {
4323
+ type: {
4027
4324
  type: 'string',
4028
- description: 'Error message',
4029
- example: 'Transaction does not balance: -100 USD != 0'
4325
+ description:
4326
+ 'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
4327
+ example: 'employer'
4328
+ },
4329
+ description: {
4330
+ type: 'string',
4331
+ description:
4332
+ 'Life event description. Empty string is a VALID value (distinct from absence).',
4333
+ example: 'Acme Corp'
4334
+ },
4335
+ meta: {
4336
+ type: 'object',
4337
+ description:
4338
+ 'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
4339
+ example: {
4340
+ note: 'Promotion'
4341
+ }
4030
4342
  }
4031
4343
  },
4032
- required: ['index', 'error']
4344
+ required: ['date', 'type', 'description']
4033
4345
  } as const;
4034
4346
 
4035
- export const $ReviewItemPreviewDto = {
4347
+ export const $EventResponseDto = {
4036
4348
  type: 'object',
4037
4349
  properties: {
4038
- index: {
4039
- type: 'number',
4040
- description: 'Index in the import batch (for tracking)',
4041
- example: 0
4042
- },
4043
- date: {
4350
+ id: {
4351
+ type: 'string',
4352
+ description: 'Unique identifier',
4353
+ example: 'uuid-123-456'
4354
+ },
4355
+ userId: {
4356
+ type: 'string',
4357
+ description: 'User ID (owner of the life event)',
4358
+ example: 'user-123'
4359
+ },
4360
+ date: {
4361
+ type: 'string',
4362
+ description: 'Life event date (ISO 8601 format)',
4363
+ example: '2024-03-15',
4364
+ format: 'date'
4365
+ },
4366
+ type: {
4367
+ type: 'string',
4368
+ description:
4369
+ 'Life event type (user-defined, e.g., "employer", "location")',
4370
+ example: 'employer'
4371
+ },
4372
+ description: {
4373
+ type: 'string',
4374
+ description:
4375
+ 'Life event description. May be an empty string (a valid value distinct from absence).',
4376
+ example: 'Acme Corp'
4377
+ },
4378
+ meta: {
4379
+ type: 'object',
4380
+ description: 'Product-side metadata (free-form JSON)',
4381
+ example: {
4382
+ note: 'Promotion'
4383
+ }
4384
+ },
4385
+ createdAt: {
4386
+ format: 'date-time',
4387
+ type: 'string',
4388
+ description: 'Creation timestamp',
4389
+ example: '2024-03-15T10:00:00Z'
4390
+ },
4391
+ updatedAt: {
4392
+ format: 'date-time',
4393
+ type: 'string',
4394
+ description:
4395
+ 'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
4396
+ example: '2024-03-15T10:00:00Z'
4397
+ }
4398
+ },
4399
+ required: [
4400
+ 'id',
4401
+ 'userId',
4402
+ 'date',
4403
+ 'type',
4404
+ 'description',
4405
+ 'meta',
4406
+ 'createdAt',
4407
+ 'updatedAt'
4408
+ ]
4409
+ } as const;
4410
+
4411
+ export const $EventListResponseDto = {
4412
+ type: 'object',
4413
+ properties: {
4414
+ items: {
4415
+ description: 'List of life events',
4416
+ type: 'array',
4417
+ items: {
4418
+ $ref: '#/components/schemas/EventResponseDto'
4419
+ }
4420
+ },
4421
+ total: {
4422
+ type: 'number',
4423
+ description: 'Total number of life events matching the query',
4424
+ example: 42
4425
+ }
4426
+ },
4427
+ required: ['items', 'total']
4428
+ } as const;
4429
+
4430
+ export const $UpdateBeanEventDto = {
4431
+ type: 'object',
4432
+ properties: {
4433
+ date: {
4434
+ type: 'string',
4435
+ description: 'Life event date (ISO 8601)'
4436
+ },
4437
+ type: {
4438
+ type: 'string',
4439
+ description: 'Life event type (user-defined)'
4440
+ },
4441
+ description: {
4442
+ type: 'string',
4443
+ description:
4444
+ 'Life event description. Empty string is a VALID value (distinct from absence).'
4445
+ },
4446
+ meta: {
4447
+ type: 'object',
4448
+ description: 'Product-side metadata (free-form JSON)'
4449
+ }
4450
+ }
4451
+ } as const;
4452
+
4453
+ export const $FileImportDto = {
4454
+ type: 'object',
4455
+ properties: {
4456
+ file: {
4457
+ type: 'string',
4458
+ format: 'binary',
4459
+ description: 'Bill file to import (CSV, PDF, OFX, etc.)',
4460
+ example: 'alipay.csv'
4461
+ }
4462
+ },
4463
+ required: ['file']
4464
+ } as const;
4465
+
4466
+ export const $ImportErrorDto = {
4467
+ type: 'object',
4468
+ properties: {
4469
+ index: {
4470
+ type: 'number',
4471
+ description: 'Index of failed transaction in the file',
4472
+ example: 5
4473
+ },
4474
+ error: {
4475
+ type: 'string',
4476
+ description: 'Error message',
4477
+ example: 'Transaction does not balance: -100 USD != 0'
4478
+ }
4479
+ },
4480
+ required: ['index', 'error']
4481
+ } as const;
4482
+
4483
+ export const $ReviewItemPreviewDto = {
4484
+ type: 'object',
4485
+ properties: {
4486
+ index: {
4487
+ type: 'number',
4488
+ description: 'Index in the import batch (for tracking)',
4489
+ example: 0
4490
+ },
4491
+ date: {
4044
4492
  type: 'string',
4045
4493
  description: 'Transaction date (ISO format)',
4046
4494
  example: '2026-03-05'
@@ -4674,6 +5122,11 @@ export const $ParserTelemetryReportDto = {
4674
5122
  properties: {}
4675
5123
  } as const;
4676
5124
 
5125
+ export const $UncoveredFormatMissDto = {
5126
+ type: 'object',
5127
+ properties: {}
5128
+ } as const;
5129
+
4677
5130
  export const $ProcessNlpDto = {
4678
5131
  type: 'object',
4679
5132
  properties: {
@@ -4688,6 +5141,16 @@ export const $ProcessNlpDto = {
4688
5141
  description:
4689
5142
  'Session ID for multi-turn conversation (auto-generated if not provided)',
4690
5143
  example: 'session_abc123'
5144
+ },
5145
+ parsedData: {
5146
+ type: 'object',
5147
+ description:
5148
+ 'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
5149
+ example: {
5150
+ amount: 35,
5151
+ currency: 'CNY',
5152
+ payee: 'Starbucks'
5153
+ }
4691
5154
  }
4692
5155
  },
4693
5156
  required: ['message']
@@ -5701,11 +6164,66 @@ export const $PlatformGroupDto = {
5701
6164
  },
5702
6165
  totalBalance: {
5703
6166
  type: 'string',
5704
- description: 'Total balance across all accounts in platform',
6167
+ description: 'FX-converted total balance in base currency',
6168
+ example: '100000.00'
6169
+ },
6170
+ balanceByCurrency: {
6171
+ description: 'Raw (unconverted) balances grouped by currency',
6172
+ type: 'array',
6173
+ items: {
6174
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
6175
+ }
6176
+ },
6177
+ convertedBalance: {
6178
+ type: 'string',
6179
+ description:
6180
+ 'Converted balance in base currency (omitted when no currency is convertible)',
5705
6181
  example: '100000.00'
6182
+ },
6183
+ sharePct: {
6184
+ type: 'number',
6185
+ description:
6186
+ 'Share of the grand converted total (0-100); 0 when grand total is 0',
6187
+ example: 42.5
6188
+ }
6189
+ },
6190
+ required: [
6191
+ 'platformId',
6192
+ 'platformName',
6193
+ 'accounts',
6194
+ 'totalBalance',
6195
+ 'balanceByCurrency',
6196
+ 'sharePct'
6197
+ ]
6198
+ } as const;
6199
+
6200
+ export const $AccountExchangeRateWarningDto = {
6201
+ type: 'object',
6202
+ properties: {
6203
+ type: {
6204
+ type: 'string',
6205
+ description: 'Warning type',
6206
+ example: 'MISSING_EXCHANGE_RATE'
6207
+ },
6208
+ currency: {
6209
+ type: 'string',
6210
+ description: 'Currency without exchange rate',
6211
+ example: 'USD'
6212
+ },
6213
+ accounts: {
6214
+ description: 'Affected account paths',
6215
+ type: 'array',
6216
+ items: {
6217
+ type: 'string'
6218
+ }
6219
+ },
6220
+ totalAmount: {
6221
+ type: 'string',
6222
+ description: 'Total amount in this currency',
6223
+ example: '5000.00'
5706
6224
  }
5707
6225
  },
5708
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
6226
+ required: ['type', 'currency', 'accounts', 'totalAmount']
5709
6227
  } as const;
5710
6228
 
5711
6229
  export const $AccountsSummaryDto = {
@@ -5718,9 +6236,21 @@ export const $AccountsSummaryDto = {
5718
6236
  totalPlatforms: {
5719
6237
  type: 'number',
5720
6238
  description: 'Total number of platforms'
6239
+ },
6240
+ baseCurrency: {
6241
+ type: 'string',
6242
+ description: 'Base currency for conversion',
6243
+ example: 'CNY'
6244
+ },
6245
+ warnings: {
6246
+ description: 'Per-account exchange rate warnings',
6247
+ type: 'array',
6248
+ items: {
6249
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
6250
+ }
5721
6251
  }
5722
6252
  },
5723
- required: ['totalAccounts', 'totalPlatforms']
6253
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
5724
6254
  } as const;
5725
6255
 
5726
6256
  export const $AccountsResponseDto = {
@@ -5791,6 +6321,12 @@ export const $AccountItemWithAssetClassDto = {
5791
6321
  type: 'string',
5792
6322
  description: 'Risk level',
5793
6323
  example: 'LOW'
6324
+ },
6325
+ source: {
6326
+ type: 'string',
6327
+ description:
6328
+ 'ADR-0105 classification provenance (holding level always; account level only on FALLBACK)',
6329
+ enum: ['USER_META', 'FIAT_CURRENCY', 'OPENBB_MAPPING', 'FALLBACK']
5794
6330
  }
5795
6331
  },
5796
6332
  required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
@@ -5845,35 +6381,6 @@ export const $AssetClassGroupDto = {
5845
6381
  required: ['assetClass', 'accounts', 'balanceByCurrency']
5846
6382
  } as const;
5847
6383
 
5848
- export const $AccountExchangeRateWarningDto = {
5849
- type: 'object',
5850
- properties: {
5851
- type: {
5852
- type: 'string',
5853
- description: 'Warning type',
5854
- example: 'MISSING_EXCHANGE_RATE'
5855
- },
5856
- currency: {
5857
- type: 'string',
5858
- description: 'Currency without exchange rate',
5859
- example: 'USD'
5860
- },
5861
- accounts: {
5862
- description: 'Affected account paths',
5863
- type: 'array',
5864
- items: {
5865
- type: 'string'
5866
- }
5867
- },
5868
- totalAmount: {
5869
- type: 'string',
5870
- description: 'Total amount in this currency',
5871
- example: '5000.00'
5872
- }
5873
- },
5874
- required: ['type', 'currency', 'accounts', 'totalAmount']
5875
- } as const;
5876
-
5877
6384
  export const $AssetClassSummaryDto = {
5878
6385
  type: 'object',
5879
6386
  properties: {
@@ -5896,6 +6403,11 @@ export const $AssetClassSummaryDto = {
5896
6403
  items: {
5897
6404
  $ref: '#/components/schemas/AccountExchangeRateWarningDto'
5898
6405
  }
6406
+ },
6407
+ fallback: {
6408
+ type: 'object',
6409
+ description:
6410
+ '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.'
5899
6411
  }
5900
6412
  },
5901
6413
  required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
@@ -5918,29 +6430,125 @@ export const $AssetClassAccountsResponseDto = {
5918
6430
  $ref: '#/components/schemas/AssetClassSummaryDto'
5919
6431
  }
5920
6432
  ]
6433
+ },
6434
+ uncategorized: {
6435
+ description:
6436
+ 'ADR-0105 §6 holding-level grey-area bucket (source=FALLBACK holdings peeled out of groups). Present only for groupBy=holdingAssetClass when FALLBACK holdings exist.',
6437
+ allOf: [
6438
+ {
6439
+ $ref: '#/components/schemas/AssetClassGroupDto'
6440
+ }
6441
+ ]
5921
6442
  }
5922
6443
  },
5923
6444
  required: ['groups', 'summary']
5924
6445
  } as const;
5925
6446
 
5926
- export const $CashFlowByCurrencyDto = {
6447
+ export const $HoldingAssetClassAccountSliceDto = {
5927
6448
  type: 'object',
5928
6449
  properties: {
5929
- income: {
5930
- description: 'Income by currency',
5931
- type: 'array',
5932
- items: {
5933
- $ref: '#/components/schemas/BalanceByCurrencyDto'
5934
- }
6450
+ accountId: {
6451
+ type: 'string',
6452
+ description: 'Account ID'
5935
6453
  },
5936
- expense: {
5937
- description: 'Expense by currency',
6454
+ accountPath: {
6455
+ type: 'string',
6456
+ description: 'Full account path',
6457
+ example: 'Assets:US:Investments:Brokerage'
6458
+ },
6459
+ accountCurrency: {
6460
+ type: 'string',
6461
+ description:
6462
+ 'Currency of the holding with the largest converted base value; undefined when no holding is convertible',
6463
+ example: 'USD'
6464
+ },
6465
+ marketValueBase: {
6466
+ type: 'string',
6467
+ description:
6468
+ "Account's market value in base currency (Σ converted holdings; grey bucket included)",
6469
+ example: '50000.00'
6470
+ },
6471
+ shareOfTotalPct: {
6472
+ type: 'number',
6473
+ description:
6474
+ 'Share of the global total (0-100). 0 when globalTotal is zero (no NaN/Infinity).',
6475
+ example: 42.5
6476
+ },
6477
+ groups: {
6478
+ description: 'Per-account asset-class breakdown',
5938
6479
  type: 'array',
5939
6480
  items: {
5940
- $ref: '#/components/schemas/BalanceByCurrencyDto'
6481
+ $ref: '#/components/schemas/AssetClassGroupDto'
5941
6482
  }
5942
6483
  },
5943
- netSavings: {
6484
+ uncategorized: {
6485
+ description:
6486
+ 'Per-account grey bucket (source=FALLBACK holdings, incl. broker cash)',
6487
+ allOf: [
6488
+ {
6489
+ $ref: '#/components/schemas/AssetClassGroupDto'
6490
+ }
6491
+ ]
6492
+ },
6493
+ holdings: {
6494
+ description:
6495
+ 'Every holding row for this account (account ID in each row’s `id` field)',
6496
+ type: 'array',
6497
+ items: {
6498
+ $ref: '#/components/schemas/AccountItemWithAssetClassDto'
6499
+ }
6500
+ }
6501
+ },
6502
+ required: [
6503
+ 'accountId',
6504
+ 'accountPath',
6505
+ 'marketValueBase',
6506
+ 'shareOfTotalPct',
6507
+ 'groups',
6508
+ 'holdings'
6509
+ ]
6510
+ } as const;
6511
+
6512
+ export const $HoldingAssetClassCrossAccountResponseDto = {
6513
+ type: 'object',
6514
+ properties: {
6515
+ global: {
6516
+ description: 'Merged cross-account holding aggregation',
6517
+ allOf: [
6518
+ {
6519
+ $ref: '#/components/schemas/AssetClassAccountsResponseDto'
6520
+ }
6521
+ ]
6522
+ },
6523
+ byAccount: {
6524
+ description: 'Per-account slices',
6525
+ type: 'array',
6526
+ items: {
6527
+ $ref: '#/components/schemas/HoldingAssetClassAccountSliceDto'
6528
+ }
6529
+ }
6530
+ },
6531
+ required: ['global', 'byAccount']
6532
+ } as const;
6533
+
6534
+ export const $CashFlowByCurrencyDto = {
6535
+ type: 'object',
6536
+ properties: {
6537
+ income: {
6538
+ description: 'Income by currency',
6539
+ type: 'array',
6540
+ items: {
6541
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
6542
+ }
6543
+ },
6544
+ expense: {
6545
+ description: 'Expense by currency',
6546
+ type: 'array',
6547
+ items: {
6548
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
6549
+ }
6550
+ },
6551
+ netSavings: {
5944
6552
  description: 'Net savings by currency',
5945
6553
  type: 'array',
5946
6554
  items: {
@@ -6052,6 +6660,547 @@ export const $CashFlowResponseDto = {
6052
6660
  ]
6053
6661
  } as const;
6054
6662
 
6663
+ export const $CategoryGroupDto = {
6664
+ type: 'object',
6665
+ properties: {
6666
+ category: {
6667
+ type: 'string',
6668
+ description:
6669
+ 'Functional category (account-path Group segment); regional and universal account paths merge under it',
6670
+ example: 'Food'
6671
+ },
6672
+ totalExpense: {
6673
+ type: 'string',
6674
+ description:
6675
+ 'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
6676
+ example: '1200.00'
6677
+ },
6678
+ sharePct: {
6679
+ type: 'number',
6680
+ description: 'Share of grand total (0-100); 0 when grand total is 0',
6681
+ example: 42.5
6682
+ },
6683
+ balanceByCurrency: {
6684
+ description: 'Raw (unconverted) expense per currency',
6685
+ type: 'array',
6686
+ items: {
6687
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
6688
+ }
6689
+ },
6690
+ convertedBalance: {
6691
+ type: 'string',
6692
+ description:
6693
+ 'Converted total in base currency (omitted when FX missing for all currencies in this category)',
6694
+ example: '1200.00'
6695
+ }
6696
+ },
6697
+ required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
6698
+ } as const;
6699
+
6700
+ export const $ExpensesByCategorySummaryDto = {
6701
+ type: 'object',
6702
+ properties: {
6703
+ totalExpense: {
6704
+ type: 'string',
6705
+ description:
6706
+ 'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
6707
+ example: '5000.00'
6708
+ },
6709
+ categoryCount: {
6710
+ type: 'number',
6711
+ description: 'Number of categories',
6712
+ example: 8
6713
+ }
6714
+ },
6715
+ required: ['totalExpense', 'categoryCount']
6716
+ } as const;
6717
+
6718
+ export const $ExpensesByCategoryResponseDto = {
6719
+ type: 'object',
6720
+ properties: {
6721
+ period: {
6722
+ type: 'string',
6723
+ description: 'Period requested',
6724
+ example: '1m'
6725
+ },
6726
+ baseCurrency: {
6727
+ type: 'string',
6728
+ description: 'Base currency for converted values',
6729
+ example: 'CNY'
6730
+ },
6731
+ groups: {
6732
+ description:
6733
+ 'Expense groups by functional category, sorted by converted total desc',
6734
+ type: 'array',
6735
+ items: {
6736
+ $ref: '#/components/schemas/CategoryGroupDto'
6737
+ }
6738
+ },
6739
+ summary: {
6740
+ description: 'Summary statistics',
6741
+ allOf: [
6742
+ {
6743
+ $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
6744
+ }
6745
+ ]
6746
+ },
6747
+ warnings: {
6748
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
6749
+ type: 'array',
6750
+ items: {
6751
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
6752
+ }
6753
+ }
6754
+ },
6755
+ required: ['period', 'baseCurrency', 'groups', 'summary']
6756
+ } as const;
6757
+
6758
+ export const $MonetaryDto = {
6759
+ type: 'object',
6760
+ properties: {
6761
+ amount: {
6762
+ type: 'string',
6763
+ description: 'Amount (Decimal string)',
6764
+ example: '3000'
6765
+ },
6766
+ currency: {
6767
+ type: 'string',
6768
+ description: 'ISO 4217 currency',
6769
+ example: 'USD'
6770
+ },
6771
+ baseCcyEquivalent: {
6772
+ type: 'object',
6773
+ description: 'Converted to user base currency (Decimal string)',
6774
+ example: '21600',
6775
+ nullable: true
6776
+ }
6777
+ },
6778
+ required: ['amount', 'currency']
6779
+ } as const;
6780
+
6781
+ export const $CurrentPriceDto = {
6782
+ type: 'object',
6783
+ properties: {
6784
+ amount: {
6785
+ type: 'string',
6786
+ description: 'Price amount (Decimal string)',
6787
+ example: '250'
6788
+ },
6789
+ currency: {
6790
+ type: 'string',
6791
+ description: 'Price currency (ISO 4217)',
6792
+ example: 'USD'
6793
+ },
6794
+ date: {
6795
+ type: 'string',
6796
+ description: 'Price date (ISO 8601)',
6797
+ example: '2024-06-01'
6798
+ },
6799
+ source: {
6800
+ type: 'string',
6801
+ description: 'Price source',
6802
+ example: 'USER_OVERRIDE',
6803
+ enum: ['USER_OVERRIDE', 'OPENBB_EQUITY', 'OPENBB_CURRENCY']
6804
+ }
6805
+ },
6806
+ required: ['amount', 'currency', 'date', 'source']
6807
+ } as const;
6808
+
6809
+ export const $FxRateDto = {
6810
+ type: 'object',
6811
+ properties: {
6812
+ from: {
6813
+ type: 'string',
6814
+ example: 'USD'
6815
+ },
6816
+ to: {
6817
+ type: 'string',
6818
+ example: 'CNY'
6819
+ },
6820
+ rate: {
6821
+ type: 'string',
6822
+ description: 'FX rate (Decimal string)',
6823
+ example: '7.2'
6824
+ },
6825
+ date: {
6826
+ type: 'string',
6827
+ description: 'Rate date (ISO 8601)',
6828
+ example: '2024-01-15'
6829
+ }
6830
+ },
6831
+ required: ['from', 'to', 'rate', 'date']
6832
+ } as const;
6833
+
6834
+ export const $HoldingPnlRowDto = {
6835
+ type: 'object',
6836
+ properties: {
6837
+ accountId: {
6838
+ type: 'string',
6839
+ description: 'Account UUID',
6840
+ example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
6841
+ },
6842
+ accountPath: {
6843
+ type: 'string',
6844
+ description: 'Full account path',
6845
+ example: 'Assets:US:Broker:AAPL'
6846
+ },
6847
+ accountCcy: {
6848
+ type: 'object',
6849
+ description: 'Account settlement currency (ISO 4217), from cost currency',
6850
+ nullable: true,
6851
+ example: 'USD'
6852
+ },
6853
+ brokerType: {
6854
+ type: 'object',
6855
+ description: 'Broker type derived from Platform.type',
6856
+ nullable: true,
6857
+ example: 'broker'
6858
+ },
6859
+ symbol: {
6860
+ type: 'string',
6861
+ description: 'Commodity symbol',
6862
+ example: 'AAPL'
6863
+ },
6864
+ chartToken: {
6865
+ type: 'string',
6866
+ description: 'Chart segment token (libs/common resolver)',
6867
+ example: 'equity',
6868
+ enum: ['equity', 'fund', 'bond', 'cash', 'other']
6869
+ },
6870
+ assetClass: {
6871
+ type: 'string',
6872
+ example: 'EQUITY'
6873
+ },
6874
+ assetSubClass: {
6875
+ type: 'object',
6876
+ nullable: true,
6877
+ example: 'STOCK'
6878
+ },
6879
+ units: {
6880
+ type: 'string',
6881
+ description: 'Net held units (Decimal string)',
6882
+ example: '12'
6883
+ },
6884
+ averageCostPerUnit: {
6885
+ description:
6886
+ 'Average cost per unit; null when cost currency conflicts or no cost',
6887
+ nullable: true,
6888
+ allOf: [
6889
+ {
6890
+ $ref: '#/components/schemas/MonetaryDto'
6891
+ }
6892
+ ]
6893
+ },
6894
+ costBasis: {
6895
+ description: 'Cost basis of held units',
6896
+ nullable: true,
6897
+ allOf: [
6898
+ {
6899
+ $ref: '#/components/schemas/MonetaryDto'
6900
+ }
6901
+ ]
6902
+ },
6903
+ marketValue: {
6904
+ description: 'Market value at asOf price',
6905
+ nullable: true,
6906
+ allOf: [
6907
+ {
6908
+ $ref: '#/components/schemas/MonetaryDto'
6909
+ }
6910
+ ]
6911
+ },
6912
+ currentPrice: {
6913
+ description: 'Price used for market value',
6914
+ nullable: true,
6915
+ allOf: [
6916
+ {
6917
+ $ref: '#/components/schemas/CurrentPriceDto'
6918
+ }
6919
+ ]
6920
+ },
6921
+ unrealizedPnlBase: {
6922
+ type: 'object',
6923
+ description:
6924
+ 'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
6925
+ nullable: true,
6926
+ example: '6000'
6927
+ },
6928
+ unrealizedPnlPct: {
6929
+ type: 'object',
6930
+ description: 'Unrealized P&L % (Decimal string)',
6931
+ nullable: true,
6932
+ example: '25'
6933
+ },
6934
+ costFxRate: {
6935
+ description: 'Historical FX rate applied to cost basis',
6936
+ nullable: true,
6937
+ allOf: [
6938
+ {
6939
+ $ref: '#/components/schemas/FxRateDto'
6940
+ }
6941
+ ]
6942
+ },
6943
+ marketFxRate: {
6944
+ description: 'FX rate applied to market value',
6945
+ nullable: true,
6946
+ allOf: [
6947
+ {
6948
+ $ref: '#/components/schemas/FxRateDto'
6949
+ }
6950
+ ]
6951
+ },
6952
+ pctOfInvestedAssets: {
6953
+ type: 'object',
6954
+ description:
6955
+ 'Share of invested assets % (Decimal string); only for invested chartTokens',
6956
+ nullable: true,
6957
+ example: '40'
6958
+ },
6959
+ realizedPnl: {
6960
+ description:
6961
+ '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',
6962
+ nullable: true,
6963
+ allOf: [
6964
+ {
6965
+ $ref: '#/components/schemas/MonetaryDto'
6966
+ }
6967
+ ]
6968
+ }
6969
+ },
6970
+ required: [
6971
+ 'accountId',
6972
+ 'accountPath',
6973
+ 'symbol',
6974
+ 'chartToken',
6975
+ 'assetClass',
6976
+ 'units'
6977
+ ]
6978
+ } as const;
6979
+
6980
+ export const $HoldingPnlWarningDto = {
6981
+ type: 'object',
6982
+ properties: {
6983
+ type: {
6984
+ type: 'string',
6985
+ description: 'Warning type',
6986
+ example: 'MISSING_COST_FX_RATE',
6987
+ enum: [
6988
+ 'MISSING_COST_FX_RATE',
6989
+ 'MISSING_MARKET_FX_RATE',
6990
+ 'MISSING_SALE_PRICE',
6991
+ 'MISSING_REALIZED_FX_RATE',
6992
+ 'OVERSOLD_LOTS',
6993
+ 'NO_PRICE',
6994
+ 'MIXED_COST_CURRENCY'
6995
+ ]
6996
+ },
6997
+ symbol: {
6998
+ type: 'object',
6999
+ nullable: true
7000
+ },
7001
+ accountId: {
7002
+ type: 'object',
7003
+ nullable: true
7004
+ },
7005
+ currency: {
7006
+ type: 'object',
7007
+ nullable: true
7008
+ }
7009
+ },
7010
+ required: ['type']
7011
+ } as const;
7012
+
7013
+ export const $HoldingPnlResponseDto = {
7014
+ type: 'object',
7015
+ properties: {
7016
+ asOfDate: {
7017
+ type: 'string',
7018
+ example: '2026-07-08'
7019
+ },
7020
+ baseCurrency: {
7021
+ type: 'string',
7022
+ example: 'CNY'
7023
+ },
7024
+ method: {
7025
+ type: 'string',
7026
+ description:
7027
+ 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
7028
+ enum: ['average', 'FIFO'],
7029
+ example: 'average'
7030
+ },
7031
+ rows: {
7032
+ type: 'array',
7033
+ items: {
7034
+ $ref: '#/components/schemas/HoldingPnlRowDto'
7035
+ }
7036
+ },
7037
+ warnings: {
7038
+ type: 'array',
7039
+ items: {
7040
+ $ref: '#/components/schemas/HoldingPnlWarningDto'
7041
+ }
7042
+ }
7043
+ },
7044
+ required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
7045
+ } as const;
7046
+
7047
+ export const $CreateBeanPriceDto = {
7048
+ type: 'object',
7049
+ properties: {
7050
+ currency: {
7051
+ type: 'string',
7052
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
7053
+ example: 'USD'
7054
+ },
7055
+ quoteCurrency: {
7056
+ type: 'string',
7057
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
7058
+ example: 'CNY'
7059
+ },
7060
+ amount: {
7061
+ type: 'number',
7062
+ description:
7063
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
7064
+ example: 175.5,
7065
+ minimum: 0
7066
+ },
7067
+ date: {
7068
+ type: 'string',
7069
+ description: 'Price date (ISO 8601 format)',
7070
+ example: '2024-11-05'
7071
+ },
7072
+ metadata: {
7073
+ type: 'object',
7074
+ description:
7075
+ 'Metadata (validated by Zod schema, max field lengths enforced)',
7076
+ example: {
7077
+ source: 'MANUAL',
7078
+ note: 'Bank valuation report',
7079
+ confidence: 0.95
7080
+ }
7081
+ }
7082
+ },
7083
+ required: ['currency', 'quoteCurrency', 'amount', 'date']
7084
+ } as const;
7085
+
7086
+ export const $PriceResponseDto = {
7087
+ type: 'object',
7088
+ properties: {
7089
+ id: {
7090
+ type: 'string',
7091
+ description: 'Unique identifier',
7092
+ example: 'uuid-123-456'
7093
+ },
7094
+ userId: {
7095
+ type: 'string',
7096
+ description: 'User ID (owner of the price)',
7097
+ example: 'user-123'
7098
+ },
7099
+ currency: {
7100
+ type: 'string',
7101
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
7102
+ example: 'BTC'
7103
+ },
7104
+ quoteCurrency: {
7105
+ type: 'string',
7106
+ description: 'Quote currency (pricing currency, e.g., USD, CNY)',
7107
+ example: 'USD'
7108
+ },
7109
+ amount: {
7110
+ type: 'number',
7111
+ description:
7112
+ 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
7113
+ example: 50000
7114
+ },
7115
+ date: {
7116
+ type: 'string',
7117
+ description:
7118
+ 'Price date (ISO 8601 format). Represents the date this price was valid.',
7119
+ example: '2024-01-01',
7120
+ format: 'date'
7121
+ },
7122
+ meta: {
7123
+ type: 'object',
7124
+ description:
7125
+ 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
7126
+ example: {
7127
+ source: 'MANUAL',
7128
+ note: 'User-defined price',
7129
+ confidence: 1
7130
+ }
7131
+ },
7132
+ createdAt: {
7133
+ format: 'date-time',
7134
+ type: 'string',
7135
+ description: 'Creation timestamp',
7136
+ example: '2024-11-03T10:00:00Z'
7137
+ },
7138
+ updatedAt: {
7139
+ format: 'date-time',
7140
+ type: 'string',
7141
+ description: 'Last update timestamp',
7142
+ example: '2024-11-03T10:00:00Z'
7143
+ }
7144
+ },
7145
+ required: [
7146
+ 'id',
7147
+ 'userId',
7148
+ 'currency',
7149
+ 'quoteCurrency',
7150
+ 'amount',
7151
+ 'date',
7152
+ 'meta',
7153
+ 'createdAt',
7154
+ 'updatedAt'
7155
+ ]
7156
+ } as const;
7157
+
7158
+ export const $PriceListResponseDto = {
7159
+ type: 'object',
7160
+ properties: {
7161
+ items: {
7162
+ description: 'List of prices',
7163
+ type: 'array',
7164
+ items: {
7165
+ $ref: '#/components/schemas/PriceResponseDto'
7166
+ }
7167
+ },
7168
+ total: {
7169
+ type: 'number',
7170
+ description: 'Total number of prices',
7171
+ example: 42
7172
+ }
7173
+ },
7174
+ required: ['items', 'total']
7175
+ } as const;
7176
+
7177
+ export const $UpdateBeanPriceDto = {
7178
+ type: 'object',
7179
+ properties: {
7180
+ currency: {
7181
+ type: 'string',
7182
+ description: 'Currency being priced'
7183
+ },
7184
+ quoteCurrency: {
7185
+ type: 'string',
7186
+ description: 'Quote currency (pricing currency)'
7187
+ },
7188
+ amount: {
7189
+ type: 'number',
7190
+ description: 'Price amount (MUST be >= 0 per Beancount spec)',
7191
+ minimum: 0
7192
+ },
7193
+ date: {
7194
+ type: 'string',
7195
+ description: 'Price date (ISO 8601 format)'
7196
+ },
7197
+ metadata: {
7198
+ type: 'object',
7199
+ description: 'Metadata'
7200
+ }
7201
+ }
7202
+ } as const;
7203
+
6055
7204
  export const $CurrencyBalanceDto = {
6056
7205
  type: 'object',
6057
7206
  properties: {
@@ -6087,6 +7236,16 @@ export const $TimeSeriesPointDto = {
6087
7236
  description: 'Change from previous point',
6088
7237
  example: '5000.00'
6089
7238
  },
7239
+ assets: {
7240
+ type: 'string',
7241
+ description: 'Total assets at this date (in base currency)',
7242
+ example: '494338.00'
7243
+ },
7244
+ liabilities: {
7245
+ type: 'string',
7246
+ description: 'Total liabilities at this date (in base currency)',
7247
+ example: '310098.00'
7248
+ },
6090
7249
  byCurrency: {
6091
7250
  description: 'Multi-currency breakdown for this point',
6092
7251
  type: 'array',
@@ -6196,6 +7355,111 @@ export const $PortfolioTrendsResponseDto = {
6196
7355
  required: ['series', 'summary', 'period', 'granularity', 'currency']
6197
7356
  } as const;
6198
7357
 
7358
+ export const $CashFlowPointDto = {
7359
+ type: 'object',
7360
+ properties: {
7361
+ month: {
7362
+ type: 'string',
7363
+ description: 'Month key (YYYY-MM)',
7364
+ example: '2024-03'
7365
+ },
7366
+ income: {
7367
+ type: 'string',
7368
+ description: 'Income in base currency (absolute, converted)',
7369
+ example: '10000.00'
7370
+ },
7371
+ expense: {
7372
+ type: 'string',
7373
+ description: 'Expense in base currency (absolute, converted)',
7374
+ example: '5000.00'
7375
+ },
7376
+ netSavings: {
7377
+ type: 'string',
7378
+ description: 'netSavings = income − expense (savings positive)',
7379
+ example: '5000.00'
7380
+ }
7381
+ },
7382
+ required: ['month', 'income', 'expense', 'netSavings']
7383
+ } as const;
7384
+
7385
+ export const $CashFlowTrendSummaryDto = {
7386
+ type: 'object',
7387
+ properties: {
7388
+ totalIncome: {
7389
+ type: 'string',
7390
+ description: 'Total income across the period',
7391
+ example: '60000.00'
7392
+ },
7393
+ totalExpense: {
7394
+ type: 'string',
7395
+ description: 'Total expense across the period',
7396
+ example: '30000.00'
7397
+ },
7398
+ totalNetSavings: {
7399
+ type: 'string',
7400
+ description: 'income − expense across the period',
7401
+ example: '30000.00'
7402
+ },
7403
+ averageMonthlyNetSavings: {
7404
+ type: 'string',
7405
+ description:
7406
+ 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
7407
+ example: '5000.00'
7408
+ }
7409
+ },
7410
+ required: [
7411
+ 'totalIncome',
7412
+ 'totalExpense',
7413
+ 'totalNetSavings',
7414
+ 'averageMonthlyNetSavings'
7415
+ ]
7416
+ } as const;
7417
+
7418
+ export const $CashFlowTrendsResponseDto = {
7419
+ type: 'object',
7420
+ properties: {
7421
+ series: {
7422
+ description:
7423
+ 'Monthly cash-flow series (fixed N-month window, zero-filled)',
7424
+ type: 'array',
7425
+ items: {
7426
+ $ref: '#/components/schemas/CashFlowPointDto'
7427
+ }
7428
+ },
7429
+ summary: {
7430
+ description: 'Period totals',
7431
+ allOf: [
7432
+ {
7433
+ $ref: '#/components/schemas/CashFlowTrendSummaryDto'
7434
+ }
7435
+ ]
7436
+ },
7437
+ period: {
7438
+ type: 'string',
7439
+ description: 'Period requested',
7440
+ example: '6m'
7441
+ },
7442
+ granularity: {
7443
+ type: 'string',
7444
+ description: 'Data granularity (v1 returns month buckets)',
7445
+ example: 'month'
7446
+ },
7447
+ currency: {
7448
+ type: 'string',
7449
+ description: 'Base currency for converted values',
7450
+ example: 'CNY'
7451
+ },
7452
+ warnings: {
7453
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
7454
+ type: 'array',
7455
+ items: {
7456
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
7457
+ }
7458
+ }
7459
+ },
7460
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
7461
+ } as const;
7462
+
6199
7463
  export const $GenerateSnapshotBody = {
6200
7464
  type: 'object',
6201
7465
  properties: {}