@firela/api-types 0.0.0-canary.411600e0 → 0.0.0-canary.4367f8bb

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/dist/index.d.mts +4272 -2844
  2. package/dist/index.d.ts +4272 -2844
  3. package/dist/index.js +33 -5
  4. package/dist/index.mjs +33 -5
  5. package/package.json +1 -1
  6. package/src/generated/schemas.gen.ts +2756 -1323
  7. package/src/generated/services.gen.ts +1375 -745
  8. package/src/generated/types.gen.ts +7465 -3159
package/src/generated/schemas.gen.ts CHANGED
@@ -6,18 +6,12 @@ export const $CreateAccountDto = {
6
6
  path: {
7
7
  type: 'string',
8
8
  description: 'Account path (hierarchical, colon-separated)',
9
- example: 'Assets:CN:Bank:ICBC:Checking'
10
- },
11
- displayName: {
12
- type: 'string',
13
- description:
14
- 'Display name to distinguish accounts at the same path (default: "")',
15
- example: '工资卡'
9
+ example: 'Assets:CN:ICBC:Checking'
16
10
  },
17
11
  openDate: {
18
12
  format: 'date-time',
19
13
  type: 'string',
20
- description: 'Account open date',
14
+ description: 'Account open date (server defaults to today)',
21
15
  example: '2024-01-01'
22
16
  },
23
17
  currencies: {
@@ -45,26 +39,22 @@ export const $CreateAccountDto = {
45
39
  templatePath: {
46
40
  type: 'string',
47
41
  description: 'Reference to account-standards template path',
48
- example: 'Assets:CN:Bank:ICBC:Checking'
42
+ example: 'Assets:CN:Checking'
49
43
  },
50
44
  isCustom: {
51
45
  type: 'boolean',
52
46
  description: 'Whether this is a custom (user-created) account',
53
47
  default: false
54
48
  },
55
- i18nKey: {
56
- type: 'string',
57
- description: 'i18n key for display name (overrides template)',
58
- example: 'account.custom.mybank'
59
- },
60
49
  icon: {
61
50
  type: 'string',
62
51
  description: 'Icon identifier (overrides template)',
63
52
  example: 'bank-custom'
64
53
  },
65
- openMeta: {
54
+ openDirectiveMeta: {
66
55
  type: 'object',
67
- description: 'Additional metadata',
56
+ description:
57
+ 'Open directive metadata (NOT an opening-balance amount — use the opening-balance endpoint)',
68
58
  example: {
69
59
  branch: 'Downtown',
70
60
  accountNumber: '1234'
@@ -76,7 +66,7 @@ export const $CreateAccountDto = {
76
66
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
77
67
  }
78
68
  },
79
- required: ['path', 'openDate']
69
+ required: ['path']
80
70
  } as const;
81
71
 
82
72
  export const $AccountResponseDto = {
@@ -90,13 +80,7 @@ export const $AccountResponseDto = {
90
80
  path: {
91
81
  type: 'string',
92
82
  description: 'Account path (hierarchical, colon-separated)',
93
- example: 'Assets:CN:Bank:ICBC:Checking'
94
- },
95
- displayName: {
96
- type: 'string',
97
- description:
98
- 'Display name distinguishing multiple accounts at the same path',
99
- example: '工资卡'
83
+ example: 'Assets:CN:ICBC:Checking'
100
84
  },
101
85
  type: {
102
86
  type: 'string',
@@ -104,6 +88,49 @@ export const $AccountResponseDto = {
104
88
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
105
89
  example: 'Assets'
106
90
  },
91
+ assetSubClass: {
92
+ type: 'string',
93
+ description:
94
+ 'Account-level asset sub-class (product type, e.g. STOCK/DEPOSIT/CREDIT_CARD/PERSONAL_LOAN). Computed from the account path via the asset-classifier (ADR-0077). Null for non-asset accounts (Income/Expenses/Equity) or unmatched paths.',
95
+ enum: [
96
+ 'DEPOSIT',
97
+ 'CASH',
98
+ 'MONEY_MARKET_FUND',
99
+ 'STOCK',
100
+ 'ETF',
101
+ 'MUTUAL_FUND',
102
+ 'EQUITY_COMPENSATION',
103
+ 'GOVERNMENT_BOND',
104
+ 'CORPORATE_BOND',
105
+ 'BOND_FUND',
106
+ 'PRIMARY_RESIDENCE',
107
+ 'INVESTMENT_PROPERTY',
108
+ 'REIT',
109
+ 'GOLD',
110
+ 'SILVER',
111
+ 'PRECIOUS_METAL',
112
+ 'PRECIOUS_METAL_FUND',
113
+ 'COMMODITY',
114
+ 'COMMODITY_FUND',
115
+ 'CRYPTOCURRENCY',
116
+ 'RETIREMENT_ACCOUNT',
117
+ 'HEALTH_ACCOUNT',
118
+ 'EDUCATION_ACCOUNT',
119
+ 'INSURANCE',
120
+ 'PRIVATE_EQUITY',
121
+ 'HEDGE_FUND',
122
+ 'COLLECTIBLES',
123
+ 'MORTGAGE',
124
+ 'STUDENT_LOAN',
125
+ 'CREDIT_CARD',
126
+ 'PERSONAL_LOAN',
127
+ 'ACCOUNTS_PAYABLE',
128
+ 'TAX_PAYABLE',
129
+ 'OTHER'
130
+ ],
131
+ nullable: true,
132
+ example: 'STOCK'
133
+ },
107
134
  status: {
108
135
  type: 'string',
109
136
  description: 'Account status',
@@ -145,26 +172,26 @@ export const $AccountResponseDto = {
145
172
  templatePath: {
146
173
  type: 'string',
147
174
  description: 'Template path reference',
148
- example: 'Assets:CN:Bank:ICBC:Checking'
175
+ example: 'Assets:CN:Checking'
149
176
  },
150
177
  isCustom: {
151
178
  type: 'boolean',
152
179
  description: 'Whether this is a custom (user-created) account',
153
180
  example: false
154
181
  },
155
- i18nKey: {
182
+ displayName: {
156
183
  type: 'string',
157
- description: 'i18n key for display name',
158
- example: 'account.assets.cn.bank.icbc.checking'
184
+ description: 'Localized display name (ADR-0114, read-time projection)',
185
+ example: 'Checking'
159
186
  },
160
187
  icon: {
161
188
  type: 'string',
162
189
  description: 'Icon identifier',
163
190
  example: 'bank-icbc'
164
191
  },
165
- openMeta: {
192
+ openDirectiveMeta: {
166
193
  type: 'object',
167
- description: 'Account metadata',
194
+ description: 'Open directive metadata (ADR-0115 Decision 9)',
168
195
  example: {
169
196
  branch: 'Downtown'
170
197
  }
@@ -192,7 +219,6 @@ export const $AccountResponseDto = {
192
219
  required: [
193
220
  'id',
194
221
  'path',
195
- 'displayName',
196
222
  'type',
197
223
  'status',
198
224
  'openDate',
@@ -225,11 +251,6 @@ export const $AccountListResponseDto = {
225
251
  export const $UpdateAccountDto = {
226
252
  type: 'object',
227
253
  properties: {
228
- displayName: {
229
- type: 'string',
230
- description: 'Display name to distinguish accounts at the same path',
231
- example: '招行工资卡'
232
- },
233
254
  currencies: {
234
255
  description: 'Allowed currencies (null = no restriction)',
235
256
  example: ['CNY', 'USD'],
@@ -251,19 +272,15 @@ export const $UpdateAccountDto = {
251
272
  'NONE'
252
273
  ]
253
274
  },
254
- i18nKey: {
255
- type: 'string',
256
- description: 'i18n key for display name',
257
- example: 'account.custom.mybank'
258
- },
259
275
  icon: {
260
276
  type: 'string',
261
277
  description: 'Icon identifier',
262
278
  example: 'bank-custom'
263
279
  },
264
- openMeta: {
280
+ openDirectiveMeta: {
265
281
  type: 'object',
266
- description: 'Additional metadata (merged with existing)',
282
+ description:
283
+ 'Open directive metadata (merged with existing; NOT an opening-balance amount)',
267
284
  example: {
268
285
  branch: 'Uptown'
269
286
  }
@@ -310,13 +327,47 @@ export const $ReopenAccountDto = {
310
327
  }
311
328
  } as const;
312
329
 
330
+ export const $CreateOpeningBalanceDto = {
331
+ type: 'object',
332
+ properties: {
333
+ amount: {
334
+ type: 'number',
335
+ description: 'Opening balance amount (non-negative)',
336
+ example: 1000
337
+ },
338
+ currency: {
339
+ type: 'string',
340
+ description: 'Currency code',
341
+ example: 'CNY'
342
+ },
343
+ date: {
344
+ format: 'date-time',
345
+ type: 'string',
346
+ description: 'Opening-balance date (defaults to now)',
347
+ example: '2024-01-01'
348
+ }
349
+ },
350
+ required: ['amount', 'currency']
351
+ } as const;
352
+
353
+ export const $OpeningBalanceResultDto = {
354
+ type: 'object',
355
+ properties: {
356
+ transactionId: {
357
+ type: 'string',
358
+ description: 'Created opening-balance transaction id.'
359
+ }
360
+ },
361
+ required: ['transactionId']
362
+ } as const;
363
+
313
364
  export const $AccountStandardResponseDto = {
314
365
  type: 'object',
315
366
  properties: {
316
367
  path: {
317
368
  type: 'string',
318
369
  description: 'Account path (hierarchical, colon-separated)',
319
- example: 'Assets:CN:Bank:ICBC:Checking'
370
+ example: 'Assets:CN:Checking'
320
371
  },
321
372
  type: {
322
373
  type: 'string',
@@ -324,11 +375,6 @@ export const $AccountStandardResponseDto = {
324
375
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
325
376
  example: 'Assets'
326
377
  },
327
- i18nKey: {
328
- type: 'string',
329
- description: 'i18n key for localized display name',
330
- example: 'account.assets.cn.bank.icbc.checking'
331
- },
332
378
  name: {
333
379
  type: 'string',
334
380
  description: 'Short localized display name',
@@ -351,9 +397,47 @@ export const $AccountStandardResponseDto = {
351
397
  type: 'string',
352
398
  description: 'Icon identifier for UI display',
353
399
  example: 'bank-icbc'
400
+ },
401
+ productCategory: {
402
+ type: 'string',
403
+ description:
404
+ 'Onboarding product category (coarse grouping derived from assetSubClass)',
405
+ enum: [
406
+ 'cash',
407
+ 'investment',
408
+ 'credit_card',
409
+ 'loan',
410
+ 'payable_tax',
411
+ 'other'
412
+ ],
413
+ example: 'investment'
414
+ },
415
+ assetClass: {
416
+ type: 'string',
417
+ description:
418
+ 'Asset class (LIQUIDITY/EQUITY/.../LIABILITY), derived at read time from classification rules',
419
+ enum: [
420
+ 'LIQUIDITY',
421
+ 'EQUITY',
422
+ 'FIXED_INCOME',
423
+ 'PRECIOUS_METALS',
424
+ 'COMMODITY',
425
+ 'INSURANCE',
426
+ 'ALTERNATIVE_INVESTMENT',
427
+ 'PERSONAL_ASSETS',
428
+ 'LIABILITY',
429
+ 'REAL_ESTATE',
430
+ 'INDEX'
431
+ ]
432
+ },
433
+ assetSubClass: {
434
+ type: 'string',
435
+ description:
436
+ 'Asset sub-class (product type, derived at read time from classification rules)',
437
+ example: 'STOCK'
354
438
  }
355
439
  },
356
- required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
440
+ required: ['path', 'type', 'description', 'tags', 'icon', 'productCategory']
357
441
  } as const;
358
442
 
359
443
  export const $AccountStandardListResponseDto = {
@@ -383,18 +467,13 @@ export const $AccountStandardListResponseDto = {
383
467
  export const $TemplateMetadataDto = {
384
468
  type: 'object',
385
469
  properties: {
386
- extendable: {
387
- type: 'boolean',
388
- description: 'Whether this path can be extended',
389
- example: true
390
- },
391
470
  rootType: {
392
471
  type: 'string',
393
472
  description: 'Root account type',
394
473
  example: 'Assets'
395
474
  }
396
475
  },
397
- required: ['extendable', 'rootType']
476
+ required: ['rootType']
398
477
  } as const;
399
478
 
400
479
  export const $TemplateMetadataResponseDto = {
@@ -533,7 +612,7 @@ export const $CreatePostingDto = {
533
612
  type: 'string',
534
613
  description:
535
614
  'Account name in Beancount format (must start with uppercase, colon-separated)',
536
- example: 'Assets:Bank:Checking'
615
+ example: 'Assets:Checking'
537
616
  },
538
617
  units: {
539
618
  type: 'string',
@@ -692,7 +771,7 @@ export const $PostingResponseDto = {
692
771
  account: {
693
772
  type: 'string',
694
773
  description: 'Account name',
695
- example: 'Assets:Bank:Checking'
774
+ example: 'Assets:Checking'
696
775
  },
697
776
  units: {
698
777
  type: 'string',
@@ -1058,7 +1137,7 @@ export const $PostingDetailDto = {
1058
1137
  account: {
1059
1138
  type: 'string',
1060
1139
  description: 'Fully-qualified Beancount account path',
1061
- example: 'Assets:Bank:Checking'
1140
+ example: 'Assets:Checking'
1062
1141
  },
1063
1142
  units: {
1064
1143
  type: 'string',
@@ -1247,6 +1326,77 @@ export const $TransactionDetailDto = {
1247
1326
  ]
1248
1327
  } as const;
1249
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
+
1250
1400
  export const $TransactionListResponseDto = {
1251
1401
  type: 'object',
1252
1402
  properties: {
@@ -1271,6 +1421,15 @@ export const $TransactionListResponseDto = {
1271
1421
  type: 'number',
1272
1422
  description: 'Number of items skipped',
1273
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
+ ]
1274
1433
  }
1275
1434
  },
1276
1435
  required: ['data', 'total', 'limit', 'offset']
@@ -1370,7 +1529,7 @@ export const $BalanceResponseDto = {
1370
1529
  account: {
1371
1530
  type: 'string',
1372
1531
  description: 'Account name',
1373
- example: 'Assets:Bank:Checking'
1532
+ example: 'Assets:Checking'
1374
1533
  },
1375
1534
  balance: {
1376
1535
  type: 'string',
@@ -1397,7 +1556,7 @@ export const $MultiCurrencyBalanceResponseDto = {
1397
1556
  account: {
1398
1557
  type: 'string',
1399
1558
  description: 'Account name',
1400
- example: 'Assets:Bank:Checking'
1559
+ example: 'Assets:Checking'
1401
1560
  },
1402
1561
  balances: {
1403
1562
  type: 'object',
@@ -1453,7 +1612,7 @@ export const $TransactionSummaryDto = {
1453
1612
  accountName: {
1454
1613
  type: 'string',
1455
1614
  description: 'Source account name (first posting)',
1456
- example: 'Assets:Bank:Checking'
1615
+ example: 'Assets:Checking'
1457
1616
  },
1458
1617
  sourceType: {
1459
1618
  type: 'string',
@@ -2745,65 +2904,222 @@ export const $UpdateCommodityDto = {
2745
2904
  }
2746
2905
  } as const;
2747
2906
 
2748
- export const $CreateRecurringRuleDto = {
2907
+ export const $CreateBeanPriceDto = {
2749
2908
  type: 'object',
2750
2909
  properties: {
2751
- name: {
2752
- type: 'string',
2753
- description: 'Rule name (unique per user)',
2754
- maxLength: 100
2755
- },
2756
- icon: {
2910
+ currency: {
2757
2911
  type: 'string',
2758
- description: 'Icon emoji',
2759
- maxLength: 10
2912
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2913
+ example: 'USD'
2760
2914
  },
2761
- frequency: {
2915
+ quoteCurrency: {
2762
2916
  type: 'string',
2763
- description: 'Recurring frequency',
2764
- enum: [
2765
- 'WEEKLY',
2766
- 'BIWEEKLY',
2767
- 'MONTHLY',
2768
- 'BIMONTHLY',
2769
- 'QUARTERLY',
2770
- 'YEARLY',
2771
- 'CUSTOM'
2772
- ]
2917
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
2918
+ example: 'CNY'
2773
2919
  },
2774
- expectedAmount: {
2920
+ amount: {
2775
2921
  type: 'number',
2776
- description: 'Expected amount (positive number)',
2922
+ description:
2923
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
2924
+ example: 175.5,
2777
2925
  minimum: 0
2778
2926
  },
2779
- expectedDay: {
2780
- type: 'number',
2781
- description: 'Expected day of month (1-31)',
2782
- minimum: 1,
2783
- maximum: 31
2927
+ date: {
2928
+ type: 'string',
2929
+ description: 'Price date (ISO 8601 format)',
2930
+ example: '2024-11-05'
2784
2931
  },
2785
- customIntervalDays: {
2786
- type: 'number',
2787
- description: 'Custom interval in days (required for CUSTOM frequency)',
2788
- minimum: 1
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'
2789
2958
  },
2790
2959
  currency: {
2791
2960
  type: 'string',
2792
- description: 'Currency code',
2793
- default: 'CNY',
2794
- maxLength: 10
2961
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2962
+ example: 'BTC'
2795
2963
  },
2796
- matchPayeePattern: {
2964
+ quoteCurrency: {
2797
2965
  type: 'string',
2798
- description: 'Payee matching pattern (supports wildcards)',
2799
- maxLength: 200
2966
+ description: 'Quote currency (pricing currency, e.g., USD, CNY)',
2967
+ example: 'USD'
2800
2968
  },
2801
- matchAmountTolerance: {
2969
+ amount: {
2802
2970
  type: 'number',
2803
- description: 'Amount tolerance percentage (0-1)',
2804
- default: 0.075,
2805
- minimum: 0,
2806
- maximum: 1
2971
+ description:
2972
+ 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
2973
+ example: 50000
2974
+ },
2975
+ date: {
2976
+ type: 'string',
2977
+ description:
2978
+ 'Price date (ISO 8601 format). Represents the date this price was valid.',
2979
+ example: '2024-01-01',
2980
+ format: 'date'
2981
+ },
2982
+ meta: {
2983
+ type: 'object',
2984
+ description:
2985
+ 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
2986
+ example: {
2987
+ source: 'MANUAL',
2988
+ note: 'User-defined price',
2989
+ confidence: 1
2990
+ }
2991
+ },
2992
+ createdAt: {
2993
+ format: 'date-time',
2994
+ type: 'string',
2995
+ description: 'Creation timestamp',
2996
+ example: '2024-11-03T10:00:00Z'
2997
+ },
2998
+ updatedAt: {
2999
+ format: 'date-time',
3000
+ type: 'string',
3001
+ description: 'Last update timestamp',
3002
+ example: '2024-11-03T10:00:00Z'
3003
+ }
3004
+ },
3005
+ required: [
3006
+ 'id',
3007
+ 'userId',
3008
+ 'currency',
3009
+ 'quoteCurrency',
3010
+ 'amount',
3011
+ 'date',
3012
+ 'meta',
3013
+ 'createdAt',
3014
+ 'updatedAt'
3015
+ ]
3016
+ } as const;
3017
+
3018
+ export const $PriceListResponseDto = {
3019
+ type: 'object',
3020
+ properties: {
3021
+ items: {
3022
+ description: 'List of prices',
3023
+ type: 'array',
3024
+ items: {
3025
+ $ref: '#/components/schemas/PriceResponseDto'
3026
+ }
3027
+ },
3028
+ total: {
3029
+ type: 'number',
3030
+ description: 'Total number of prices',
3031
+ example: 42
3032
+ }
3033
+ },
3034
+ required: ['items', 'total']
3035
+ } as const;
3036
+
3037
+ export const $UpdateBeanPriceDto = {
3038
+ type: 'object',
3039
+ properties: {
3040
+ currency: {
3041
+ type: 'string',
3042
+ description: 'Currency being priced'
3043
+ },
3044
+ quoteCurrency: {
3045
+ type: 'string',
3046
+ description: 'Quote currency (pricing currency)'
3047
+ },
3048
+ amount: {
3049
+ type: 'number',
3050
+ description: 'Price amount (MUST be >= 0 per Beancount spec)',
3051
+ minimum: 0
3052
+ },
3053
+ date: {
3054
+ type: 'string',
3055
+ description: 'Price date (ISO 8601 format)'
3056
+ },
3057
+ metadata: {
3058
+ type: 'object',
3059
+ description: 'Metadata'
3060
+ }
3061
+ }
3062
+ } as const;
3063
+
3064
+ export const $CreateRecurringRuleDto = {
3065
+ type: 'object',
3066
+ properties: {
3067
+ name: {
3068
+ type: 'string',
3069
+ description: 'Rule name (unique per user)',
3070
+ maxLength: 100
3071
+ },
3072
+ icon: {
3073
+ type: 'string',
3074
+ description: 'Icon emoji',
3075
+ maxLength: 10
3076
+ },
3077
+ frequency: {
3078
+ type: 'string',
3079
+ description: 'Recurring frequency',
3080
+ enum: [
3081
+ 'WEEKLY',
3082
+ 'BIWEEKLY',
3083
+ 'MONTHLY',
3084
+ 'BIMONTHLY',
3085
+ 'QUARTERLY',
3086
+ 'YEARLY',
3087
+ 'CUSTOM'
3088
+ ]
3089
+ },
3090
+ expectedAmount: {
3091
+ type: 'number',
3092
+ description: 'Expected amount (positive number)',
3093
+ minimum: 0
3094
+ },
3095
+ expectedDay: {
3096
+ type: 'number',
3097
+ description: 'Expected day of month (1-31)',
3098
+ minimum: 1,
3099
+ maximum: 31
3100
+ },
3101
+ customIntervalDays: {
3102
+ type: 'number',
3103
+ description: 'Custom interval in days (required for CUSTOM frequency)',
3104
+ minimum: 1
3105
+ },
3106
+ currency: {
3107
+ type: 'string',
3108
+ description: 'Currency code',
3109
+ default: 'CNY',
3110
+ maxLength: 10
3111
+ },
3112
+ matchPayeePattern: {
3113
+ type: 'string',
3114
+ description: 'Payee matching pattern (supports wildcards)',
3115
+ maxLength: 200
3116
+ },
3117
+ matchAmountTolerance: {
3118
+ type: 'number',
3119
+ description: 'Amount tolerance percentage (0-1)',
3120
+ default: 0.075,
3121
+ minimum: 0,
3122
+ maximum: 1
2807
3123
  },
2808
3124
  defaultExpenseAccount: {
2809
3125
  type: 'string',
@@ -3516,705 +3832,400 @@ export const $ForecastResponseDto = {
3516
3832
  ]
3517
3833
  } as const;
3518
3834
 
3519
- export const $CreateTransactionRuleDto = {
3835
+ export const $CurrencyBalanceDto = {
3520
3836
  type: 'object',
3521
3837
  properties: {
3522
- name: {
3838
+ currency: {
3523
3839
  type: 'string',
3524
- minLength: 1,
3525
- maxLength: 100
3840
+ description: 'ISO 4217 currency code',
3841
+ example: 'CNY'
3526
3842
  },
3527
- description: {
3843
+ balance: {
3528
3844
  type: 'string',
3529
- maxLength: 500
3530
- },
3531
- narrationKeywords: {
3532
- items: {
3533
- type: 'array'
3534
- },
3535
- maxItems: 50,
3536
- type: 'array'
3537
- },
3538
- payeeKeywords: {
3539
- items: {
3540
- type: 'array'
3541
- },
3542
- maxItems: 50,
3543
- type: 'array'
3544
- },
3545
- categoryKeywords: {
3546
- items: {
3547
- type: 'array'
3548
- },
3549
- maxItems: 50,
3550
- type: 'array'
3551
- },
3552
- methodKeywords: {
3553
- items: {
3554
- type: 'array'
3555
- },
3556
- maxItems: 50,
3557
- description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
3558
- type: 'array'
3559
- },
3560
- categoryAccount: {
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: {
3561
3856
  type: 'string',
3562
- maxLength: 200,
3563
- description:
3564
- 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
3857
+ description: 'Date in YYYY-MM-DD format',
3858
+ example: '2024-06-15'
3565
3859
  },
3566
- matchLogic: {
3860
+ value: {
3567
3861
  type: 'string',
3568
- enum: ['OR', 'AND'],
3569
- default: 'OR'
3862
+ description: 'Value at this date (in base currency)',
3863
+ example: '500000.00'
3570
3864
  },
3571
- amountMin: {
3572
- type: 'number',
3573
- minimum: 0,
3574
- description: 'Minimum transaction amount (inclusive)'
3865
+ change: {
3866
+ type: 'object',
3867
+ description: 'Change from previous point',
3868
+ example: '5000.00'
3575
3869
  },
3576
- amountMax: {
3577
- type: 'number',
3578
- minimum: 0,
3579
- description: 'Maximum transaction amount (inclusive)'
3870
+ assets: {
3871
+ type: 'string',
3872
+ description: 'Total assets at this date (in base currency)',
3873
+ example: '494338.00'
3580
3874
  },
3581
- priority: {
3582
- type: 'number',
3583
- default: 50,
3584
- minimum: 0,
3585
- maximum: 1000
3875
+ liabilities: {
3876
+ type: 'string',
3877
+ description: 'Total liabilities at this date (in base currency)',
3878
+ example: '310098.00'
3586
3879
  },
3587
- additionalTags: {
3880
+ byCurrency: {
3881
+ description: 'Multi-currency breakdown for this point',
3882
+ type: 'array',
3588
3883
  items: {
3589
- type: 'array'
3590
- },
3591
- maxItems: 20,
3592
- type: 'array'
3593
- },
3594
- additionalMetadata: {
3595
- type: 'object'
3596
- },
3597
- upsertByPayee: {
3598
- type: 'boolean',
3599
- description:
3600
- 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
3884
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3885
+ }
3601
3886
  }
3602
3887
  },
3603
- required: ['name', 'matchLogic', 'priority']
3888
+ required: ['date', 'value']
3604
3889
  } as const;
3605
3890
 
3606
- export const $AmountRangeDto = {
3891
+ export const $TrendSummaryDto = {
3607
3892
  type: 'object',
3608
3893
  properties: {
3609
- min: {
3610
- type: 'number',
3611
- description: 'Minimum amount'
3894
+ startValue: {
3895
+ type: 'string',
3896
+ description: 'Value at start of period',
3897
+ example: '450000.00'
3612
3898
  },
3613
- max: {
3614
- type: 'number',
3615
- description: 'Maximum amount'
3899
+ endValue: {
3900
+ type: 'string',
3901
+ description: 'Value at end of period',
3902
+ example: '500000.00'
3903
+ },
3904
+ totalChange: {
3905
+ type: 'string',
3906
+ description: 'Total change over period',
3907
+ example: '50000.00'
3908
+ },
3909
+ totalChangePercentage: {
3910
+ type: 'string',
3911
+ description: 'Total change percentage',
3912
+ example: '+11.11%'
3616
3913
  }
3617
- }
3914
+ },
3915
+ required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
3618
3916
  } as const;
3619
3917
 
3620
- export const $TransactionRuleResponseDto = {
3918
+ export const $MultiCurrencyPointDto = {
3621
3919
  type: 'object',
3622
3920
  properties: {
3623
- id: {
3624
- type: 'string',
3625
- description: 'Rule ID'
3626
- },
3627
- name: {
3628
- type: 'string',
3629
- description: 'Rule name'
3630
- },
3631
- description: {
3921
+ date: {
3632
3922
  type: 'string',
3633
- description: 'Rule description'
3634
- },
3635
- narrationKeywords: {
3636
- description: 'Keywords to match in transaction narration',
3637
- type: 'array',
3638
- items: {
3639
- type: 'string'
3640
- }
3641
- },
3642
- payeeKeywords: {
3643
- description: 'Keywords to match in payee name',
3644
- type: 'array',
3645
- items: {
3646
- type: 'string'
3647
- }
3923
+ description: 'Date in YYYY-MM-DD format',
3924
+ example: '2024-06-15'
3648
3925
  },
3649
- categoryKeywords: {
3650
- description: 'Keywords to match in category',
3926
+ byCurrency: {
3927
+ description: 'Balances by currency',
3651
3928
  type: 'array',
3652
3929
  items: {
3653
- type: 'string'
3930
+ $ref: '#/components/schemas/CurrencyBalanceDto'
3654
3931
  }
3655
- },
3656
- methodKeywords: {
3657
- description: 'Keywords to match in payment method',
3932
+ }
3933
+ },
3934
+ required: ['date', 'byCurrency']
3935
+ } as const;
3936
+
3937
+ export const $PortfolioTrendsResponseDto = {
3938
+ type: 'object',
3939
+ properties: {
3940
+ series: {
3941
+ description: 'Time series data points',
3658
3942
  type: 'array',
3659
3943
  items: {
3660
- type: 'string'
3944
+ $ref: '#/components/schemas/TimeSeriesPointDto'
3661
3945
  }
3662
3946
  },
3663
- categoryAccount: {
3664
- type: 'string',
3665
- description: 'Destination account for categorization'
3666
- },
3667
- matchLogic: {
3668
- type: 'string',
3669
- description: 'Keyword matching logic',
3670
- enum: ['OR', 'AND'],
3671
- example: 'OR'
3672
- },
3673
- amountRange: {
3674
- description: 'Amount range for matching',
3947
+ summary: {
3948
+ description: 'Period summary',
3675
3949
  allOf: [
3676
3950
  {
3677
- $ref: '#/components/schemas/AmountRangeDto'
3951
+ $ref: '#/components/schemas/TrendSummaryDto'
3678
3952
  }
3679
3953
  ]
3680
3954
  },
3681
- priority: {
3682
- type: 'number',
3683
- description: 'Rule priority (0-1000, higher = first match)',
3684
- example: 50
3685
- },
3686
- enabled: {
3687
- type: 'boolean',
3688
- description: 'Whether the rule is enabled'
3689
- },
3690
- learningSource: {
3955
+ period: {
3691
3956
  type: 'string',
3692
- description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
3693
- enum: ['NLP', 'REVIEW_CENTER'],
3694
- nullable: true,
3695
- example: 'REVIEW_CENTER'
3957
+ description: 'Period requested',
3958
+ example: '6m'
3696
3959
  },
3697
- autoApplyEnabled: {
3698
- type: 'boolean',
3699
- description: 'Whether auto-apply is enabled for this rule'
3960
+ granularity: {
3961
+ type: 'string',
3962
+ description: 'Data granularity',
3963
+ example: 'month'
3700
3964
  },
3701
- confirmationCount: {
3702
- type: 'number',
3703
- description: 'Number of confirmations for NLP-learned rules',
3704
- example: 3
3965
+ currency: {
3966
+ type: 'string',
3967
+ description: 'Base currency for converted values',
3968
+ example: 'CNY'
3705
3969
  },
3706
- additionalTags: {
3707
- description: 'Additional tags',
3970
+ byCurrency: {
3971
+ description:
3972
+ 'Multi-currency time series (each point has currency breakdown)',
3708
3973
  type: 'array',
3709
3974
  items: {
3710
- type: 'string'
3975
+ $ref: '#/components/schemas/MultiCurrencyPointDto'
3711
3976
  }
3712
3977
  },
3713
- additionalMetadata: {
3714
- type: 'object',
3715
- description: 'Additional metadata',
3716
- additionalProperties: {
3717
- type: 'string'
3978
+ warnings: {
3979
+ description: 'Exchange rate warnings',
3980
+ type: 'array',
3981
+ items: {
3982
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
3718
3983
  }
3719
- },
3720
- createdAt: {
3721
- format: 'date-time',
3722
- type: 'string',
3723
- description: 'Created timestamp'
3724
- },
3725
- updatedAt: {
3726
- format: 'date-time',
3727
- type: 'string',
3728
- description: 'Updated timestamp'
3729
3984
  }
3730
3985
  },
3731
- required: [
3732
- 'id',
3733
- 'name',
3734
- 'narrationKeywords',
3735
- 'payeeKeywords',
3736
- 'categoryKeywords',
3737
- 'methodKeywords',
3738
- 'matchLogic',
3739
- 'priority',
3740
- 'enabled',
3741
- 'autoApplyEnabled',
3742
- 'confirmationCount',
3743
- 'additionalTags',
3744
- 'createdAt',
3745
- 'updatedAt'
3746
- ]
3986
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3747
3987
  } as const;
3748
3988
 
3749
- export const $TransactionRuleListResponseDto = {
3989
+ export const $CashFlowPointDto = {
3750
3990
  type: 'object',
3751
3991
  properties: {
3752
- data: {
3753
- type: 'array',
3754
- items: {
3755
- $ref: '#/components/schemas/TransactionRuleResponseDto'
3756
- }
3992
+ month: {
3993
+ type: 'string',
3994
+ description: 'Month key (YYYY-MM)',
3995
+ example: '2024-03'
3757
3996
  },
3758
- total: {
3759
- type: 'number',
3760
- description: 'Total count of rules'
3997
+ income: {
3998
+ type: 'string',
3999
+ description: 'Income in base currency (absolute, converted)',
4000
+ example: '10000.00'
3761
4001
  },
3762
- limit: {
3763
- type: 'number',
3764
- description: 'Results per page'
4002
+ expense: {
4003
+ type: 'string',
4004
+ description: 'Expense in base currency (absolute, converted)',
4005
+ example: '5000.00'
3765
4006
  },
3766
- offset: {
3767
- type: 'number',
3768
- description: 'Pagination offset'
4007
+ netSavings: {
4008
+ type: 'string',
4009
+ description: 'netSavings = income − expense (savings positive)',
4010
+ example: '5000.00'
3769
4011
  }
3770
4012
  },
3771
- required: ['data', 'total', 'limit', 'offset']
4013
+ required: ['month', 'income', 'expense', 'netSavings']
3772
4014
  } as const;
3773
4015
 
3774
- export const $ValidateRuleDto = {
4016
+ export const $CashFlowTrendSummaryDto = {
3775
4017
  type: 'object',
3776
4018
  properties: {
3777
- name: {
4019
+ totalIncome: {
3778
4020
  type: 'string',
3779
- minLength: 1,
3780
- maxLength: 100
4021
+ description: 'Total income across the period',
4022
+ example: '60000.00'
3781
4023
  },
3782
- description: {
4024
+ totalExpense: {
3783
4025
  type: 'string',
3784
- maxLength: 500
4026
+ description: 'Total expense across the period',
4027
+ example: '30000.00'
3785
4028
  },
3786
- narrationKeywords: {
3787
- items: {
3788
- type: 'array'
3789
- },
3790
- maxItems: 50,
3791
- type: 'array'
4029
+ totalNetSavings: {
4030
+ type: 'string',
4031
+ description: 'income − expense across the period',
4032
+ example: '30000.00'
3792
4033
  },
3793
- payeeKeywords: {
4034
+ averageMonthlyNetSavings: {
4035
+ type: 'string',
4036
+ description:
4037
+ 'totalNetSavings divided by the window length (N months, incl. zero-filled)',
4038
+ example: '5000.00'
4039
+ }
4040
+ },
4041
+ required: [
4042
+ 'totalIncome',
4043
+ 'totalExpense',
4044
+ 'totalNetSavings',
4045
+ 'averageMonthlyNetSavings'
4046
+ ]
4047
+ } as const;
4048
+
4049
+ export const $CashFlowTrendsResponseDto = {
4050
+ type: 'object',
4051
+ properties: {
4052
+ series: {
4053
+ description:
4054
+ 'Monthly cash-flow series (fixed N-month window, zero-filled)',
4055
+ type: 'array',
3794
4056
  items: {
3795
- type: 'array'
3796
- },
3797
- maxItems: 50,
3798
- type: 'array'
4057
+ $ref: '#/components/schemas/CashFlowPointDto'
4058
+ }
3799
4059
  },
3800
- categoryKeywords: {
3801
- items: {
3802
- type: 'array'
3803
- },
3804
- maxItems: 50,
3805
- type: 'array'
4060
+ summary: {
4061
+ description: 'Period totals',
4062
+ allOf: [
4063
+ {
4064
+ $ref: '#/components/schemas/CashFlowTrendSummaryDto'
4065
+ }
4066
+ ]
3806
4067
  },
3807
- methodKeywords: {
3808
- items: {
3809
- type: 'array'
3810
- },
3811
- maxItems: 50,
3812
- description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
3813
- type: 'array'
4068
+ period: {
4069
+ type: 'string',
4070
+ description: 'Period requested',
4071
+ example: '6m'
3814
4072
  },
3815
- categoryAccount: {
4073
+ granularity: {
3816
4074
  type: 'string',
3817
- maxLength: 200,
3818
- description:
3819
- 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4075
+ description: 'Data granularity (v1 returns month buckets)',
4076
+ example: 'month'
3820
4077
  },
3821
- matchLogic: {
4078
+ currency: {
3822
4079
  type: 'string',
3823
- enum: ['OR', 'AND'],
3824
- default: 'OR'
3825
- },
3826
- amountMin: {
3827
- type: 'number',
3828
- minimum: 0,
3829
- description: 'Minimum transaction amount (inclusive)'
3830
- },
3831
- amountMax: {
3832
- type: 'number',
3833
- minimum: 0,
3834
- description: 'Maximum transaction amount (inclusive)'
3835
- },
3836
- priority: {
3837
- type: 'number',
3838
- default: 50,
3839
- minimum: 0,
3840
- maximum: 1000
4080
+ description: 'Base currency for converted values',
4081
+ example: 'CNY'
3841
4082
  },
3842
- additionalTags: {
4083
+ warnings: {
4084
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
4085
+ type: 'array',
3843
4086
  items: {
3844
- type: 'array'
3845
- },
3846
- maxItems: 20,
3847
- type: 'array'
3848
- },
3849
- additionalMetadata: {
3850
- type: 'object'
3851
- },
3852
- upsertByPayee: {
3853
- type: 'boolean',
3854
- description:
3855
- 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
4087
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
4088
+ }
3856
4089
  }
3857
4090
  },
3858
- required: ['name', 'matchLogic', 'priority']
4091
+ required: ['series', 'summary', 'period', 'granularity', 'currency']
3859
4092
  } as const;
3860
4093
 
3861
- export const $ValidateRuleResponseDto = {
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 = {
3862
4115
  type: 'object',
3863
4116
  properties: {
3864
- valid: {
3865
- type: 'boolean',
3866
- description: 'Whether the rule configuration is valid',
3867
- example: true
3868
- },
3869
- errors: {
3870
- description: 'List of validation errors (empty if valid)',
3871
- example: [],
3872
- items: {
3873
- type: 'array'
3874
- },
3875
- type: 'array'
3876
- },
3877
- warnings: {
3878
- description: 'List of validation warnings (non-blocking issues)',
3879
- example: [
3880
- 'No account constraints specified - rule will match any account'
3881
- ],
3882
- items: {
3883
- type: 'array'
3884
- },
3885
- type: 'array'
4117
+ accessToken: {
4118
+ type: 'string',
4119
+ description: 'Access token for user verification',
4120
+ example: 'abc123xyz'
3886
4121
  }
3887
4122
  },
3888
- required: ['valid', 'errors', 'warnings']
4123
+ required: ['accessToken']
3889
4124
  } as const;
3890
4125
 
3891
- export const $BulkCreateRulesDto = {
4126
+ export const $UserSettingsResponseDto = {
3892
4127
  type: 'object',
3893
4128
  properties: {
3894
- rules: {
3895
- items: {
3896
- type: 'array'
3897
- },
3898
- description: 'Array of rules to import',
3899
- type: 'array'
3900
- },
3901
- conflictStrategy: {
4129
+ baseCurrency: {
3902
4130
  type: 'string',
3903
- enum: ['replace', 'skip'],
3904
- default: 'skip',
3905
4131
  description:
3906
- 'Conflict handling strategy: skip (default) ignores duplicates, replace soft-deletes existing rule'
4132
+ 'Base currency (ISO 4217) for net-worth/report aggregation. Independent of region (ADR-0006).',
4133
+ example: 'USD',
4134
+ nullable: true
3907
4135
  }
3908
4136
  },
3909
- required: ['rules', 'conflictStrategy']
4137
+ required: ['baseCurrency']
3910
4138
  } as const;
3911
4139
 
3912
- export const $BulkCreateRulesResponseDto = {
4140
+ export const $UserResponseDto = {
3913
4141
  type: 'object',
3914
4142
  properties: {
3915
- successCount: {
3916
- type: 'number',
3917
- description: 'Number of successfully created rules'
3918
- },
3919
- failureCount: {
3920
- type: 'number',
3921
- description: 'Number of failed rules'
4143
+ id: {
4144
+ type: 'string',
4145
+ description: 'User ID'
3922
4146
  },
3923
- errors: {
3924
- type: 'array',
3925
- description: 'Error details for failed rules',
3926
- items: {
3927
- type: 'object',
3928
- properties: {
3929
- index: {
3930
- type: 'number'
3931
- },
3932
- message: {
3933
- type: 'string'
3934
- }
3935
- }
3936
- }
4147
+ role: {
4148
+ type: 'string',
4149
+ description: 'Assigned user role'
3937
4150
  },
3938
- createdRuleIds: {
3939
- description: 'IDs of successfully created rules',
4151
+ permissions: {
4152
+ description: 'Permission strings',
3940
4153
  type: 'array',
3941
4154
  items: {
3942
4155
  type: 'string'
3943
4156
  }
4157
+ },
4158
+ settings: {
4159
+ description: 'User settings',
4160
+ allOf: [
4161
+ {
4162
+ $ref: '#/components/schemas/UserSettingsResponseDto'
4163
+ }
4164
+ ]
3944
4165
  }
3945
4166
  },
3946
- required: ['successCount', 'failureCount', 'errors', 'createdRuleIds']
4167
+ required: ['id', 'role', 'permissions', 'settings']
3947
4168
  } as const;
3948
4169
 
3949
- export const $ExportRulesResponseDto = {
4170
+ export const $SignupDto = {
3950
4171
  type: 'object',
3951
4172
  properties: {
3952
- exportedAt: {
3953
- type: 'string',
3954
- description: 'Export timestamp'
3955
- },
3956
- userId: {
4173
+ turnstileToken: {
3957
4174
  type: 'string',
3958
- description: 'User ID'
3959
- },
3960
- ruleCount: {
3961
- type: 'number',
3962
- description: 'Number of exported rules'
3963
- },
3964
- rules: {
3965
- type: 'array',
3966
- description: 'Exported rules'
4175
+ description:
4176
+ 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4177
+ example: '0.abc123def456...'
3967
4178
  }
3968
- },
3969
- required: ['exportedAt', 'userId', 'ruleCount', 'rules']
4179
+ }
3970
4180
  } as const;
3971
4181
 
3972
- export const $RuleStatisticsResponseDto = {
4182
+ export const $SignupResponseDto = {
3973
4183
  type: 'object',
3974
4184
  properties: {
3975
- period: {
4185
+ authToken: {
3976
4186
  type: 'string',
3977
- description: 'Statistics time period',
3978
- enum: ['7d', '30d', '90d']
3979
- },
3980
- totalRules: {
3981
- type: 'number',
3982
- description: 'Total number of rules'
3983
- },
3984
- rulesWithMatches: {
3985
- type: 'number',
3986
- description: 'Number of rules with at least one match'
3987
- },
3988
- totalMatches: {
3989
- type: 'number',
3990
- description: 'Total number of matches across all rules'
4187
+ description: 'JWT auth token',
4188
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
3991
4189
  },
3992
- averageConfidence: {
3993
- type: 'number',
3994
- description: 'Average confidence score across all matches',
3995
- example: 0.82
4190
+ accessToken: {
4191
+ type: 'string',
4192
+ description: 'Auto-generated access token'
3996
4193
  },
3997
- ruleStats: {
3998
- type: 'array',
3999
- description: 'Per-rule statistics',
4000
- items: {
4001
- type: 'object',
4002
- properties: {
4003
- ruleId: {
4004
- type: 'string'
4005
- },
4006
- ruleName: {
4007
- type: 'string'
4008
- },
4009
- matchCount: {
4010
- type: 'number'
4011
- },
4012
- averageConfidence: {
4013
- type: 'number'
4014
- }
4015
- }
4016
- }
4194
+ role: {
4195
+ type: 'string',
4196
+ description: 'Assigned user role',
4197
+ enum: ['USER', 'ADMIN', 'DEMO', 'INACTIVE', 'PAID', 'OPS']
4017
4198
  }
4018
4199
  },
4019
- required: [
4020
- 'period',
4021
- 'totalRules',
4022
- 'rulesWithMatches',
4023
- 'totalMatches',
4024
- 'averageConfidence',
4025
- 'ruleStats'
4026
- ]
4200
+ required: ['authToken', 'accessToken', 'role']
4027
4201
  } as const;
4028
4202
 
4029
- export const $UpdateTransactionRuleDto = {
4203
+ export const $UpdateUserSettingDto = {
4030
4204
  type: 'object',
4031
4205
  properties: {
4032
- name: {
4206
+ secId: {
4207
+ type: 'number',
4208
+ description: 'Security ID'
4209
+ },
4210
+ annualInterestRate: {
4211
+ type: 'number',
4212
+ description: 'Annual interest rate',
4213
+ example: 0.05
4214
+ },
4215
+ currency: {
4033
4216
  type: 'string',
4034
- minLength: 1,
4035
- maxLength: 100
4217
+ description: 'Currency code',
4218
+ example: 'USD'
4036
4219
  },
4037
- description: {
4220
+ baseCurrency: {
4038
4221
  type: 'string',
4039
- maxLength: 500
4222
+ description: 'Base currency code',
4223
+ example: 'USD'
4040
4224
  },
4041
- narrationKeywords: {
4042
- items: {
4043
- type: 'array'
4044
- },
4045
- maxItems: 50,
4046
- type: 'array'
4047
- },
4048
- payeeKeywords: {
4049
- items: {
4050
- type: 'array'
4051
- },
4052
- maxItems: 50,
4053
- type: 'array'
4054
- },
4055
- categoryKeywords: {
4056
- items: {
4057
- type: 'array'
4058
- },
4059
- maxItems: 50,
4060
- type: 'array'
4061
- },
4062
- methodKeywords: {
4063
- items: {
4064
- type: 'array'
4065
- },
4066
- maxItems: 50,
4067
- description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4068
- type: 'array'
4069
- },
4070
- categoryAccount: {
4071
- type: 'string',
4072
- maxLength: 200,
4073
- description:
4074
- 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4075
- },
4076
- matchLogic: {
4077
- type: 'string',
4078
- enum: ['OR', 'AND']
4079
- },
4080
- amountMin: {
4081
- type: 'number',
4082
- minimum: 0,
4083
- description: 'Minimum transaction amount (inclusive)'
4084
- },
4085
- amountMax: {
4086
- type: 'number',
4087
- minimum: 0,
4088
- description: 'Maximum transaction amount (inclusive)'
4089
- },
4090
- priority: {
4091
- type: 'number',
4092
- minimum: 0,
4093
- maximum: 1000
4094
- },
4095
- enabled: {
4096
- type: 'boolean',
4097
- description: 'Enable or disable the rule'
4098
- },
4099
- additionalTags: {
4100
- items: {
4101
- type: 'array'
4102
- },
4103
- maxItems: 20,
4104
- type: 'array'
4105
- },
4106
- additionalMetadata: {
4107
- type: 'object'
4108
- }
4109
- }
4110
- } as const;
4111
-
4112
- export const $TestRuleDto = {
4113
- type: 'object',
4114
- properties: {
4115
- narration: {
4116
- type: 'string',
4117
- minLength: 1,
4118
- maxLength: 500
4119
- },
4120
- payee: {
4121
- type: 'string',
4122
- maxLength: 200
4123
- },
4124
- categoryAccount: {
4125
- type: 'string',
4126
- maxLength: 200
4127
- },
4128
- amount: {
4129
- type: 'number'
4130
- },
4131
- currency: {
4132
- type: 'string',
4133
- maxLength: 10
4134
- }
4135
- },
4136
- required: ['narration']
4137
- } as const;
4138
-
4139
- export const $TestRuleResponseDto = {
4140
- type: 'object',
4141
- properties: {
4142
- ruleId: {
4143
- type: 'string',
4144
- description: 'Rule ID that was tested'
4145
- },
4146
- matches: {
4147
- type: 'boolean',
4148
- description: 'Whether the rule matched the test data'
4149
- },
4150
- confidence: {
4151
- type: 'number',
4152
- description: 'Match confidence score (0-1)',
4153
- example: 0.85
4154
- },
4155
- matchDetails: {
4156
- type: 'object',
4157
- description: 'Details of which fields matched',
4158
- example: {
4159
- narration: true,
4160
- payee: false,
4161
- categoryAccount: false
4162
- }
4163
- }
4164
- },
4165
- required: ['ruleId', 'matches', 'confidence', 'matchDetails']
4166
- } as const;
4167
-
4168
- export const $DeleteOwnUserDto = {
4169
- type: 'object',
4170
- properties: {
4171
- accessToken: {
4172
- type: 'string',
4173
- description: 'Access token for user verification',
4174
- example: 'abc123xyz'
4175
- }
4176
- },
4177
- required: ['accessToken']
4178
- } as const;
4179
-
4180
- export const $SignupDto = {
4181
- type: 'object',
4182
- properties: {
4183
- turnstileToken: {
4184
- type: 'string',
4185
- description:
4186
- 'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
4187
- example: '0.abc123def456...'
4188
- }
4189
- }
4190
- } as const;
4191
-
4192
- export const $UpdateUserSettingDto = {
4193
- type: 'object',
4194
- properties: {
4195
- secId: {
4196
- type: 'number',
4197
- description: 'Security ID'
4198
- },
4199
- annualInterestRate: {
4200
- type: 'number',
4201
- description: 'Annual interest rate',
4202
- example: 0.05
4203
- },
4204
- currency: {
4205
- type: 'string',
4206
- description: 'Currency code',
4207
- example: 'USD'
4208
- },
4209
- baseCurrency: {
4210
- type: 'string',
4211
- description: 'Base currency code',
4212
- example: 'USD'
4213
- },
4214
- benchmark: {
4215
- type: 'string',
4216
- description: 'Benchmark symbol',
4217
- example: 'SPY'
4225
+ benchmark: {
4226
+ type: 'string',
4227
+ description: 'Benchmark symbol',
4228
+ example: 'SPY'
4218
4229
  },
4219
4230
  colorScheme: {
4220
4231
  type: 'string',
@@ -4312,74 +4323,1175 @@ export const $UpdatePropertyDto = {
4312
4323
  required: ['value']
4313
4324
  } as const;
4314
4325
 
4315
- export const $FileImportDto = {
4326
+ export const $CreateTransactionRuleDto = {
4316
4327
  type: 'object',
4317
4328
  properties: {
4318
- file: {
4329
+ name: {
4319
4330
  type: 'string',
4320
- format: 'binary',
4321
- description: 'Bill file to import (CSV, PDF, OFX, etc.)',
4322
- example: 'alipay.csv'
4323
- }
4324
- },
4325
- required: ['file']
4326
- } as const;
4327
-
4328
- export const $ImportErrorDto = {
4329
- type: 'object',
4330
- properties: {
4331
- index: {
4332
- type: 'number',
4333
- description: 'Index of failed transaction in the file',
4334
- example: 5
4331
+ minLength: 1,
4332
+ maxLength: 100
4335
4333
  },
4336
- error: {
4334
+ description: {
4337
4335
  type: 'string',
4338
- description: 'Error message',
4339
- example: 'Transaction does not balance: -100 USD != 0'
4340
- }
4341
- },
4342
- required: ['index', 'error']
4343
- } as const;
4344
-
4345
- export const $ReviewItemPreviewDto = {
4346
- type: 'object',
4347
- properties: {
4348
- index: {
4349
- type: 'number',
4350
- description: 'Index in the import batch (for tracking)',
4351
- example: 0
4336
+ maxLength: 500
4352
4337
  },
4353
- date: {
4354
- type: 'string',
4355
- description: 'Transaction date (ISO format)',
4356
- example: '2026-03-05'
4338
+ narrationKeywords: {
4339
+ items: {
4340
+ type: 'array'
4341
+ },
4342
+ maxItems: 50,
4343
+ type: 'array'
4357
4344
  },
4358
- amount: {
4359
- type: 'number',
4360
- description: 'Transaction amount (absolute value)',
4361
- example: 99
4345
+ payeeKeywords: {
4346
+ items: {
4347
+ type: 'array'
4348
+ },
4349
+ maxItems: 50,
4350
+ type: 'array'
4362
4351
  },
4363
- currency: {
4364
- type: 'string',
4365
- description: 'Currency code',
4366
- example: 'CNY'
4352
+ categoryKeywords: {
4353
+ items: {
4354
+ type: 'array'
4355
+ },
4356
+ maxItems: 50,
4357
+ type: 'array'
4367
4358
  },
4368
- narration: {
4369
- type: 'string',
4370
- description: 'Transaction narration/description',
4371
- example: 'Restaurant expense'
4359
+ methodKeywords: {
4360
+ items: {
4361
+ type: 'array'
4362
+ },
4363
+ maxItems: 50,
4364
+ description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4365
+ type: 'array'
4372
4366
  },
4373
- payee: {
4367
+ categoryAccount: {
4374
4368
  type: 'string',
4375
- description: 'Payee name',
4376
- example: 'Restaurant ABC'
4369
+ maxLength: 200,
4370
+ description:
4371
+ 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4377
4372
  },
4378
- category: {
4373
+ matchLogic: {
4379
4374
  type: 'string',
4380
- description: 'Inferred category from rule matching',
4381
- example: 'food'
4382
- },
4375
+ enum: ['OR', 'AND'],
4376
+ default: 'OR'
4377
+ },
4378
+ amountMin: {
4379
+ type: 'number',
4380
+ minimum: 0,
4381
+ description: 'Minimum transaction amount (inclusive)'
4382
+ },
4383
+ amountMax: {
4384
+ type: 'number',
4385
+ minimum: 0,
4386
+ description: 'Maximum transaction amount (inclusive)'
4387
+ },
4388
+ priority: {
4389
+ type: 'number',
4390
+ default: 50,
4391
+ minimum: 0,
4392
+ maximum: 1000
4393
+ },
4394
+ additionalTags: {
4395
+ items: {
4396
+ type: 'array'
4397
+ },
4398
+ maxItems: 20,
4399
+ type: 'array'
4400
+ },
4401
+ additionalMetadata: {
4402
+ type: 'object'
4403
+ },
4404
+ upsertByPayee: {
4405
+ type: 'boolean',
4406
+ description:
4407
+ 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
4408
+ }
4409
+ },
4410
+ required: ['name', 'matchLogic', 'priority']
4411
+ } as const;
4412
+
4413
+ export const $AmountRangeDto = {
4414
+ type: 'object',
4415
+ properties: {
4416
+ min: {
4417
+ type: 'number',
4418
+ description: 'Minimum amount'
4419
+ },
4420
+ max: {
4421
+ type: 'number',
4422
+ description: 'Maximum amount'
4423
+ }
4424
+ }
4425
+ } as const;
4426
+
4427
+ export const $TransactionRuleResponseDto = {
4428
+ type: 'object',
4429
+ properties: {
4430
+ id: {
4431
+ type: 'string',
4432
+ description: 'Rule ID'
4433
+ },
4434
+ name: {
4435
+ type: 'string',
4436
+ description: 'Rule name'
4437
+ },
4438
+ description: {
4439
+ type: 'string',
4440
+ description: 'Rule description'
4441
+ },
4442
+ narrationKeywords: {
4443
+ description: 'Keywords to match in transaction narration',
4444
+ type: 'array',
4445
+ items: {
4446
+ type: 'string'
4447
+ }
4448
+ },
4449
+ payeeKeywords: {
4450
+ description: 'Keywords to match in payee name',
4451
+ type: 'array',
4452
+ items: {
4453
+ type: 'string'
4454
+ }
4455
+ },
4456
+ categoryKeywords: {
4457
+ description: 'Keywords to match in category',
4458
+ type: 'array',
4459
+ items: {
4460
+ type: 'string'
4461
+ }
4462
+ },
4463
+ methodKeywords: {
4464
+ description: 'Keywords to match in payment method',
4465
+ type: 'array',
4466
+ items: {
4467
+ type: 'string'
4468
+ }
4469
+ },
4470
+ categoryAccount: {
4471
+ type: 'string',
4472
+ description: 'Destination account for categorization'
4473
+ },
4474
+ matchLogic: {
4475
+ type: 'string',
4476
+ description: 'Keyword matching logic',
4477
+ enum: ['OR', 'AND'],
4478
+ example: 'OR'
4479
+ },
4480
+ amountRange: {
4481
+ description: 'Amount range for matching',
4482
+ allOf: [
4483
+ {
4484
+ $ref: '#/components/schemas/AmountRangeDto'
4485
+ }
4486
+ ]
4487
+ },
4488
+ priority: {
4489
+ type: 'number',
4490
+ description: 'Rule priority (0-1000, higher = first match)',
4491
+ example: 50
4492
+ },
4493
+ enabled: {
4494
+ type: 'boolean',
4495
+ description: 'Whether the rule is enabled'
4496
+ },
4497
+ learningSource: {
4498
+ type: 'string',
4499
+ description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
4500
+ enum: ['NLP', 'REVIEW_CENTER'],
4501
+ nullable: true,
4502
+ example: 'REVIEW_CENTER'
4503
+ },
4504
+ autoApplyEnabled: {
4505
+ type: 'boolean',
4506
+ description: 'Whether auto-apply is enabled for this rule'
4507
+ },
4508
+ confirmationCount: {
4509
+ type: 'number',
4510
+ description: 'Number of confirmations for NLP-learned rules',
4511
+ example: 3
4512
+ },
4513
+ additionalTags: {
4514
+ description: 'Additional tags',
4515
+ type: 'array',
4516
+ items: {
4517
+ type: 'string'
4518
+ }
4519
+ },
4520
+ additionalMetadata: {
4521
+ type: 'object',
4522
+ description: 'Additional metadata',
4523
+ additionalProperties: {
4524
+ type: 'string'
4525
+ }
4526
+ },
4527
+ createdAt: {
4528
+ format: 'date-time',
4529
+ type: 'string',
4530
+ description: 'Created timestamp'
4531
+ },
4532
+ updatedAt: {
4533
+ format: 'date-time',
4534
+ type: 'string',
4535
+ description: 'Updated timestamp'
4536
+ }
4537
+ },
4538
+ required: [
4539
+ 'id',
4540
+ 'name',
4541
+ 'narrationKeywords',
4542
+ 'payeeKeywords',
4543
+ 'categoryKeywords',
4544
+ 'methodKeywords',
4545
+ 'matchLogic',
4546
+ 'priority',
4547
+ 'enabled',
4548
+ 'autoApplyEnabled',
4549
+ 'confirmationCount',
4550
+ 'additionalTags',
4551
+ 'createdAt',
4552
+ 'updatedAt'
4553
+ ]
4554
+ } as const;
4555
+
4556
+ export const $TransactionRuleListResponseDto = {
4557
+ type: 'object',
4558
+ properties: {
4559
+ data: {
4560
+ type: 'array',
4561
+ items: {
4562
+ $ref: '#/components/schemas/TransactionRuleResponseDto'
4563
+ }
4564
+ },
4565
+ total: {
4566
+ type: 'number',
4567
+ description: 'Total count of rules'
4568
+ },
4569
+ limit: {
4570
+ type: 'number',
4571
+ description: 'Results per page'
4572
+ },
4573
+ offset: {
4574
+ type: 'number',
4575
+ description: 'Pagination offset'
4576
+ }
4577
+ },
4578
+ required: ['data', 'total', 'limit', 'offset']
4579
+ } as const;
4580
+
4581
+ export const $ValidateRuleDto = {
4582
+ type: 'object',
4583
+ properties: {
4584
+ name: {
4585
+ type: 'string',
4586
+ minLength: 1,
4587
+ maxLength: 100
4588
+ },
4589
+ description: {
4590
+ type: 'string',
4591
+ maxLength: 500
4592
+ },
4593
+ narrationKeywords: {
4594
+ items: {
4595
+ type: 'array'
4596
+ },
4597
+ maxItems: 50,
4598
+ type: 'array'
4599
+ },
4600
+ payeeKeywords: {
4601
+ items: {
4602
+ type: 'array'
4603
+ },
4604
+ maxItems: 50,
4605
+ type: 'array'
4606
+ },
4607
+ categoryKeywords: {
4608
+ items: {
4609
+ type: 'array'
4610
+ },
4611
+ maxItems: 50,
4612
+ type: 'array'
4613
+ },
4614
+ methodKeywords: {
4615
+ items: {
4616
+ type: 'array'
4617
+ },
4618
+ maxItems: 50,
4619
+ description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4620
+ type: 'array'
4621
+ },
4622
+ categoryAccount: {
4623
+ type: 'string',
4624
+ maxLength: 200,
4625
+ description:
4626
+ 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4627
+ },
4628
+ matchLogic: {
4629
+ type: 'string',
4630
+ enum: ['OR', 'AND'],
4631
+ default: 'OR'
4632
+ },
4633
+ amountMin: {
4634
+ type: 'number',
4635
+ minimum: 0,
4636
+ description: 'Minimum transaction amount (inclusive)'
4637
+ },
4638
+ amountMax: {
4639
+ type: 'number',
4640
+ minimum: 0,
4641
+ description: 'Maximum transaction amount (inclusive)'
4642
+ },
4643
+ priority: {
4644
+ type: 'number',
4645
+ default: 50,
4646
+ minimum: 0,
4647
+ maximum: 1000
4648
+ },
4649
+ additionalTags: {
4650
+ items: {
4651
+ type: 'array'
4652
+ },
4653
+ maxItems: 20,
4654
+ type: 'array'
4655
+ },
4656
+ additionalMetadata: {
4657
+ type: 'object'
4658
+ },
4659
+ upsertByPayee: {
4660
+ type: 'boolean',
4661
+ description:
4662
+ 'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
4663
+ }
4664
+ },
4665
+ required: ['name', 'matchLogic', 'priority']
4666
+ } as const;
4667
+
4668
+ export const $ValidateRuleResponseDto = {
4669
+ type: 'object',
4670
+ properties: {
4671
+ valid: {
4672
+ type: 'boolean',
4673
+ description: 'Whether the rule configuration is valid',
4674
+ example: true
4675
+ },
4676
+ errors: {
4677
+ description: 'List of validation errors (empty if valid)',
4678
+ example: [],
4679
+ items: {
4680
+ type: 'array'
4681
+ },
4682
+ type: 'array'
4683
+ },
4684
+ warnings: {
4685
+ description: 'List of validation warnings (non-blocking issues)',
4686
+ example: [
4687
+ 'No account constraints specified - rule will match any account'
4688
+ ],
4689
+ items: {
4690
+ type: 'array'
4691
+ },
4692
+ type: 'array'
4693
+ }
4694
+ },
4695
+ required: ['valid', 'errors', 'warnings']
4696
+ } as const;
4697
+
4698
+ export const $BulkCreateRulesDto = {
4699
+ type: 'object',
4700
+ properties: {
4701
+ rules: {
4702
+ items: {
4703
+ type: 'array'
4704
+ },
4705
+ description: 'Array of rules to import',
4706
+ type: 'array'
4707
+ },
4708
+ conflictStrategy: {
4709
+ type: 'string',
4710
+ enum: ['replace', 'skip'],
4711
+ default: 'skip',
4712
+ description:
4713
+ 'Conflict handling strategy: skip (default) ignores duplicates, replace soft-deletes existing rule'
4714
+ }
4715
+ },
4716
+ required: ['rules', 'conflictStrategy']
4717
+ } as const;
4718
+
4719
+ export const $BulkCreateRulesResponseDto = {
4720
+ type: 'object',
4721
+ properties: {
4722
+ successCount: {
4723
+ type: 'number',
4724
+ description: 'Number of successfully created rules'
4725
+ },
4726
+ failureCount: {
4727
+ type: 'number',
4728
+ description: 'Number of failed rules'
4729
+ },
4730
+ errors: {
4731
+ type: 'array',
4732
+ description: 'Error details for failed rules',
4733
+ items: {
4734
+ type: 'object',
4735
+ properties: {
4736
+ index: {
4737
+ type: 'number'
4738
+ },
4739
+ message: {
4740
+ type: 'string'
4741
+ }
4742
+ }
4743
+ }
4744
+ },
4745
+ createdRuleIds: {
4746
+ description: 'IDs of successfully created rules',
4747
+ type: 'array',
4748
+ items: {
4749
+ type: 'string'
4750
+ }
4751
+ }
4752
+ },
4753
+ required: ['successCount', 'failureCount', 'errors', 'createdRuleIds']
4754
+ } as const;
4755
+
4756
+ export const $ExportRulesResponseDto = {
4757
+ type: 'object',
4758
+ properties: {
4759
+ exportedAt: {
4760
+ type: 'string',
4761
+ description: 'Export timestamp'
4762
+ },
4763
+ userId: {
4764
+ type: 'string',
4765
+ description: 'User ID'
4766
+ },
4767
+ ruleCount: {
4768
+ type: 'number',
4769
+ description: 'Number of exported rules'
4770
+ },
4771
+ rules: {
4772
+ type: 'array',
4773
+ description: 'Exported rules'
4774
+ }
4775
+ },
4776
+ required: ['exportedAt', 'userId', 'ruleCount', 'rules']
4777
+ } as const;
4778
+
4779
+ export const $RuleStatisticsResponseDto = {
4780
+ type: 'object',
4781
+ properties: {
4782
+ period: {
4783
+ type: 'string',
4784
+ description: 'Statistics time period',
4785
+ enum: ['7d', '30d', '90d']
4786
+ },
4787
+ totalRules: {
4788
+ type: 'number',
4789
+ description: 'Total number of rules'
4790
+ },
4791
+ rulesWithMatches: {
4792
+ type: 'number',
4793
+ description: 'Number of rules with at least one match'
4794
+ },
4795
+ totalMatches: {
4796
+ type: 'number',
4797
+ description: 'Total number of matches across all rules'
4798
+ },
4799
+ averageConfidence: {
4800
+ type: 'number',
4801
+ description: 'Average confidence score across all matches',
4802
+ example: 0.82
4803
+ },
4804
+ ruleStats: {
4805
+ type: 'array',
4806
+ description: 'Per-rule statistics',
4807
+ items: {
4808
+ type: 'object',
4809
+ properties: {
4810
+ ruleId: {
4811
+ type: 'string'
4812
+ },
4813
+ ruleName: {
4814
+ type: 'string'
4815
+ },
4816
+ matchCount: {
4817
+ type: 'number'
4818
+ },
4819
+ averageConfidence: {
4820
+ type: 'number'
4821
+ }
4822
+ }
4823
+ }
4824
+ }
4825
+ },
4826
+ required: [
4827
+ 'period',
4828
+ 'totalRules',
4829
+ 'rulesWithMatches',
4830
+ 'totalMatches',
4831
+ 'averageConfidence',
4832
+ 'ruleStats'
4833
+ ]
4834
+ } as const;
4835
+
4836
+ export const $UpdateTransactionRuleDto = {
4837
+ type: 'object',
4838
+ properties: {
4839
+ name: {
4840
+ type: 'string',
4841
+ minLength: 1,
4842
+ maxLength: 100
4843
+ },
4844
+ description: {
4845
+ type: 'string',
4846
+ maxLength: 500
4847
+ },
4848
+ narrationKeywords: {
4849
+ items: {
4850
+ type: 'array'
4851
+ },
4852
+ maxItems: 50,
4853
+ type: 'array'
4854
+ },
4855
+ payeeKeywords: {
4856
+ items: {
4857
+ type: 'array'
4858
+ },
4859
+ maxItems: 50,
4860
+ type: 'array'
4861
+ },
4862
+ categoryKeywords: {
4863
+ items: {
4864
+ type: 'array'
4865
+ },
4866
+ maxItems: 50,
4867
+ type: 'array'
4868
+ },
4869
+ methodKeywords: {
4870
+ items: {
4871
+ type: 'array'
4872
+ },
4873
+ maxItems: 50,
4874
+ description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4875
+ type: 'array'
4876
+ },
4877
+ categoryAccount: {
4878
+ type: 'string',
4879
+ maxLength: 200,
4880
+ description:
4881
+ 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4882
+ },
4883
+ matchLogic: {
4884
+ type: 'string',
4885
+ enum: ['OR', 'AND']
4886
+ },
4887
+ amountMin: {
4888
+ type: 'number',
4889
+ minimum: 0,
4890
+ description: 'Minimum transaction amount (inclusive)'
4891
+ },
4892
+ amountMax: {
4893
+ type: 'number',
4894
+ minimum: 0,
4895
+ description: 'Maximum transaction amount (inclusive)'
4896
+ },
4897
+ priority: {
4898
+ type: 'number',
4899
+ minimum: 0,
4900
+ maximum: 1000
4901
+ },
4902
+ enabled: {
4903
+ type: 'boolean',
4904
+ description: 'Enable or disable the rule'
4905
+ },
4906
+ additionalTags: {
4907
+ items: {
4908
+ type: 'array'
4909
+ },
4910
+ maxItems: 20,
4911
+ type: 'array'
4912
+ },
4913
+ additionalMetadata: {
4914
+ type: 'object'
4915
+ }
4916
+ }
4917
+ } as const;
4918
+
4919
+ export const $TestRuleDto = {
4920
+ type: 'object',
4921
+ properties: {
4922
+ narration: {
4923
+ type: 'string',
4924
+ minLength: 1,
4925
+ maxLength: 500
4926
+ },
4927
+ payee: {
4928
+ type: 'string',
4929
+ maxLength: 200
4930
+ },
4931
+ categoryAccount: {
4932
+ type: 'string',
4933
+ maxLength: 200
4934
+ },
4935
+ amount: {
4936
+ type: 'number'
4937
+ },
4938
+ currency: {
4939
+ type: 'string',
4940
+ maxLength: 10
4941
+ }
4942
+ },
4943
+ required: ['narration']
4944
+ } as const;
4945
+
4946
+ export const $TestRuleResponseDto = {
4947
+ type: 'object',
4948
+ properties: {
4949
+ ruleId: {
4950
+ type: 'string',
4951
+ description: 'Rule ID that was tested'
4952
+ },
4953
+ matches: {
4954
+ type: 'boolean',
4955
+ description: 'Whether the rule matched the test data'
4956
+ },
4957
+ confidence: {
4958
+ type: 'number',
4959
+ description: 'Match confidence score (0-1)',
4960
+ example: 0.85
4961
+ },
4962
+ matchDetails: {
4963
+ type: 'object',
4964
+ description: 'Details of which fields matched',
4965
+ example: {
4966
+ narration: true,
4967
+ payee: false,
4968
+ categoryAccount: false
4969
+ }
4970
+ }
4971
+ },
4972
+ required: ['ruleId', 'matches', 'confidence', 'matchDetails']
4973
+ } as const;
4974
+
4975
+ export const $CategoryCatalogEntryDto = {
4976
+ type: 'object',
4977
+ properties: {
4978
+ slug: {
4979
+ type: 'string',
4980
+ description: 'Category slug (single source-of-truth)',
4981
+ example: 'food'
4982
+ },
4983
+ scenario: {
4984
+ type: 'string',
4985
+ description: 'Display scenario group (maps to frontend picker _scenario)',
4986
+ enum: [
4987
+ 'expense',
4988
+ 'income',
4989
+ 'investment',
4990
+ 'banking',
4991
+ 'transfer',
4992
+ 'payment'
4993
+ ],
4994
+ example: 'expense'
4995
+ },
4996
+ icon: {
4997
+ type: 'string',
4998
+ description: 'Lucide icon name',
4999
+ example: 'utensils'
5000
+ },
5001
+ regions: {
5002
+ description: "Applicable regions ('*' = all, 'cn' = CN-only)",
5003
+ example: ['*'],
5004
+ type: 'array',
5005
+ items: {
5006
+ type: 'string'
5007
+ }
5008
+ }
5009
+ },
5010
+ required: ['slug', 'scenario', 'icon', 'regions']
5011
+ } as const;
5012
+
5013
+ export const $CategoryCatalogListResponseDto = {
5014
+ type: 'object',
5015
+ properties: {
5016
+ items: {
5017
+ description: 'Category entries (region-scoped, query-filtered)',
5018
+ type: 'array',
5019
+ items: {
5020
+ $ref: '#/components/schemas/CategoryCatalogEntryDto'
5021
+ }
5022
+ },
5023
+ total: {
5024
+ type: 'number',
5025
+ description:
5026
+ 'Total category entries for the region (before query filtering)',
5027
+ example: 30
5028
+ },
5029
+ region: {
5030
+ type: 'string',
5031
+ description: 'Region code',
5032
+ example: 'cn'
5033
+ }
5034
+ },
5035
+ required: ['items', 'total', 'region']
5036
+ } as const;
5037
+
5038
+ export const $CreateBeanEventDto = {
5039
+ type: 'object',
5040
+ properties: {
5041
+ date: {
5042
+ type: 'string',
5043
+ description: 'Life event date (ISO 8601)',
5044
+ example: '2024-03-15'
5045
+ },
5046
+ type: {
5047
+ type: 'string',
5048
+ description:
5049
+ 'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
5050
+ example: 'employer'
5051
+ },
5052
+ description: {
5053
+ type: 'string',
5054
+ description:
5055
+ 'Life event description. Empty string is a VALID value (distinct from absence).',
5056
+ example: 'Acme Corp'
5057
+ },
5058
+ meta: {
5059
+ type: 'object',
5060
+ description:
5061
+ 'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
5062
+ example: {
5063
+ note: 'Promotion'
5064
+ }
5065
+ }
5066
+ },
5067
+ required: ['date', 'type', 'description']
5068
+ } as const;
5069
+
5070
+ export const $EventResponseDto = {
5071
+ type: 'object',
5072
+ properties: {
5073
+ id: {
5074
+ type: 'string',
5075
+ description: 'Unique identifier',
5076
+ example: 'uuid-123-456'
5077
+ },
5078
+ userId: {
5079
+ type: 'string',
5080
+ description: 'User ID (owner of the life event)',
5081
+ example: 'user-123'
5082
+ },
5083
+ date: {
5084
+ type: 'string',
5085
+ description: 'Life event date (ISO 8601 format)',
5086
+ example: '2024-03-15',
5087
+ format: 'date'
5088
+ },
5089
+ type: {
5090
+ type: 'string',
5091
+ description:
5092
+ 'Life event type (user-defined, e.g., "employer", "location")',
5093
+ example: 'employer'
5094
+ },
5095
+ description: {
5096
+ type: 'string',
5097
+ description:
5098
+ 'Life event description. May be an empty string (a valid value distinct from absence).',
5099
+ example: 'Acme Corp'
5100
+ },
5101
+ meta: {
5102
+ type: 'object',
5103
+ description: 'Product-side metadata (free-form JSON)',
5104
+ example: {
5105
+ note: 'Promotion'
5106
+ }
5107
+ },
5108
+ createdAt: {
5109
+ format: 'date-time',
5110
+ type: 'string',
5111
+ description: 'Creation timestamp',
5112
+ example: '2024-03-15T10:00:00Z'
5113
+ },
5114
+ updatedAt: {
5115
+ format: 'date-time',
5116
+ type: 'string',
5117
+ description:
5118
+ 'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
5119
+ example: '2024-03-15T10:00:00Z'
5120
+ }
5121
+ },
5122
+ required: [
5123
+ 'id',
5124
+ 'userId',
5125
+ 'date',
5126
+ 'type',
5127
+ 'description',
5128
+ 'meta',
5129
+ 'createdAt',
5130
+ 'updatedAt'
5131
+ ]
5132
+ } as const;
5133
+
5134
+ export const $EventListResponseDto = {
5135
+ type: 'object',
5136
+ properties: {
5137
+ items: {
5138
+ description: 'List of life events',
5139
+ type: 'array',
5140
+ items: {
5141
+ $ref: '#/components/schemas/EventResponseDto'
5142
+ }
5143
+ },
5144
+ total: {
5145
+ type: 'number',
5146
+ description: 'Total number of life events matching the query',
5147
+ example: 42
5148
+ }
5149
+ },
5150
+ required: ['items', 'total']
5151
+ } as const;
5152
+
5153
+ export const $UpdateBeanEventDto = {
5154
+ type: 'object',
5155
+ properties: {
5156
+ date: {
5157
+ type: 'string',
5158
+ description: 'Life event date (ISO 8601)'
5159
+ },
5160
+ type: {
5161
+ type: 'string',
5162
+ description: 'Life event type (user-defined)'
5163
+ },
5164
+ description: {
5165
+ type: 'string',
5166
+ description:
5167
+ 'Life event description. Empty string is a VALID value (distinct from absence).'
5168
+ },
5169
+ meta: {
5170
+ type: 'object',
5171
+ description: 'Product-side metadata (free-form JSON)'
5172
+ }
5173
+ }
5174
+ } as const;
5175
+
5176
+ export const $OnboardingAccountDto = {
5177
+ type: 'object',
5178
+ properties: {
5179
+ path: {
5180
+ type: 'string',
5181
+ description:
5182
+ 'Account path (Assets/Liabilities only; format validated by the account service)',
5183
+ example: 'Assets:Checking'
5184
+ },
5185
+ currency: {
5186
+ type: 'string',
5187
+ description: 'ISO 4217 currency code (3 letters)',
5188
+ example: 'USD'
5189
+ },
5190
+ openingBalance: {
5191
+ type: 'string',
5192
+ description:
5193
+ 'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
5194
+ example: '1000.00'
5195
+ },
5196
+ platformId: {
5197
+ type: 'string',
5198
+ description:
5199
+ 'Platform ID to bind the account to (references Platform.id); omit for unbound',
5200
+ example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
5201
+ }
5202
+ },
5203
+ required: ['path', 'currency']
5204
+ } as const;
5205
+
5206
+ export const $OnboardingDto = {
5207
+ type: 'object',
5208
+ properties: {
5209
+ accounts: {
5210
+ description: 'Asset/Liability accounts to register with opening balances',
5211
+ type: 'array',
5212
+ items: {
5213
+ $ref: '#/components/schemas/OnboardingAccountDto'
5214
+ }
5215
+ },
5216
+ skipAssetRegistration: {
5217
+ type: 'boolean',
5218
+ description:
5219
+ 'Skip asset registration; only bootstrap the core account set',
5220
+ default: false
5221
+ }
5222
+ }
5223
+ } as const;
5224
+
5225
+ export const $ActualBalanceDto = {
5226
+ type: 'object',
5227
+ properties: {
5228
+ amount: {
5229
+ type: 'string',
5230
+ description:
5231
+ 'Actual balance amount as a decimal string (preserves precision for tolerance inference).',
5232
+ example: '1234.56'
5233
+ },
5234
+ ccy: {
5235
+ type: 'string',
5236
+ description: 'Currency code (ISO 4217 or commodity ticker).',
5237
+ example: 'CNY'
5238
+ }
5239
+ },
5240
+ required: ['amount', 'ccy']
5241
+ } as const;
5242
+
5243
+ export const $ComputeReconciliationDto = {
5244
+ type: 'object',
5245
+ properties: {
5246
+ accountId: {
5247
+ type: 'string',
5248
+ description: 'BeanAccount id to reconcile.'
5249
+ },
5250
+ asOfDate: {
5251
+ type: 'string',
5252
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5253
+ example: '2026-07-24'
5254
+ },
5255
+ actualBalance: {
5256
+ description: 'Actual balance from the external statement.',
5257
+ allOf: [
5258
+ {
5259
+ $ref: '#/components/schemas/ActualBalanceDto'
5260
+ }
5261
+ ]
5262
+ }
5263
+ },
5264
+ required: ['accountId', 'asOfDate', 'actualBalance']
5265
+ } as const;
5266
+
5267
+ export const $ReconciliationComputeResultDto = {
5268
+ type: 'object',
5269
+ properties: {
5270
+ accountId: {
5271
+ type: 'string'
5272
+ },
5273
+ asOfDate: {
5274
+ type: 'string'
5275
+ },
5276
+ bookBalance: {
5277
+ type: 'string',
5278
+ description: 'System-computed book balance (decimal string).'
5279
+ },
5280
+ actualBalance: {
5281
+ type: 'string',
5282
+ description: 'User-entered actual balance (decimal string).'
5283
+ },
5284
+ currency: {
5285
+ type: 'string'
5286
+ },
5287
+ diff: {
5288
+ type: 'string',
5289
+ description: 'Diff = book − actual (decimal string).'
5290
+ },
5291
+ tolerance: {
5292
+ type: 'string',
5293
+ description: 'Applied tolerance (decimal string).'
5294
+ },
5295
+ withinTolerance: {
5296
+ type: 'boolean',
5297
+ description: 'true when |diff| ≤ tolerance.'
5298
+ },
5299
+ suggestedAction: {
5300
+ type: 'string',
5301
+ enum: ['assert', 'pad'],
5302
+ description:
5303
+ 'Suggested next action: assert when within tolerance, pad otherwise.'
5304
+ }
5305
+ },
5306
+ required: [
5307
+ 'accountId',
5308
+ 'asOfDate',
5309
+ 'bookBalance',
5310
+ 'actualBalance',
5311
+ 'currency',
5312
+ 'diff',
5313
+ 'tolerance',
5314
+ 'withinTolerance',
5315
+ 'suggestedAction'
5316
+ ]
5317
+ } as const;
5318
+
5319
+ export const $AssertReconciliationDto = {
5320
+ type: 'object',
5321
+ properties: {
5322
+ accountId: {
5323
+ type: 'string',
5324
+ description: 'BeanAccount id to reconcile.'
5325
+ },
5326
+ asOfDate: {
5327
+ type: 'string',
5328
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5329
+ example: '2026-07-24'
5330
+ },
5331
+ actualBalance: {
5332
+ description: 'Actual balance from the external statement.',
5333
+ allOf: [
5334
+ {
5335
+ $ref: '#/components/schemas/ActualBalanceDto'
5336
+ }
5337
+ ]
5338
+ },
5339
+ tolerance: {
5340
+ type: 'string',
5341
+ description:
5342
+ 'Optional explicit tolerance override. Omit to infer from amount precision (Beancount default).',
5343
+ example: '0.01'
5344
+ }
5345
+ },
5346
+ required: ['accountId', 'asOfDate', 'actualBalance']
5347
+ } as const;
5348
+
5349
+ export const $ReconciliationRecordDto = {
5350
+ type: 'object',
5351
+ properties: {
5352
+ id: {
5353
+ type: 'string'
5354
+ },
5355
+ accountId: {
5356
+ type: 'string'
5357
+ },
5358
+ date: {
5359
+ type: 'string'
5360
+ },
5361
+ amount: {
5362
+ type: 'string',
5363
+ description: 'Asserted (actual) amount.'
5364
+ },
5365
+ currency: {
5366
+ type: 'string'
5367
+ },
5368
+ tolerance: {
5369
+ type: 'string'
5370
+ },
5371
+ diffAmount: {
5372
+ type: 'string',
5373
+ description: 'book − actual.'
5374
+ },
5375
+ diffCurrency: {
5376
+ type: 'string'
5377
+ },
5378
+ createdAt: {
5379
+ type: 'string'
5380
+ }
5381
+ },
5382
+ required: ['id', 'accountId', 'date', 'amount', 'currency', 'createdAt']
5383
+ } as const;
5384
+
5385
+ export const $PadReconciliationDto = {
5386
+ type: 'object',
5387
+ properties: {
5388
+ accountId: {
5389
+ type: 'string',
5390
+ description: 'BeanAccount id to reconcile.'
5391
+ },
5392
+ asOfDate: {
5393
+ type: 'string',
5394
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
5395
+ example: '2026-07-24'
5396
+ },
5397
+ actualBalance: {
5398
+ description: 'Actual balance from the external statement.',
5399
+ allOf: [
5400
+ {
5401
+ $ref: '#/components/schemas/ActualBalanceDto'
5402
+ }
5403
+ ]
5404
+ },
5405
+ sourceAccount: {
5406
+ type: 'string',
5407
+ description:
5408
+ 'Pad source account. Defaults to Equity:Opening-Balances (official Beancount convention).',
5409
+ example: 'Equity:Opening-Balances',
5410
+ default: 'Equity:Opening-Balances'
5411
+ }
5412
+ },
5413
+ required: ['accountId', 'asOfDate', 'actualBalance']
5414
+ } as const;
5415
+
5416
+ export const $PadResultDto = {
5417
+ type: 'object',
5418
+ properties: {
5419
+ transactionId: {
5420
+ type: 'string',
5421
+ description: 'Created pad adjusting transaction id.'
5422
+ }
5423
+ },
5424
+ required: ['transactionId']
5425
+ } as const;
5426
+
5427
+ export const $FileImportDto = {
5428
+ type: 'object',
5429
+ properties: {
5430
+ file: {
5431
+ type: 'string',
5432
+ format: 'binary',
5433
+ description: 'Bill file to import (CSV, PDF, OFX, etc.)',
5434
+ example: 'alipay.csv'
5435
+ }
5436
+ },
5437
+ required: ['file']
5438
+ } as const;
5439
+
5440
+ export const $ImportErrorDto = {
5441
+ type: 'object',
5442
+ properties: {
5443
+ index: {
5444
+ type: 'number',
5445
+ description: 'Index of failed transaction in the file',
5446
+ example: 5
5447
+ },
5448
+ error: {
5449
+ type: 'string',
5450
+ description: 'Error message',
5451
+ example: 'Transaction does not balance: -100 USD != 0'
5452
+ }
5453
+ },
5454
+ required: ['index', 'error']
5455
+ } as const;
5456
+
5457
+ export const $ReviewItemPreviewDto = {
5458
+ type: 'object',
5459
+ properties: {
5460
+ index: {
5461
+ type: 'number',
5462
+ description: 'Index in the import batch (for tracking)',
5463
+ example: 0
5464
+ },
5465
+ date: {
5466
+ type: 'string',
5467
+ description: 'Transaction date (ISO format)',
5468
+ example: '2026-03-05'
5469
+ },
5470
+ amount: {
5471
+ type: 'number',
5472
+ description: 'Transaction amount (absolute value)',
5473
+ example: 99
5474
+ },
5475
+ currency: {
5476
+ type: 'string',
5477
+ description: 'Currency code',
5478
+ example: 'CNY'
5479
+ },
5480
+ narration: {
5481
+ type: 'string',
5482
+ description: 'Transaction narration/description',
5483
+ example: 'Restaurant expense'
5484
+ },
5485
+ payee: {
5486
+ type: 'string',
5487
+ description: 'Payee name',
5488
+ example: 'Restaurant ABC'
5489
+ },
5490
+ category: {
5491
+ type: 'string',
5492
+ description: 'Inferred category from rule matching',
5493
+ example: 'food'
5494
+ },
4383
5495
  confidence: {
4384
5496
  type: 'number',
4385
5497
  description: 'Confidence score for the match (0-1)',
@@ -4478,7 +5590,7 @@ export const $IdentifyResultDto = {
4478
5590
  account: {
4479
5591
  type: 'string',
4480
5592
  description: 'Default account used by this importer',
4481
- example: 'Assets:Alipay:Balance'
5593
+ example: 'Assets:CN:Alipay:Balance'
4482
5594
  },
4483
5595
  message: {
4484
5596
  type: 'string',
@@ -4495,7 +5607,7 @@ export const $MapperDefaultsDto = {
4495
5607
  sourceAccount: {
4496
5608
  type: 'string',
4497
5609
  description: 'Source account for transactions (Beancount format)',
4498
- example: 'Assets:Alipay:Balance'
5610
+ example: 'Assets:CN:Alipay:Balance'
4499
5611
  },
4500
5612
  currency: {
4501
5613
  type: 'string',
@@ -4532,7 +5644,7 @@ export const $MapperDefaultsDto = {
4532
5644
  description:
4533
5645
  '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).',
4534
5646
  example: {
4535
- HuaBei: 'Liabilities:Alipay:Huabei',
5647
+ HuaBei: 'Liabilities:CN:CreditLine',
4536
5648
  CreditCard: 'Liabilities:CreditCard'
4537
5649
  }
4538
5650
  }
@@ -4664,8 +5776,9 @@ export const $UpdateMapperDefaultsDto = {
4664
5776
  sourceAccount: {
4665
5777
  type: 'string',
4666
5778
  description: 'Source account for transactions (Beancount format)',
4667
- example: 'Assets:Alipay:Balance',
4668
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5779
+ example: 'Assets:CN:Alipay:Balance',
5780
+ pattern:
5781
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4669
5782
  },
4670
5783
  currency: {
4671
5784
  type: 'string',
@@ -4679,20 +5792,22 @@ export const $UpdateMapperDefaultsDto = {
4679
5792
  type: 'string',
4680
5793
  description: 'Default expense account (optional)',
4681
5794
  example: 'Expenses:Unknown',
4682
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5795
+ pattern:
5796
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4683
5797
  },
4684
5798
  incomeAccount: {
4685
5799
  type: 'string',
4686
5800
  description: 'Default income account (optional)',
4687
5801
  example: 'Income:Unknown',
4688
- pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
5802
+ pattern:
5803
+ '^(Assets|Liabilities|Income|Expenses|Equity)(:[A-Za-z0-9][A-Za-z0-9-]*)+$'
4689
5804
  },
4690
5805
  methodAccountMapping: {
4691
5806
  type: 'object',
4692
5807
  description:
4693
5808
  '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).',
4694
5809
  example: {
4695
- HuaBei: 'Liabilities:Alipay:Huabei',
5810
+ HuaBei: 'Liabilities:CN:CreditLine',
4696
5811
  CreditCard: 'Liabilities:CreditCard'
4697
5812
  }
4698
5813
  }
@@ -4727,119 +5842,13 @@ export const $UpdateImporterConfigDto = {
4727
5842
  }
4728
5843
  } as const;
4729
5844
 
4730
- export const $CreatePlatformDto = {
4731
- type: 'object',
4732
- properties: {
4733
- name: {
4734
- type: 'string',
4735
- description: 'Platform name',
4736
- example: 'Binance'
4737
- },
4738
- canonical: {
4739
- type: 'string',
4740
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4741
- example: 'binance'
4742
- },
4743
- aliases: {
4744
- description: 'Platform aliases (multi-language names for lookup)',
4745
- example: ['Binance', 'Binance Exchange', 'BNB'],
4746
- type: 'array',
4747
- items: {
4748
- type: 'string'
4749
- }
4750
- },
4751
- url: {
4752
- type: 'string',
4753
- description: 'Platform URL',
4754
- example: 'https://www.binance.com'
4755
- },
4756
- type: {
4757
- type: 'string',
4758
- description: 'Platform type',
4759
- enum: [
4760
- 'BANK',
4761
- 'BROKERAGE',
4762
- 'CRYPTO_EXCHANGE',
4763
- 'PAYMENT',
4764
- 'INVESTMENT',
4765
- 'INSURANCE',
4766
- 'OTHER'
4767
- ],
4768
- example: 'CRYPTO_EXCHANGE'
4769
- },
4770
- logoUrl: {
4771
- type: 'string',
4772
- description: 'Platform logo URL',
4773
- example: 'https://example.com/logos/binance.png'
4774
- },
4775
- isActive: {
4776
- type: 'boolean',
4777
- description: 'Whether the platform is active',
4778
- default: true
4779
- }
4780
- },
4781
- required: ['name', 'canonical', 'aliases', 'url', 'type']
4782
- } as const;
4783
-
4784
- export const $UpdatePlatformDto = {
4785
- type: 'object',
4786
- properties: {
4787
- name: {
4788
- type: 'string',
4789
- description: 'Platform name',
4790
- example: 'Binance'
4791
- },
4792
- canonical: {
4793
- type: 'string',
4794
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4795
- example: 'binance'
4796
- },
4797
- aliases: {
4798
- description: 'Platform aliases (multi-language names for lookup)',
4799
- example: ['Binance', 'Binance Exchange', 'BNB'],
4800
- type: 'array',
4801
- items: {
4802
- type: 'string'
4803
- }
4804
- },
4805
- url: {
4806
- type: 'string',
4807
- description: 'Platform URL',
4808
- example: 'https://www.binance.com'
4809
- },
4810
- type: {
4811
- type: 'string',
4812
- description: 'Platform type',
4813
- enum: [
4814
- 'BANK',
4815
- 'BROKERAGE',
4816
- 'CRYPTO_EXCHANGE',
4817
- 'PAYMENT',
4818
- 'INVESTMENT',
4819
- 'INSURANCE',
4820
- 'OTHER'
4821
- ],
4822
- example: 'CRYPTO_EXCHANGE'
4823
- },
4824
- logoUrl: {
4825
- type: 'string',
4826
- description: 'Platform logo URL',
4827
- example: 'https://example.com/logos/binance.png'
4828
- },
4829
- isActive: {
4830
- type: 'boolean',
4831
- description: 'Whether the platform is active'
4832
- }
4833
- }
4834
- } as const;
4835
-
4836
5845
  export const $ProviderSyncConfigDto = {
4837
5846
  type: 'object',
4838
5847
  properties: {
4839
5848
  sourceAccount: {
4840
5849
  type: 'string',
4841
5850
  description: 'Source account for the first posting',
4842
- example: 'Assets:Bank:Chase'
5851
+ example: 'Assets:US:Chase:Checking'
4843
5852
  },
4844
5853
  defaultCurrency: {
4845
5854
  type: 'string',
@@ -4848,26 +5857,29 @@ export const $ProviderSyncConfigDto = {
4848
5857
  },
4849
5858
  defaultExpenseAccount: {
4850
5859
  type: 'string',
4851
- description: 'Default expense account for the second posting',
5860
+ description:
5861
+ 'Default expense account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4852
5862
  example: 'Expenses:Unknown'
4853
5863
  },
4854
5864
  defaultIncomeAccount: {
4855
5865
  type: 'string',
4856
- description: 'Default income account for the second posting',
5866
+ description:
5867
+ 'Default income account for the second posting. Omit when no real default exists; the pipeline routes to Review via the Uncategorized sentinel (#618).',
4857
5868
  example: 'Income:Unknown'
4858
5869
  },
4859
5870
  filterPending: {
4860
5871
  type: 'boolean',
4861
5872
  description: 'Filter pending transactions',
4862
5873
  default: true
5874
+ },
5875
+ externalAccountId: {
5876
+ type: 'string',
5877
+ description:
5878
+ 'External account ID for per-batch providers (e.g. GoCardless). Overrides sourceAccount when an ExternalAccountLink mapping exists.',
5879
+ example: 'acc_gocardless_001'
4863
5880
  }
4864
5881
  },
4865
- required: [
4866
- 'sourceAccount',
4867
- 'defaultCurrency',
4868
- 'defaultExpenseAccount',
4869
- 'defaultIncomeAccount'
4870
- ]
5882
+ required: ['sourceAccount', 'defaultCurrency']
4871
5883
  } as const;
4872
5884
 
4873
5885
  export const $ProviderSyncDto = {
@@ -4975,18 +5987,189 @@ export const $SupportedProvidersResponseDto = {
4975
5987
  type: 'string'
4976
5988
  }
4977
5989
  }
4978
- },
4979
- required: ['providers']
4980
- } as const;
4981
-
4982
- export const $ParserTelemetryReportDto = {
4983
- type: 'object',
4984
- properties: {}
4985
- } as const;
4986
-
4987
- export const $UncoveredFormatMissDto = {
4988
- type: 'object',
4989
- properties: {}
5990
+ },
5991
+ required: ['providers']
5992
+ } as const;
5993
+
5994
+ export const $CreateExternalAccountLinkDto = {
5995
+ type: 'object',
5996
+ properties: {
5997
+ provider: {
5998
+ type: 'string',
5999
+ enum: [
6000
+ 'plaid',
6001
+ 'teller',
6002
+ 'truelayer',
6003
+ 'gocardless',
6004
+ 'simplefin',
6005
+ 'yodlee',
6006
+ 'beancount-direct',
6007
+ 'parsed-bill'
6008
+ ],
6009
+ example: 'plaid',
6010
+ description: 'Open Banking provider (whitelist)'
6011
+ },
6012
+ externalAccountId: {
6013
+ type: 'string',
6014
+ example: 'acc-plaid-001',
6015
+ description: 'External account ID from the provider'
6016
+ },
6017
+ beanAccountId: {
6018
+ type: 'string',
6019
+ example: '550e8400-e29b-41d4-a716-446655440000',
6020
+ description: 'Target BeanAccount ID (must belong to the JWT user)'
6021
+ }
6022
+ },
6023
+ required: ['provider', 'externalAccountId', 'beanAccountId']
6024
+ } as const;
6025
+
6026
+ export const $ExternalAccountLinkResponseDto = {
6027
+ type: 'object',
6028
+ properties: {
6029
+ id: {
6030
+ type: 'string'
6031
+ },
6032
+ provider: {
6033
+ type: 'string'
6034
+ },
6035
+ externalAccountId: {
6036
+ type: 'string'
6037
+ },
6038
+ beanAccountId: {
6039
+ type: 'string'
6040
+ },
6041
+ isActive: {
6042
+ type: 'boolean'
6043
+ },
6044
+ createdAt: {
6045
+ type: 'string'
6046
+ },
6047
+ updatedAt: {
6048
+ type: 'string'
6049
+ }
6050
+ },
6051
+ required: [
6052
+ 'id',
6053
+ 'provider',
6054
+ 'externalAccountId',
6055
+ 'beanAccountId',
6056
+ 'isActive',
6057
+ 'createdAt',
6058
+ 'updatedAt'
6059
+ ]
6060
+ } as const;
6061
+
6062
+ export const $ExternalAccountLinkListResponseDto = {
6063
+ type: 'object',
6064
+ properties: {
6065
+ items: {
6066
+ type: 'array',
6067
+ items: {
6068
+ $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
6069
+ }
6070
+ },
6071
+ total: {
6072
+ type: 'number'
6073
+ },
6074
+ provider: {
6075
+ type: 'string',
6076
+ description: 'Filter by provider (query param)'
6077
+ }
6078
+ },
6079
+ required: ['items', 'total']
6080
+ } as const;
6081
+
6082
+ export const $ParserTelemetryReportDto = {
6083
+ type: 'object',
6084
+ properties: {}
6085
+ } as const;
6086
+
6087
+ export const $UncoveredFormatMissDto = {
6088
+ type: 'object',
6089
+ properties: {}
6090
+ } as const;
6091
+
6092
+ export const $ClientParsedDataDto = {
6093
+ type: 'object',
6094
+ properties: {
6095
+ amount: {
6096
+ type: 'number',
6097
+ description: 'Transaction amount',
6098
+ example: 35
6099
+ },
6100
+ currency: {
6101
+ type: 'string',
6102
+ description: 'Currency code',
6103
+ example: 'CNY'
6104
+ },
6105
+ date: {
6106
+ type: 'string',
6107
+ description: 'Transaction date (ISO 8601)',
6108
+ example: '2026-08-15'
6109
+ },
6110
+ payee: {
6111
+ type: 'string',
6112
+ description: 'Payee/merchant name',
6113
+ example: 'Starbucks'
6114
+ },
6115
+ narration: {
6116
+ type: 'string',
6117
+ description: 'Transaction narration'
6118
+ },
6119
+ category: {
6120
+ type: 'string',
6121
+ description: 'Category slug',
6122
+ example: 'food_restaurant'
6123
+ },
6124
+ incomeType: {
6125
+ type: 'string',
6126
+ description: 'Income type',
6127
+ example: 'Salary'
6128
+ },
6129
+ incomeSource: {
6130
+ type: 'string',
6131
+ description: 'Income source',
6132
+ example: 'Anthropic Inc.'
6133
+ },
6134
+ symbol: {
6135
+ type: 'string',
6136
+ description: 'Security symbol code (e.g., 600519, AAPL)',
6137
+ example: 'AAPL'
6138
+ },
6139
+ quantity: {
6140
+ type: 'number',
6141
+ description: 'Quantity of shares/units',
6142
+ example: 100
6143
+ },
6144
+ price: {
6145
+ type: 'number',
6146
+ description: 'Unit price per share/unit',
6147
+ example: 1900
6148
+ },
6149
+ investmentAction: {
6150
+ type: 'string',
6151
+ description: 'Investment action',
6152
+ enum: ['buy', 'sell'],
6153
+ example: 'buy'
6154
+ },
6155
+ paymentSource: {
6156
+ type: 'string',
6157
+ description: 'Payment source: asset (default) or liability (credit card)',
6158
+ enum: ['asset', 'liability'],
6159
+ example: 'asset'
6160
+ },
6161
+ liabilityHint: {
6162
+ type: 'string',
6163
+ description: 'Liability account hint (CreditCard/Huabei/Baitiao)',
6164
+ example: 'CreditCard'
6165
+ },
6166
+ warning: {
6167
+ type: 'string',
6168
+ description:
6169
+ 'Display-only warning from the prior response; accepted but ignored.',
6170
+ example: 'Cross-currency settlement applies.'
6171
+ }
6172
+ }
4990
6173
  } as const;
4991
6174
 
4992
6175
  export const $ProcessNlpDto = {
@@ -4994,10 +6177,17 @@ export const $ProcessNlpDto = {
4994
6177
  properties: {
4995
6178
  message: {
4996
6179
  type: 'string',
4997
- description: 'Natural language text describing a transaction (Chinese)',
4998
- example: 'yesterday Starbucks spent 35 yuan',
6180
+ description:
6181
+ 'Natural language text describing a transaction. Optional when `confirm` is true (structured confirm); otherwise required.',
6182
+ example: 'Starbucks 35',
4999
6183
  maxLength: 500
5000
6184
  },
6185
+ confirm: {
6186
+ type: 'boolean',
6187
+ description:
6188
+ 'Structured confirm signal — bypasses NL confirm-word matching when true. Send parsedData field edits alongside. The NL word-list path is the fallback.',
6189
+ example: true
6190
+ },
5001
6191
  sessionId: {
5002
6192
  type: 'string',
5003
6193
  description:
@@ -5005,17 +6195,32 @@ export const $ProcessNlpDto = {
5005
6195
  example: 'session_abc123'
5006
6196
  },
5007
6197
  parsedData: {
5008
- type: 'object',
5009
6198
  description:
5010
6199
  'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
5011
6200
  example: {
5012
6201
  amount: 35,
5013
6202
  currency: 'CNY',
5014
6203
  payee: 'Starbucks'
5015
- }
6204
+ },
6205
+ allOf: [
6206
+ {
6207
+ $ref: '#/components/schemas/ClientParsedDataDto'
6208
+ }
6209
+ ]
6210
+ },
6211
+ selectedRuleId: {
6212
+ type: 'string',
6213
+ description:
6214
+ '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.',
6215
+ example: 'rule_abc123'
6216
+ },
6217
+ selectedAccount: {
6218
+ type: 'string',
6219
+ description:
6220
+ '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.',
6221
+ example: 'Expenses:Food:Coffee'
5016
6222
  }
5017
- },
5018
- required: ['message']
6223
+ }
5019
6224
  } as const;
5020
6225
 
5021
6226
  export const $NlpTransactionInfoDto = {
@@ -5337,7 +6542,8 @@ export const $NlpAccountConfirmationDataDto = {
5337
6542
  },
5338
6543
  suggestedAccount: {
5339
6544
  type: 'string',
5340
- description: 'Suggested replacement account',
6545
+ description:
6546
+ 'Suggested replacement account (omitted when no clear candidate)',
5341
6547
  example: 'Expenses:Food:Drinks'
5342
6548
  },
5343
6549
  similarAccounts: {
@@ -5359,7 +6565,6 @@ export const $NlpAccountConfirmationDataDto = {
5359
6565
  },
5360
6566
  required: [
5361
6567
  'invalidAccount',
5362
- 'suggestedAccount',
5363
6568
  'similarAccounts',
5364
6569
  'errorMessage',
5365
6570
  'transactionContext'
@@ -5528,11 +6733,12 @@ export const $NlpSuggestedAccountDto = {
5528
6733
  account: {
5529
6734
  type: 'string',
5530
6735
  description: 'Suggested account path',
5531
- example: 'Assets:Bank:Checking'
6736
+ example: 'Assets:Checking'
5532
6737
  },
5533
6738
  confidence: {
5534
6739
  type: 'number',
5535
- description: 'Confidence score for this suggestion (0-1)',
6740
+ description:
6741
+ 'Confidence score for this suggestion (0-1). Present = predicted (confirm/confirm_rule/confirm_account); omitted = actual persisted account (created). (#586)',
5536
6742
  example: 0.9
5537
6743
  }
5538
6744
  },
@@ -5568,23 +6774,31 @@ export const $NlpDefaultAccountsDto = {
5568
6774
  properties: {
5569
6775
  asset: {
5570
6776
  type: 'string',
5571
- description: 'Default asset account',
5572
- example: 'Assets:Bank:Checking'
6777
+ description:
6778
+ 'Default OPEN asset account (MRU when multiple), or null when none/ambiguous',
6779
+ example: 'Assets:Checking',
6780
+ nullable: true
5573
6781
  },
5574
6782
  expense: {
5575
6783
  type: 'string',
5576
- description: 'Default expense account',
5577
- example: 'Expenses:Uncategorized'
6784
+ description:
6785
+ 'Default OPEN expense account (MRU when multiple), or null when none/ambiguous',
6786
+ example: 'Expenses:Food:Coffee',
6787
+ nullable: true
5578
6788
  },
5579
6789
  income: {
5580
6790
  type: 'string',
5581
- description: 'Default income account',
5582
- example: 'Income:Uncategorized'
6791
+ description:
6792
+ 'Default OPEN income account (MRU when multiple), or null when none/ambiguous',
6793
+ example: 'Income:Salary',
6794
+ nullable: true
5583
6795
  },
5584
6796
  liability: {
5585
6797
  type: 'string',
5586
- description: 'Default liability account',
5587
- example: 'Liabilities:CreditCard'
6798
+ description:
6799
+ 'Default OPEN liability account (MRU when multiple), or null when none/ambiguous',
6800
+ example: 'Liabilities:CreditCard',
6801
+ nullable: true
5588
6802
  }
5589
6803
  },
5590
6804
  required: ['asset', 'expense', 'income', 'liability']
@@ -5609,7 +6823,8 @@ export const $NlpResponseDto = {
5609
6823
  'confirm_rule',
5610
6824
  'confirm_account',
5611
6825
  'confirm_payee',
5612
- 'cancel'
6826
+ 'cancel',
6827
+ 'aborted'
5613
6828
  ]
5614
6829
  },
5615
6830
  intent: {
@@ -5771,7 +6986,7 @@ export const $NlpResponseDto = {
5771
6986
  },
5772
6987
  suggestedAccounts: {
5773
6988
  description:
5774
- 'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
6989
+ '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.',
5775
6990
  allOf: [
5776
6991
  {
5777
6992
  $ref: '#/components/schemas/NlpSuggestedAccountsDto'
@@ -5780,7 +6995,7 @@ export const $NlpResponseDto = {
5780
6995
  },
5781
6996
  defaultAccounts: {
5782
6997
  description:
5783
- 'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
6998
+ 'Default fallback accounts for the user/region (#586). v1 returns universal constants; per-user personalization is planned.',
5784
6999
  allOf: [
5785
7000
  {
5786
7001
  $ref: '#/components/schemas/NlpDefaultAccountsDto'
@@ -5788,24 +7003,285 @@ export const $NlpResponseDto = {
5788
7003
  ]
5789
7004
  }
5790
7005
  },
5791
- required: ['status', 'action']
7006
+ required: ['status', 'action']
7007
+ } as const;
7008
+
7009
+ export const $PlatformListItemDto = {
7010
+ type: 'object',
7011
+ properties: {
7012
+ id: {
7013
+ type: 'string',
7014
+ description: 'Global platform ID'
7015
+ },
7016
+ name: {
7017
+ type: 'string',
7018
+ description: 'Platform name'
7019
+ },
7020
+ url: {
7021
+ type: 'string',
7022
+ description: 'Platform URL'
7023
+ },
7024
+ type: {
7025
+ type: 'string',
7026
+ description: 'Platform type',
7027
+ enum: [
7028
+ 'BANK',
7029
+ 'BROKERAGE',
7030
+ 'CRYPTO_EXCHANGE',
7031
+ 'PAYMENT',
7032
+ 'INVESTMENT',
7033
+ 'INSURANCE',
7034
+ 'OTHER'
7035
+ ]
7036
+ },
7037
+ canonical: {
7038
+ type: 'string',
7039
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
7040
+ },
7041
+ suggestedSegment: {
7042
+ type: 'string',
7043
+ description:
7044
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
7045
+ },
7046
+ logoUrl: {
7047
+ type: 'string',
7048
+ description: 'Logo URL',
7049
+ nullable: true
7050
+ },
7051
+ countryCode: {
7052
+ type: 'string',
7053
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
7054
+ example: 'CN',
7055
+ nullable: true
7056
+ },
7057
+ category: {
7058
+ type: 'string',
7059
+ description:
7060
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
7061
+ nullable: true,
7062
+ example: 'DigitalWallet'
7063
+ },
7064
+ isBound: {
7065
+ type: 'boolean',
7066
+ description: 'Whether user has accounts using this platform'
7067
+ }
7068
+ },
7069
+ required: [
7070
+ 'id',
7071
+ 'name',
7072
+ 'url',
7073
+ 'type',
7074
+ 'canonical',
7075
+ 'suggestedSegment',
7076
+ 'logoUrl',
7077
+ 'countryCode',
7078
+ 'category',
7079
+ 'isBound'
7080
+ ]
7081
+ } as const;
7082
+
7083
+ export const $PlatformMatchResultDto = {
7084
+ type: 'object',
7085
+ properties: {
7086
+ id: {
7087
+ type: 'string',
7088
+ description: 'Global platform ID'
7089
+ },
7090
+ name: {
7091
+ type: 'string',
7092
+ description: 'Platform name (e.g., "ICBC")'
7093
+ },
7094
+ canonical: {
7095
+ type: 'string',
7096
+ description: 'Canonical identifier in ACCOUNT_RE format (e.g., "icbc")'
7097
+ },
7098
+ type: {
7099
+ type: 'string',
7100
+ description: 'Platform type',
7101
+ enum: [
7102
+ 'BANK',
7103
+ 'BROKERAGE',
7104
+ 'CRYPTO_EXCHANGE',
7105
+ 'PAYMENT',
7106
+ 'INVESTMENT',
7107
+ 'INSURANCE',
7108
+ 'OTHER'
7109
+ ]
7110
+ },
7111
+ suggestedSegment: {
7112
+ type: 'string',
7113
+ description:
7114
+ 'Suggested path segment — canonical PascalCased per hyphen-part, hyphens preserved (e.g. "Apple-Pay")'
7115
+ },
7116
+ logoUrl: {
7117
+ type: 'string',
7118
+ description: 'Logo URL',
7119
+ nullable: true
7120
+ },
7121
+ countryCode: {
7122
+ type: 'string',
7123
+ description: 'ISO 3166-1 alpha-2 (UPPERCASE); null = global platform',
7124
+ example: 'CN',
7125
+ nullable: true
7126
+ },
7127
+ category: {
7128
+ type: 'string',
7129
+ description:
7130
+ 'Region-aware category (institution vocab, e.g. DigitalWallet/Bank). null = no region-aware suggestion; fall back to type.',
7131
+ nullable: true,
7132
+ example: 'DigitalWallet'
7133
+ },
7134
+ matchType: {
7135
+ type: 'string',
7136
+ description: "How this row matched: 'exact' > 'prefix' > 'substring'",
7137
+ enum: ['exact', 'prefix', 'substring']
7138
+ }
7139
+ },
7140
+ required: [
7141
+ 'id',
7142
+ 'name',
7143
+ 'canonical',
7144
+ 'type',
7145
+ 'suggestedSegment',
7146
+ 'logoUrl',
7147
+ 'countryCode',
7148
+ 'category',
7149
+ 'matchType'
7150
+ ]
7151
+ } as const;
7152
+
7153
+ export const $PlatformMatchResponseDto = {
7154
+ type: 'object',
7155
+ properties: {
7156
+ platforms: {
7157
+ description: 'Ranked matches, best tier first (at most 10 rows)',
7158
+ type: 'array',
7159
+ items: {
7160
+ $ref: '#/components/schemas/PlatformMatchResultDto'
7161
+ }
7162
+ },
7163
+ matchType: {
7164
+ type: 'string',
7165
+ description:
7166
+ "Overall match quality — top row's tier, or 'none' when no hits",
7167
+ enum: ['none', 'exact', 'prefix', 'substring']
7168
+ },
7169
+ total: {
7170
+ type: 'number',
7171
+ description: 'Total matches before LIMIT (truncation transparency)'
7172
+ },
7173
+ hasMore: {
7174
+ type: 'boolean',
7175
+ description: 'true when total > platforms.length (more matches exist)'
7176
+ }
7177
+ },
7178
+ required: ['platforms', 'matchType', 'total', 'hasMore']
7179
+ } as const;
7180
+
7181
+ export const $CreatePlatformDto = {
7182
+ type: 'object',
7183
+ properties: {
7184
+ name: {
7185
+ type: 'string',
7186
+ description: 'Platform name',
7187
+ example: 'Binance'
7188
+ },
7189
+ canonical: {
7190
+ type: 'string',
7191
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
7192
+ example: 'binance'
7193
+ },
7194
+ aliases: {
7195
+ description: 'Platform aliases (multi-language names for lookup)',
7196
+ example: ['Binance', 'Binance Exchange', 'BNB'],
7197
+ type: 'array',
7198
+ items: {
7199
+ type: 'string'
7200
+ }
7201
+ },
7202
+ url: {
7203
+ type: 'string',
7204
+ description: 'Platform URL',
7205
+ example: 'https://www.binance.com'
7206
+ },
7207
+ type: {
7208
+ type: 'string',
7209
+ description: 'Platform type',
7210
+ enum: [
7211
+ 'BANK',
7212
+ 'BROKERAGE',
7213
+ 'CRYPTO_EXCHANGE',
7214
+ 'PAYMENT',
7215
+ 'INVESTMENT',
7216
+ 'INSURANCE',
7217
+ 'OTHER'
7218
+ ],
7219
+ example: 'CRYPTO_EXCHANGE'
7220
+ },
7221
+ logoUrl: {
7222
+ type: 'string',
7223
+ description: 'Platform logo URL',
7224
+ example: 'https://example.com/logos/binance.png'
7225
+ },
7226
+ isActive: {
7227
+ type: 'boolean',
7228
+ description: 'Whether the platform is active',
7229
+ default: true
7230
+ }
7231
+ },
7232
+ required: ['name', 'canonical', 'aliases', 'url', 'type']
5792
7233
  } as const;
5793
7234
 
5794
- export const $BalanceByCurrencyDto = {
7235
+ export const $UpdatePlatformDto = {
5795
7236
  type: 'object',
5796
7237
  properties: {
5797
- currency: {
7238
+ name: {
5798
7239
  type: 'string',
5799
- description: 'ISO 4217 currency code',
5800
- example: 'CNY'
7240
+ description: 'Platform name',
7241
+ example: 'Binance'
5801
7242
  },
5802
- balance: {
7243
+ canonical: {
5803
7244
  type: 'string',
5804
- description: 'Balance amount',
5805
- example: '50000.00'
7245
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
7246
+ example: 'binance'
7247
+ },
7248
+ aliases: {
7249
+ description: 'Platform aliases (multi-language names for lookup)',
7250
+ example: ['Binance', 'Binance Exchange', 'BNB'],
7251
+ type: 'array',
7252
+ items: {
7253
+ type: 'string'
7254
+ }
7255
+ },
7256
+ url: {
7257
+ type: 'string',
7258
+ description: 'Platform URL',
7259
+ example: 'https://www.binance.com'
7260
+ },
7261
+ type: {
7262
+ type: 'string',
7263
+ description: 'Platform type',
7264
+ enum: [
7265
+ 'BANK',
7266
+ 'BROKERAGE',
7267
+ 'CRYPTO_EXCHANGE',
7268
+ 'PAYMENT',
7269
+ 'INVESTMENT',
7270
+ 'INSURANCE',
7271
+ 'OTHER'
7272
+ ],
7273
+ example: 'CRYPTO_EXCHANGE'
7274
+ },
7275
+ logoUrl: {
7276
+ type: 'string',
7277
+ description: 'Platform logo URL',
7278
+ example: 'https://example.com/logos/binance.png'
7279
+ },
7280
+ isActive: {
7281
+ type: 'boolean',
7282
+ description: 'Whether the platform is active'
5806
7283
  }
5807
- },
5808
- required: ['currency', 'balance']
7284
+ }
5809
7285
  } as const;
5810
7286
 
5811
7287
  export const $NetWorthByCurrencyDto = {
@@ -5877,28 +7353,6 @@ export const $ConvertedNetWorthDto = {
5877
7353
  ]
5878
7354
  } as const;
5879
7355
 
5880
- export const $ExchangeRateWarningDto = {
5881
- type: 'object',
5882
- properties: {
5883
- type: {
5884
- type: 'string',
5885
- description: 'Warning type',
5886
- example: 'MISSING_EXCHANGE_RATE'
5887
- },
5888
- currency: {
5889
- type: 'string',
5890
- description: 'Currency without exchange rate',
5891
- example: 'EUR'
5892
- },
5893
- totalAmount: {
5894
- type: 'string',
5895
- description: 'Total amount affected',
5896
- example: '1000.00'
5897
- }
5898
- },
5899
- required: ['type', 'currency', 'totalAmount']
5900
- } as const;
5901
-
5902
7356
  export const $NetWorthResponseDto = {
5903
7357
  type: 'object',
5904
7358
  properties: {
@@ -5984,7 +7438,7 @@ export const $AccountItemDto = {
5984
7438
  name: {
5985
7439
  type: 'string',
5986
7440
  description: 'Full account name',
5987
- example: 'Assets:Bank:CMB:Savings'
7441
+ example: 'Assets:CN:CMB:Savings'
5988
7442
  },
5989
7443
  displayName: {
5990
7444
  type: 'string',
@@ -6000,6 +7454,12 @@ export const $AccountItemDto = {
6000
7454
  type: 'string',
6001
7455
  description: 'Currency code',
6002
7456
  example: 'CNY'
7457
+ },
7458
+ convertedBalance: {
7459
+ type: 'string',
7460
+ description:
7461
+ 'FX-converted balance in base currency; omitted when not convertible',
7462
+ example: '50000.00'
6003
7463
  }
6004
7464
  },
6005
7465
  required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -6026,11 +7486,66 @@ export const $PlatformGroupDto = {
6026
7486
  },
6027
7487
  totalBalance: {
6028
7488
  type: 'string',
6029
- description: 'Total balance across all accounts in platform',
7489
+ description: 'FX-converted total balance in base currency',
7490
+ example: '100000.00'
7491
+ },
7492
+ balanceByCurrency: {
7493
+ description: 'Raw (unconverted) balances grouped by currency',
7494
+ type: 'array',
7495
+ items: {
7496
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
7497
+ }
7498
+ },
7499
+ convertedBalance: {
7500
+ type: 'string',
7501
+ description:
7502
+ 'Converted balance in base currency (omitted when no currency is convertible)',
6030
7503
  example: '100000.00'
7504
+ },
7505
+ sharePct: {
7506
+ type: 'number',
7507
+ description:
7508
+ 'Share of the grand converted total (0-100); 0 when grand total is 0',
7509
+ example: 42.5
7510
+ }
7511
+ },
7512
+ required: [
7513
+ 'platformId',
7514
+ 'platformName',
7515
+ 'accounts',
7516
+ 'totalBalance',
7517
+ 'balanceByCurrency',
7518
+ 'sharePct'
7519
+ ]
7520
+ } as const;
7521
+
7522
+ export const $AccountExchangeRateWarningDto = {
7523
+ type: 'object',
7524
+ properties: {
7525
+ type: {
7526
+ type: 'string',
7527
+ description: 'Warning type',
7528
+ example: 'MISSING_EXCHANGE_RATE'
7529
+ },
7530
+ currency: {
7531
+ type: 'string',
7532
+ description: 'Currency without exchange rate',
7533
+ example: 'USD'
7534
+ },
7535
+ accounts: {
7536
+ description: 'Affected account paths',
7537
+ type: 'array',
7538
+ items: {
7539
+ type: 'string'
7540
+ }
7541
+ },
7542
+ totalAmount: {
7543
+ type: 'string',
7544
+ description: 'Total amount in this currency',
7545
+ example: '5000.00'
6031
7546
  }
6032
7547
  },
6033
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
7548
+ required: ['type', 'currency', 'accounts', 'totalAmount']
6034
7549
  } as const;
6035
7550
 
6036
7551
  export const $AccountsSummaryDto = {
@@ -6043,9 +7558,21 @@ export const $AccountsSummaryDto = {
6043
7558
  totalPlatforms: {
6044
7559
  type: 'number',
6045
7560
  description: 'Total number of platforms'
7561
+ },
7562
+ baseCurrency: {
7563
+ type: 'string',
7564
+ description: 'Base currency for conversion',
7565
+ example: 'CNY'
7566
+ },
7567
+ warnings: {
7568
+ description: 'Per-account exchange rate warnings',
7569
+ type: 'array',
7570
+ items: {
7571
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
7572
+ }
6046
7573
  }
6047
7574
  },
6048
- required: ['totalAccounts', 'totalPlatforms']
7575
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
6049
7576
  } as const;
6050
7577
 
6051
7578
  export const $AccountsResponseDto = {
@@ -6080,7 +7607,7 @@ export const $AccountItemWithAssetClassDto = {
6080
7607
  name: {
6081
7608
  type: 'string',
6082
7609
  description: 'Full account name',
6083
- example: 'Assets:Bank:CMB:Savings'
7610
+ example: 'Assets:CN:CMB:Savings'
6084
7611
  },
6085
7612
  displayName: {
6086
7613
  type: 'string',
@@ -6097,6 +7624,12 @@ export const $AccountItemWithAssetClassDto = {
6097
7624
  description: 'Currency code',
6098
7625
  example: 'CNY'
6099
7626
  },
7627
+ convertedBalance: {
7628
+ type: 'string',
7629
+ description:
7630
+ 'FX-converted balance in base currency; omitted when not convertible',
7631
+ example: '50000.00'
7632
+ },
6100
7633
  assetClass: {
6101
7634
  type: 'string',
6102
7635
  description: 'Asset class',
@@ -6176,35 +7709,6 @@ export const $AssetClassGroupDto = {
6176
7709
  required: ['assetClass', 'accounts', 'balanceByCurrency']
6177
7710
  } as const;
6178
7711
 
6179
- export const $AccountExchangeRateWarningDto = {
6180
- type: 'object',
6181
- properties: {
6182
- type: {
6183
- type: 'string',
6184
- description: 'Warning type',
6185
- example: 'MISSING_EXCHANGE_RATE'
6186
- },
6187
- currency: {
6188
- type: 'string',
6189
- description: 'Currency without exchange rate',
6190
- example: 'USD'
6191
- },
6192
- accounts: {
6193
- description: 'Affected account paths',
6194
- type: 'array',
6195
- items: {
6196
- type: 'string'
6197
- }
6198
- },
6199
- totalAmount: {
6200
- type: 'string',
6201
- description: 'Total amount in this currency',
6202
- example: '5000.00'
6203
- }
6204
- },
6205
- required: ['type', 'currency', 'accounts', 'totalAmount']
6206
- } as const;
6207
-
6208
7712
  export const $AssetClassSummaryDto = {
6209
7713
  type: 'object',
6210
7714
  properties: {
@@ -6278,7 +7782,7 @@ export const $HoldingAssetClassAccountSliceDto = {
6278
7782
  accountPath: {
6279
7783
  type: 'string',
6280
7784
  description: 'Full account path',
6281
- example: 'Assets:US:Investments:Brokerage'
7785
+ example: 'Assets:US:Fidelity:Brokerage'
6282
7786
  },
6283
7787
  accountCurrency: {
6284
7788
  type: 'string',
@@ -6450,38 +7954,133 @@ export const $CashFlowResponseDto = {
6450
7954
  description: 'Base currency code',
6451
7955
  example: 'CNY'
6452
7956
  },
6453
- byCurrency: {
6454
- description: 'Cash flow grouped by original currency',
6455
- allOf: [
6456
- {
6457
- $ref: '#/components/schemas/CashFlowByCurrencyDto'
6458
- }
6459
- ]
7957
+ byCurrency: {
7958
+ description: 'Cash flow grouped by original currency',
7959
+ allOf: [
7960
+ {
7961
+ $ref: '#/components/schemas/CashFlowByCurrencyDto'
7962
+ }
7963
+ ]
7964
+ },
7965
+ converted: {
7966
+ description: 'Converted values in base currency',
7967
+ allOf: [
7968
+ {
7969
+ $ref: '#/components/schemas/ConvertedCashFlowDto'
7970
+ }
7971
+ ]
7972
+ },
7973
+ warnings: {
7974
+ description: 'Exchange rate warnings',
7975
+ type: 'array',
7976
+ items: {
7977
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
7978
+ }
7979
+ }
7980
+ },
7981
+ required: [
7982
+ 'period',
7983
+ 'income',
7984
+ 'expense',
7985
+ 'netSavings',
7986
+ 'savingsRate',
7987
+ 'currency'
7988
+ ]
7989
+ } as const;
7990
+
7991
+ export const $CategoryGroupDto = {
7992
+ type: 'object',
7993
+ properties: {
7994
+ category: {
7995
+ type: 'string',
7996
+ description:
7997
+ 'Functional category (account-path Group segment); regional and universal account paths merge under it',
7998
+ example: 'Food'
7999
+ },
8000
+ totalExpense: {
8001
+ type: 'string',
8002
+ description:
8003
+ 'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
8004
+ example: '1200.00'
8005
+ },
8006
+ sharePct: {
8007
+ type: 'number',
8008
+ description: 'Share of grand total (0-100); 0 when grand total is 0',
8009
+ example: 42.5
8010
+ },
8011
+ balanceByCurrency: {
8012
+ description: 'Raw (unconverted) expense per currency',
8013
+ type: 'array',
8014
+ items: {
8015
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
8016
+ }
8017
+ },
8018
+ convertedBalance: {
8019
+ type: 'string',
8020
+ description:
8021
+ 'Converted total in base currency (omitted when FX missing for all currencies in this category)',
8022
+ example: '1200.00'
8023
+ }
8024
+ },
8025
+ required: ['category', 'totalExpense', 'sharePct', 'balanceByCurrency']
8026
+ } as const;
8027
+
8028
+ export const $ExpensesByCategorySummaryDto = {
8029
+ type: 'object',
8030
+ properties: {
8031
+ totalExpense: {
8032
+ type: 'string',
8033
+ description:
8034
+ 'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
8035
+ example: '5000.00'
8036
+ },
8037
+ categoryCount: {
8038
+ type: 'number',
8039
+ description: 'Number of categories',
8040
+ example: 8
8041
+ }
8042
+ },
8043
+ required: ['totalExpense', 'categoryCount']
8044
+ } as const;
8045
+
8046
+ export const $ExpensesByCategoryResponseDto = {
8047
+ type: 'object',
8048
+ properties: {
8049
+ period: {
8050
+ type: 'string',
8051
+ description: 'Period requested',
8052
+ example: '1m'
8053
+ },
8054
+ baseCurrency: {
8055
+ type: 'string',
8056
+ description: 'Base currency for converted values',
8057
+ example: 'CNY'
8058
+ },
8059
+ groups: {
8060
+ description:
8061
+ 'Expense groups by functional category, sorted by converted total desc',
8062
+ type: 'array',
8063
+ items: {
8064
+ $ref: '#/components/schemas/CategoryGroupDto'
8065
+ }
6460
8066
  },
6461
- converted: {
6462
- description: 'Converted values in base currency',
8067
+ summary: {
8068
+ description: 'Summary statistics',
6463
8069
  allOf: [
6464
8070
  {
6465
- $ref: '#/components/schemas/ConvertedCashFlowDto'
8071
+ $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
6466
8072
  }
6467
8073
  ]
6468
8074
  },
6469
8075
  warnings: {
6470
- description: 'Exchange rate warnings',
8076
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
6471
8077
  type: 'array',
6472
8078
  items: {
6473
8079
  $ref: '#/components/schemas/ExchangeRateWarningDto'
6474
8080
  }
6475
8081
  }
6476
8082
  },
6477
- required: [
6478
- 'period',
6479
- 'income',
6480
- 'expense',
6481
- 'netSavings',
6482
- 'savingsRate',
6483
- 'currency'
6484
- ]
8083
+ required: ['period', 'baseCurrency', 'groups', 'summary']
6485
8084
  } as const;
6486
8085
 
6487
8086
  export const $MonetaryDto = {
@@ -6698,409 +8297,243 @@ export const $HoldingPnlRowDto = {
6698
8297
  },
6699
8298
  required: [
6700
8299
  'accountId',
6701
- 'accountPath',
6702
- 'symbol',
6703
- 'chartToken',
6704
- 'assetClass',
6705
- 'units'
6706
- ]
6707
- } as const;
6708
-
6709
- export const $HoldingPnlWarningDto = {
6710
- type: 'object',
6711
- properties: {
6712
- type: {
6713
- type: 'string',
6714
- description: 'Warning type',
6715
- example: 'MISSING_COST_FX_RATE',
6716
- enum: [
6717
- 'MISSING_COST_FX_RATE',
6718
- 'MISSING_MARKET_FX_RATE',
6719
- 'MISSING_SALE_PRICE',
6720
- 'MISSING_REALIZED_FX_RATE',
6721
- 'OVERSOLD_LOTS',
6722
- 'NO_PRICE',
6723
- 'MIXED_COST_CURRENCY'
6724
- ]
6725
- },
6726
- symbol: {
6727
- type: 'object',
6728
- nullable: true
6729
- },
6730
- accountId: {
6731
- type: 'object',
6732
- nullable: true
6733
- },
6734
- currency: {
6735
- type: 'object',
6736
- nullable: true
6737
- }
6738
- },
6739
- required: ['type']
6740
- } as const;
6741
-
6742
- export const $HoldingPnlResponseDto = {
6743
- type: 'object',
6744
- properties: {
6745
- asOfDate: {
6746
- type: 'string',
6747
- example: '2026-07-08'
6748
- },
6749
- baseCurrency: {
6750
- type: 'string',
6751
- example: 'CNY'
6752
- },
6753
- method: {
6754
- type: 'string',
6755
- description:
6756
- 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
6757
- enum: ['average', 'FIFO'],
6758
- example: 'average'
6759
- },
6760
- rows: {
6761
- type: 'array',
6762
- items: {
6763
- $ref: '#/components/schemas/HoldingPnlRowDto'
6764
- }
6765
- },
6766
- warnings: {
6767
- type: 'array',
6768
- items: {
6769
- $ref: '#/components/schemas/HoldingPnlWarningDto'
6770
- }
6771
- }
6772
- },
6773
- required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6774
- } as const;
6775
-
6776
- export const $CreateBeanPriceDto = {
6777
- type: 'object',
6778
- properties: {
6779
- currency: {
6780
- type: 'string',
6781
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6782
- example: 'USD'
6783
- },
6784
- quoteCurrency: {
6785
- type: 'string',
6786
- description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
6787
- example: 'CNY'
6788
- },
6789
- amount: {
6790
- type: 'number',
6791
- description:
6792
- 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
6793
- example: 175.5,
6794
- minimum: 0
6795
- },
6796
- date: {
6797
- type: 'string',
6798
- description: 'Price date (ISO 8601 format)',
6799
- example: '2024-11-05'
6800
- },
6801
- metadata: {
6802
- type: 'object',
6803
- description:
6804
- 'Metadata (validated by Zod schema, max field lengths enforced)',
6805
- example: {
6806
- source: 'MANUAL',
6807
- note: 'Bank valuation report',
6808
- confidence: 0.95
6809
- }
6810
- }
6811
- },
6812
- required: ['currency', 'quoteCurrency', 'amount', 'date']
6813
- } as const;
6814
-
6815
- export const $PriceResponseDto = {
6816
- type: 'object',
6817
- properties: {
6818
- id: {
6819
- type: 'string',
6820
- description: 'Unique identifier',
6821
- example: 'uuid-123-456'
6822
- },
6823
- userId: {
6824
- type: 'string',
6825
- description: 'User ID (owner of the price)',
6826
- example: 'user-123'
6827
- },
6828
- currency: {
6829
- type: 'string',
6830
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6831
- example: 'BTC'
6832
- },
6833
- quoteCurrency: {
6834
- type: 'string',
6835
- description: 'Quote currency (pricing currency, e.g., USD, CNY)',
6836
- example: 'USD'
6837
- },
6838
- amount: {
6839
- type: 'number',
6840
- description:
6841
- 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
6842
- example: 50000
6843
- },
6844
- date: {
6845
- type: 'string',
6846
- description:
6847
- 'Price date (ISO 8601 format). Represents the date this price was valid.',
6848
- example: '2024-01-01',
6849
- format: 'date'
6850
- },
6851
- meta: {
6852
- type: 'object',
6853
- description:
6854
- 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
6855
- example: {
6856
- source: 'MANUAL',
6857
- note: 'User-defined price',
6858
- confidence: 1
6859
- }
6860
- },
6861
- createdAt: {
6862
- format: 'date-time',
6863
- type: 'string',
6864
- description: 'Creation timestamp',
6865
- example: '2024-11-03T10:00:00Z'
6866
- },
6867
- updatedAt: {
6868
- format: 'date-time',
6869
- type: 'string',
6870
- description: 'Last update timestamp',
6871
- example: '2024-11-03T10:00:00Z'
6872
- }
6873
- },
6874
- required: [
6875
- 'id',
6876
- 'userId',
6877
- 'currency',
6878
- 'quoteCurrency',
6879
- 'amount',
6880
- 'date',
6881
- 'meta',
6882
- 'createdAt',
6883
- 'updatedAt'
6884
- ]
6885
- } as const;
6886
-
6887
- export const $PriceListResponseDto = {
6888
- type: 'object',
6889
- properties: {
6890
- items: {
6891
- description: 'List of prices',
6892
- type: 'array',
6893
- items: {
6894
- $ref: '#/components/schemas/PriceResponseDto'
6895
- }
6896
- },
6897
- total: {
6898
- type: 'number',
6899
- description: 'Total number of prices',
6900
- example: 42
6901
- }
6902
- },
6903
- required: ['items', 'total']
6904
- } as const;
6905
-
6906
- export const $UpdateBeanPriceDto = {
6907
- type: 'object',
6908
- properties: {
6909
- currency: {
6910
- type: 'string',
6911
- description: 'Currency being priced'
6912
- },
6913
- quoteCurrency: {
6914
- type: 'string',
6915
- description: 'Quote currency (pricing currency)'
6916
- },
6917
- amount: {
6918
- type: 'number',
6919
- description: 'Price amount (MUST be >= 0 per Beancount spec)',
6920
- minimum: 0
6921
- },
6922
- date: {
6923
- type: 'string',
6924
- description: 'Price date (ISO 8601 format)'
6925
- },
6926
- metadata: {
6927
- type: 'object',
6928
- description: 'Metadata'
6929
- }
6930
- }
8300
+ 'accountPath',
8301
+ 'symbol',
8302
+ 'chartToken',
8303
+ 'assetClass',
8304
+ 'units'
8305
+ ]
6931
8306
  } as const;
6932
8307
 
6933
- export const $CurrencyBalanceDto = {
8308
+ export const $HoldingPnlWarningDto = {
6934
8309
  type: 'object',
6935
8310
  properties: {
6936
- currency: {
8311
+ type: {
6937
8312
  type: 'string',
6938
- description: 'ISO 4217 currency code',
6939
- example: 'CNY'
8313
+ description: 'Warning type',
8314
+ example: 'MISSING_COST_FX_RATE',
8315
+ enum: [
8316
+ 'MISSING_COST_FX_RATE',
8317
+ 'MISSING_MARKET_FX_RATE',
8318
+ 'MISSING_SALE_PRICE',
8319
+ 'MISSING_REALIZED_FX_RATE',
8320
+ 'OVERSOLD_LOTS',
8321
+ 'NO_PRICE',
8322
+ 'MIXED_COST_CURRENCY'
8323
+ ]
6940
8324
  },
6941
- balance: {
6942
- type: 'string',
6943
- description: 'Balance amount',
6944
- example: '500000.00'
8325
+ symbol: {
8326
+ type: 'object',
8327
+ nullable: true
8328
+ },
8329
+ accountId: {
8330
+ type: 'object',
8331
+ nullable: true
8332
+ },
8333
+ currency: {
8334
+ type: 'object',
8335
+ nullable: true
6945
8336
  }
6946
8337
  },
6947
- required: ['currency', 'balance']
8338
+ required: ['type']
6948
8339
  } as const;
6949
8340
 
6950
- export const $TimeSeriesPointDto = {
8341
+ export const $HoldingPnlResponseDto = {
6951
8342
  type: 'object',
6952
8343
  properties: {
6953
- date: {
8344
+ asOfDate: {
6954
8345
  type: 'string',
6955
- description: 'Date in YYYY-MM-DD format',
6956
- example: '2024-06-15'
8346
+ example: '2026-07-08'
6957
8347
  },
6958
- value: {
8348
+ baseCurrency: {
6959
8349
  type: 'string',
6960
- description: 'Value at this date (in base currency)',
6961
- example: '500000.00'
8350
+ example: 'CNY'
6962
8351
  },
6963
- change: {
6964
- type: 'object',
6965
- description: 'Change from previous point',
6966
- example: '5000.00'
8352
+ method: {
8353
+ type: 'string',
8354
+ description:
8355
+ 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
8356
+ enum: ['average', 'FIFO'],
8357
+ example: 'average'
6967
8358
  },
6968
- byCurrency: {
6969
- description: 'Multi-currency breakdown for this point',
8359
+ rows: {
6970
8360
  type: 'array',
6971
8361
  items: {
6972
- $ref: '#/components/schemas/CurrencyBalanceDto'
8362
+ $ref: '#/components/schemas/HoldingPnlRowDto'
8363
+ }
8364
+ },
8365
+ warnings: {
8366
+ type: 'array',
8367
+ items: {
8368
+ $ref: '#/components/schemas/HoldingPnlWarningDto'
6973
8369
  }
6974
8370
  }
6975
8371
  },
6976
- required: ['date', 'value']
8372
+ required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6977
8373
  } as const;
6978
8374
 
6979
- export const $TrendSummaryDto = {
8375
+ export const $AnonymousLoginDto = {
6980
8376
  type: 'object',
6981
8377
  properties: {
6982
- startValue: {
6983
- type: 'string',
6984
- description: 'Value at start of period',
6985
- example: '450000.00'
6986
- },
6987
- endValue: {
6988
- type: 'string',
6989
- description: 'Value at end of period',
6990
- example: '500000.00'
6991
- },
6992
- totalChange: {
6993
- type: 'string',
6994
- description: 'Total change over period',
6995
- example: '50000.00'
6996
- },
6997
- totalChangePercentage: {
8378
+ accessToken: {
6998
8379
  type: 'string',
6999
- description: 'Total change percentage',
7000
- example: '+11.11%'
8380
+ description: 'Access token for anonymous login'
7001
8381
  }
7002
8382
  },
7003
- required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
8383
+ required: ['accessToken']
7004
8384
  } as const;
7005
8385
 
7006
- export const $MultiCurrencyPointDto = {
8386
+ export const $AnonymousLoginResponseDto = {
7007
8387
  type: 'object',
7008
8388
  properties: {
7009
- date: {
8389
+ authToken: {
7010
8390
  type: 'string',
7011
- description: 'Date in YYYY-MM-DD format',
7012
- example: '2024-06-15'
7013
- },
7014
- byCurrency: {
7015
- description: 'Balances by currency',
7016
- type: 'array',
7017
- items: {
7018
- $ref: '#/components/schemas/CurrencyBalanceDto'
7019
- }
8391
+ description: 'JWT auth token',
8392
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
7020
8393
  }
7021
8394
  },
7022
- required: ['date', 'byCurrency']
8395
+ required: ['authToken']
7023
8396
  } as const;
7024
8397
 
7025
- export const $PortfolioTrendsResponseDto = {
8398
+ export const $SymbolSearchResultDto = {
7026
8399
  type: 'object',
7027
8400
  properties: {
7028
- series: {
7029
- description: 'Time series data points',
7030
- type: 'array',
7031
- items: {
7032
- $ref: '#/components/schemas/TimeSeriesPointDto'
7033
- }
8401
+ symbol: {
8402
+ type: 'string',
8403
+ example: 'AAPL'
7034
8404
  },
7035
- summary: {
7036
- description: 'Period summary',
7037
- allOf: [
7038
- {
7039
- $ref: '#/components/schemas/TrendSummaryDto'
7040
- }
7041
- ]
8405
+ name: {
8406
+ type: 'object',
8407
+ example: 'Apple Inc.',
8408
+ nullable: true
7042
8409
  },
7043
- period: {
7044
- type: 'string',
7045
- description: 'Period requested',
7046
- example: '6m'
8410
+ exchange: {
8411
+ type: 'object',
8412
+ example: 'US',
8413
+ nullable: true
7047
8414
  },
7048
- granularity: {
7049
- type: 'string',
7050
- description: 'Data granularity',
7051
- example: 'month'
8415
+ assetType: {
8416
+ type: 'object',
8417
+ description: 'OpenBB asset_type (e.g. stock, etf)',
8418
+ example: 'stock',
8419
+ nullable: true
7052
8420
  },
7053
- currency: {
7054
- type: 'string',
7055
- description: 'Base currency for converted values',
7056
- example: 'CNY'
8421
+ assetClass: {
8422
+ type: 'object',
8423
+ description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
8424
+ example: 'EQUITY',
8425
+ nullable: true
7057
8426
  },
7058
- byCurrency: {
7059
- description:
7060
- 'Multi-currency time series (each point has currency breakdown)',
7061
- type: 'array',
7062
- items: {
7063
- $ref: '#/components/schemas/MultiCurrencyPointDto'
7064
- }
8427
+ assetSubClass: {
8428
+ type: 'object',
8429
+ description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
8430
+ example: 'STOCK',
8431
+ nullable: true
7065
8432
  },
7066
- warnings: {
7067
- description: 'Exchange rate warnings',
7068
- type: 'array',
7069
- items: {
7070
- $ref: '#/components/schemas/ExchangeRateWarningDto'
7071
- }
8433
+ currency: {
8434
+ type: 'object',
8435
+ description: 'Trading currency (extra_data or inferred from exchange)',
8436
+ example: 'USD',
8437
+ nullable: true
7072
8438
  }
7073
8439
  },
7074
- required: ['series', 'summary', 'period', 'granularity', 'currency']
7075
- } as const;
7076
-
7077
- export const $GenerateSnapshotBody = {
7078
- type: 'object',
7079
- properties: {}
7080
- } as const;
7081
-
7082
- export const $GenerateSnapshotResponse = {
7083
- type: 'object',
7084
- properties: {}
7085
- } as const;
7086
-
7087
- export const $BackfillSnapshotsBody = {
7088
- type: 'object',
7089
- properties: {}
7090
- } as const;
7091
-
7092
- export const $BackfillSnapshotsResponse = {
7093
- type: 'object',
7094
- properties: {}
8440
+ required: ['symbol']
7095
8441
  } as const;
7096
8442
 
7097
- export const $AnonymousLoginDto = {
8443
+ export const $SymbolQuoteDto = {
7098
8444
  type: 'object',
7099
8445
  properties: {
7100
- accessToken: {
8446
+ symbol: {
7101
8447
  type: 'string',
7102
- description: 'Access token for anonymous login'
8448
+ example: 'AAPL'
8449
+ },
8450
+ name: {
8451
+ type: 'object',
8452
+ example: 'Apple Inc.',
8453
+ nullable: true
8454
+ },
8455
+ exchange: {
8456
+ type: 'object',
8457
+ example: 'US',
8458
+ nullable: true
8459
+ },
8460
+ assetType: {
8461
+ type: 'object',
8462
+ description: 'OpenBB asset_type',
8463
+ example: 'stock',
8464
+ nullable: true
8465
+ },
8466
+ assetClass: {
8467
+ type: 'object',
8468
+ description: 'IGN asset class',
8469
+ example: 'EQUITY',
8470
+ nullable: true
8471
+ },
8472
+ assetSubClass: {
8473
+ type: 'object',
8474
+ description: 'IGN asset sub-class',
8475
+ example: 'STOCK',
8476
+ nullable: true
8477
+ },
8478
+ currency: {
8479
+ type: 'object',
8480
+ description: 'Trading currency (extra_data or inferred from exchange)',
8481
+ example: 'USD',
8482
+ nullable: true
8483
+ },
8484
+ price: {
8485
+ type: 'object',
8486
+ description: 'Latest price (Decimal string)',
8487
+ example: '189.84',
8488
+ nullable: true
8489
+ },
8490
+ priceDate: {
8491
+ type: 'object',
8492
+ description: 'Date the price was observed (ISO yyyy-MM-dd)',
8493
+ example: '2026-08-05',
8494
+ nullable: true
8495
+ },
8496
+ changePercent: {
8497
+ type: 'object',
8498
+ description:
8499
+ '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.',
8500
+ example: 1.7,
8501
+ nullable: true
8502
+ },
8503
+ prevClose: {
8504
+ type: 'object',
8505
+ description: 'Previous close (Decimal string)',
8506
+ nullable: true
8507
+ },
8508
+ open: {
8509
+ type: 'object',
8510
+ description: 'Day open (Decimal string)',
8511
+ nullable: true
8512
+ },
8513
+ high: {
8514
+ type: 'object',
8515
+ description: 'Day high (Decimal string)',
8516
+ nullable: true
8517
+ },
8518
+ low: {
8519
+ type: 'object',
8520
+ description: 'Day low (Decimal string)',
8521
+ nullable: true
8522
+ },
8523
+ volume: {
8524
+ type: 'object',
8525
+ description: 'Day volume (Decimal string)',
8526
+ nullable: true
8527
+ },
8528
+ yearHigh: {
8529
+ type: 'object',
8530
+ description: '52-week high (Decimal string)',
8531
+ nullable: true
8532
+ },
8533
+ yearLow: {
8534
+ type: 'object',
8535
+ description: '52-week low (Decimal string)',
8536
+ nullable: true
7103
8537
  }
7104
- },
7105
- required: ['accessToken']
8538
+ }
7106
8539
  } as const;