@firela/api-types 0.0.0-canary.8c68ebbe → 0.0.0-canary.90dabcd7

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 +2429 -1237
  2. package/dist/index.d.ts +2429 -1237
  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 +2636 -1341
  7. package/src/generated/services.gen.ts +1251 -774
  8. package/src/generated/types.gen.ts +5403 -1337
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,75 +4323,787 @@ export const $UpdatePropertyDto = {
4312
4323
  required: ['value']
4313
4324
  } as const;
4314
4325
 
4315
- export const $CreateBeanEventDto = {
4326
+ export const $CreateTransactionRuleDto = {
4316
4327
  type: 'object',
4317
4328
  properties: {
4318
- date: {
4319
- type: 'string',
4320
- description: 'Life event date (ISO 8601)',
4321
- example: '2024-03-15'
4322
- },
4323
- type: {
4329
+ name: {
4324
4330
  type: 'string',
4325
- description:
4326
- 'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
4327
- example: 'employer'
4331
+ minLength: 1,
4332
+ maxLength: 100
4328
4333
  },
4329
4334
  description: {
4330
4335
  type: 'string',
4331
- description:
4332
- 'Life event description. Empty string is a VALID value (distinct from absence).',
4333
- example: 'Acme Corp'
4336
+ maxLength: 500
4334
4337
  },
4335
- meta: {
4336
- type: 'object',
4337
- description:
4338
- 'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
4339
- example: {
4340
- note: 'Promotion'
4341
- }
4342
- }
4343
- },
4344
- required: ['date', 'type', 'description']
4345
- } as const;
4346
-
4347
- export const $EventResponseDto = {
4348
- type: 'object',
4349
- properties: {
4350
- id: {
4351
- type: 'string',
4352
- description: 'Unique identifier',
4353
- example: 'uuid-123-456'
4338
+ narrationKeywords: {
4339
+ items: {
4340
+ type: 'array'
4341
+ },
4342
+ maxItems: 50,
4343
+ type: 'array'
4354
4344
  },
4355
- userId: {
4356
- type: 'string',
4357
- description: 'User ID (owner of the life event)',
4358
- example: 'user-123'
4345
+ payeeKeywords: {
4346
+ items: {
4347
+ type: 'array'
4348
+ },
4349
+ maxItems: 50,
4350
+ type: 'array'
4359
4351
  },
4360
- date: {
4361
- type: 'string',
4362
- description: 'Life event date (ISO 8601 format)',
4363
- example: '2024-03-15',
4364
- format: 'date'
4352
+ categoryKeywords: {
4353
+ items: {
4354
+ type: 'array'
4355
+ },
4356
+ maxItems: 50,
4357
+ type: 'array'
4365
4358
  },
4366
- type: {
4359
+ methodKeywords: {
4360
+ items: {
4361
+ type: 'array'
4362
+ },
4363
+ maxItems: 50,
4364
+ description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
4365
+ type: 'array'
4366
+ },
4367
+ categoryAccount: {
4367
4368
  type: 'string',
4369
+ maxLength: 200,
4368
4370
  description:
4369
- 'Life event type (user-defined, e.g., "employer", "location")',
4370
- example: 'employer'
4371
+ 'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
4371
4372
  },
4372
- description: {
4373
+ matchLogic: {
4373
4374
  type: 'string',
4374
- description:
4375
- 'Life event description. May be an empty string (a valid value distinct from absence).',
4376
- example: 'Acme Corp'
4375
+ enum: ['OR', 'AND'],
4376
+ default: 'OR'
4377
4377
  },
4378
- meta: {
4379
- type: 'object',
4380
- description: 'Product-side metadata (free-form JSON)',
4381
- example: {
4382
- note: 'Promotion'
4383
- }
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
+ }
4384
5107
  },
4385
5108
  createdAt: {
4386
5109
  format: 'date-time',
@@ -4424,30 +5147,281 @@ export const $EventListResponseDto = {
4424
5147
  example: 42
4425
5148
  }
4426
5149
  },
4427
- required: ['items', 'total']
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']
4428
5414
  } as const;
4429
5415
 
4430
- export const $UpdateBeanEventDto = {
5416
+ export const $PadResultDto = {
4431
5417
  type: 'object',
4432
5418
  properties: {
4433
- date: {
4434
- type: 'string',
4435
- description: 'Life event date (ISO 8601)'
4436
- },
4437
- type: {
4438
- type: 'string',
4439
- description: 'Life event type (user-defined)'
4440
- },
4441
- description: {
5419
+ transactionId: {
4442
5420
  type: 'string',
4443
- description:
4444
- 'Life event description. Empty string is a VALID value (distinct from absence).'
4445
- },
4446
- meta: {
4447
- type: 'object',
4448
- description: 'Product-side metadata (free-form JSON)'
5421
+ description: 'Created pad adjusting transaction id.'
4449
5422
  }
4450
- }
5423
+ },
5424
+ required: ['transactionId']
4451
5425
  } as const;
4452
5426
 
4453
5427
  export const $FileImportDto = {
@@ -4616,7 +5590,7 @@ export const $IdentifyResultDto = {
4616
5590
  account: {
4617
5591
  type: 'string',
4618
5592
  description: 'Default account used by this importer',
4619
- example: 'Assets:Alipay:Balance'
5593
+ example: 'Assets:CN:Alipay:Balance'
4620
5594
  },
4621
5595
  message: {
4622
5596
  type: 'string',
@@ -4633,7 +5607,7 @@ export const $MapperDefaultsDto = {
4633
5607
  sourceAccount: {
4634
5608
  type: 'string',
4635
5609
  description: 'Source account for transactions (Beancount format)',
4636
- example: 'Assets:Alipay:Balance'
5610
+ example: 'Assets:CN:Alipay:Balance'
4637
5611
  },
4638
5612
  currency: {
4639
5613
  type: 'string',
@@ -4670,7 +5644,7 @@ export const $MapperDefaultsDto = {
4670
5644
  description:
4671
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).',
4672
5646
  example: {
4673
- HuaBei: 'Liabilities:Alipay:Huabei',
5647
+ HuaBei: 'Liabilities:CN:CreditLine',
4674
5648
  CreditCard: 'Liabilities:CreditCard'
4675
5649
  }
4676
5650
  }
@@ -4802,8 +5776,9 @@ export const $UpdateMapperDefaultsDto = {
4802
5776
  sourceAccount: {
4803
5777
  type: 'string',
4804
5778
  description: 'Source account for transactions (Beancount format)',
4805
- example: 'Assets:Alipay:Balance',
4806
- 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-]*)+$'
4807
5782
  },
4808
5783
  currency: {
4809
5784
  type: 'string',
@@ -4817,20 +5792,22 @@ export const $UpdateMapperDefaultsDto = {
4817
5792
  type: 'string',
4818
5793
  description: 'Default expense account (optional)',
4819
5794
  example: 'Expenses:Unknown',
4820
- 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-]*)+$'
4821
5797
  },
4822
5798
  incomeAccount: {
4823
5799
  type: 'string',
4824
5800
  description: 'Default income account (optional)',
4825
5801
  example: 'Income:Unknown',
4826
- 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-]*)+$'
4827
5804
  },
4828
5805
  methodAccountMapping: {
4829
5806
  type: 'object',
4830
5807
  description:
4831
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).',
4832
5809
  example: {
4833
- HuaBei: 'Liabilities:Alipay:Huabei',
5810
+ HuaBei: 'Liabilities:CN:CreditLine',
4834
5811
  CreditCard: 'Liabilities:CreditCard'
4835
5812
  }
4836
5813
  }
@@ -4865,119 +5842,13 @@ export const $UpdateImporterConfigDto = {
4865
5842
  }
4866
5843
  } as const;
4867
5844
 
4868
- export const $CreatePlatformDto = {
4869
- type: 'object',
4870
- properties: {
4871
- name: {
4872
- type: 'string',
4873
- description: 'Platform name',
4874
- example: 'Binance'
4875
- },
4876
- canonical: {
4877
- type: 'string',
4878
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4879
- example: 'binance'
4880
- },
4881
- aliases: {
4882
- description: 'Platform aliases (multi-language names for lookup)',
4883
- example: ['Binance', 'Binance Exchange', 'BNB'],
4884
- type: 'array',
4885
- items: {
4886
- type: 'string'
4887
- }
4888
- },
4889
- url: {
4890
- type: 'string',
4891
- description: 'Platform URL',
4892
- example: 'https://www.binance.com'
4893
- },
4894
- type: {
4895
- type: 'string',
4896
- description: 'Platform type',
4897
- enum: [
4898
- 'BANK',
4899
- 'BROKERAGE',
4900
- 'CRYPTO_EXCHANGE',
4901
- 'PAYMENT',
4902
- 'INVESTMENT',
4903
- 'INSURANCE',
4904
- 'OTHER'
4905
- ],
4906
- example: 'CRYPTO_EXCHANGE'
4907
- },
4908
- logoUrl: {
4909
- type: 'string',
4910
- description: 'Platform logo URL',
4911
- example: 'https://example.com/logos/binance.png'
4912
- },
4913
- isActive: {
4914
- type: 'boolean',
4915
- description: 'Whether the platform is active',
4916
- default: true
4917
- }
4918
- },
4919
- required: ['name', 'canonical', 'aliases', 'url', 'type']
4920
- } as const;
4921
-
4922
- export const $UpdatePlatformDto = {
4923
- type: 'object',
4924
- properties: {
4925
- name: {
4926
- type: 'string',
4927
- description: 'Platform name',
4928
- example: 'Binance'
4929
- },
4930
- canonical: {
4931
- type: 'string',
4932
- description: 'Platform canonical identifier (lowercase, kebab-case)',
4933
- example: 'binance'
4934
- },
4935
- aliases: {
4936
- description: 'Platform aliases (multi-language names for lookup)',
4937
- example: ['Binance', 'Binance Exchange', 'BNB'],
4938
- type: 'array',
4939
- items: {
4940
- type: 'string'
4941
- }
4942
- },
4943
- url: {
4944
- type: 'string',
4945
- description: 'Platform URL',
4946
- example: 'https://www.binance.com'
4947
- },
4948
- type: {
4949
- type: 'string',
4950
- description: 'Platform type',
4951
- enum: [
4952
- 'BANK',
4953
- 'BROKERAGE',
4954
- 'CRYPTO_EXCHANGE',
4955
- 'PAYMENT',
4956
- 'INVESTMENT',
4957
- 'INSURANCE',
4958
- 'OTHER'
4959
- ],
4960
- example: 'CRYPTO_EXCHANGE'
4961
- },
4962
- logoUrl: {
4963
- type: 'string',
4964
- description: 'Platform logo URL',
4965
- example: 'https://example.com/logos/binance.png'
4966
- },
4967
- isActive: {
4968
- type: 'boolean',
4969
- description: 'Whether the platform is active'
4970
- }
4971
- }
4972
- } as const;
4973
-
4974
5845
  export const $ProviderSyncConfigDto = {
4975
5846
  type: 'object',
4976
5847
  properties: {
4977
5848
  sourceAccount: {
4978
5849
  type: 'string',
4979
5850
  description: 'Source account for the first posting',
4980
- example: 'Assets:Bank:Chase'
5851
+ example: 'Assets:US:Chase:Checking'
4981
5852
  },
4982
5853
  defaultCurrency: {
4983
5854
  type: 'string',
@@ -4986,26 +5857,29 @@ export const $ProviderSyncConfigDto = {
4986
5857
  },
4987
5858
  defaultExpenseAccount: {
4988
5859
  type: 'string',
4989
- 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).',
4990
5862
  example: 'Expenses:Unknown'
4991
5863
  },
4992
5864
  defaultIncomeAccount: {
4993
5865
  type: 'string',
4994
- 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).',
4995
5868
  example: 'Income:Unknown'
4996
5869
  },
4997
5870
  filterPending: {
4998
5871
  type: 'boolean',
4999
5872
  description: 'Filter pending transactions',
5000
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'
5001
5880
  }
5002
5881
  },
5003
- required: [
5004
- 'sourceAccount',
5005
- 'defaultCurrency',
5006
- 'defaultExpenseAccount',
5007
- 'defaultIncomeAccount'
5008
- ]
5882
+ required: ['sourceAccount', 'defaultCurrency']
5009
5883
  } as const;
5010
5884
 
5011
5885
  export const $ProviderSyncDto = {
@@ -5113,18 +5987,189 @@ export const $SupportedProvidersResponseDto = {
5113
5987
  type: 'string'
5114
5988
  }
5115
5989
  }
5116
- },
5117
- required: ['providers']
5118
- } as const;
5119
-
5120
- export const $ParserTelemetryReportDto = {
5121
- type: 'object',
5122
- properties: {}
5123
- } as const;
5124
-
5125
- export const $UncoveredFormatMissDto = {
5126
- type: 'object',
5127
- 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
+ }
5128
6173
  } as const;
5129
6174
 
5130
6175
  export const $ProcessNlpDto = {
@@ -5132,10 +6177,17 @@ export const $ProcessNlpDto = {
5132
6177
  properties: {
5133
6178
  message: {
5134
6179
  type: 'string',
5135
- description: 'Natural language text describing a transaction (Chinese)',
5136
- 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',
5137
6183
  maxLength: 500
5138
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
+ },
5139
6191
  sessionId: {
5140
6192
  type: 'string',
5141
6193
  description:
@@ -5143,17 +6195,32 @@ export const $ProcessNlpDto = {
5143
6195
  example: 'session_abc123'
5144
6196
  },
5145
6197
  parsedData: {
5146
- type: 'object',
5147
6198
  description:
5148
6199
  'Parsed data from previous NLP response for session recovery. Send back the parsedData received in confirm_payee/confirm responses.',
5149
6200
  example: {
5150
6201
  amount: 35,
5151
6202
  currency: 'CNY',
5152
6203
  payee: 'Starbucks'
5153
- }
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'
5154
6222
  }
5155
- },
5156
- required: ['message']
6223
+ }
5157
6224
  } as const;
5158
6225
 
5159
6226
  export const $NlpTransactionInfoDto = {
@@ -5475,7 +6542,8 @@ export const $NlpAccountConfirmationDataDto = {
5475
6542
  },
5476
6543
  suggestedAccount: {
5477
6544
  type: 'string',
5478
- description: 'Suggested replacement account',
6545
+ description:
6546
+ 'Suggested replacement account (omitted when no clear candidate)',
5479
6547
  example: 'Expenses:Food:Drinks'
5480
6548
  },
5481
6549
  similarAccounts: {
@@ -5497,7 +6565,6 @@ export const $NlpAccountConfirmationDataDto = {
5497
6565
  },
5498
6566
  required: [
5499
6567
  'invalidAccount',
5500
- 'suggestedAccount',
5501
6568
  'similarAccounts',
5502
6569
  'errorMessage',
5503
6570
  'transactionContext'
@@ -5666,11 +6733,12 @@ export const $NlpSuggestedAccountDto = {
5666
6733
  account: {
5667
6734
  type: 'string',
5668
6735
  description: 'Suggested account path',
5669
- example: 'Assets:Bank:Checking'
6736
+ example: 'Assets:Checking'
5670
6737
  },
5671
6738
  confidence: {
5672
6739
  type: 'number',
5673
- 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)',
5674
6742
  example: 0.9
5675
6743
  }
5676
6744
  },
@@ -5706,23 +6774,31 @@ export const $NlpDefaultAccountsDto = {
5706
6774
  properties: {
5707
6775
  asset: {
5708
6776
  type: 'string',
5709
- description: 'Default asset account',
5710
- 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
5711
6781
  },
5712
6782
  expense: {
5713
6783
  type: 'string',
5714
- description: 'Default expense account',
5715
- 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
5716
6788
  },
5717
6789
  income: {
5718
6790
  type: 'string',
5719
- description: 'Default income account',
5720
- 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
5721
6795
  },
5722
6796
  liability: {
5723
6797
  type: 'string',
5724
- description: 'Default liability account',
5725
- 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
5726
6802
  }
5727
6803
  },
5728
6804
  required: ['asset', 'expense', 'income', 'liability']
@@ -5747,7 +6823,8 @@ export const $NlpResponseDto = {
5747
6823
  'confirm_rule',
5748
6824
  'confirm_account',
5749
6825
  'confirm_payee',
5750
- 'cancel'
6826
+ 'cancel',
6827
+ 'aborted'
5751
6828
  ]
5752
6829
  },
5753
6830
  intent: {
@@ -5761,7 +6838,7 @@ export const $NlpResponseDto = {
5761
6838
  type: 'string',
5762
6839
  description:
5763
6840
  'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
5764
- enum: ['transfer', 'banking', 'investment'],
6841
+ enum: ['transfer', 'banking', 'investment', 'lend', 'lend_collect'],
5765
6842
  example: 'investment'
5766
6843
  },
5767
6844
  liabilitySubType: {
@@ -5909,7 +6986,7 @@ export const $NlpResponseDto = {
5909
6986
  },
5910
6987
  suggestedAccounts: {
5911
6988
  description:
5912
- '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.',
5913
6990
  allOf: [
5914
6991
  {
5915
6992
  $ref: '#/components/schemas/NlpSuggestedAccountsDto'
@@ -5918,7 +6995,7 @@ export const $NlpResponseDto = {
5918
6995
  },
5919
6996
  defaultAccounts: {
5920
6997
  description:
5921
- '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.',
5922
6999
  allOf: [
5923
7000
  {
5924
7001
  $ref: '#/components/schemas/NlpDefaultAccountsDto'
@@ -5926,24 +7003,285 @@ export const $NlpResponseDto = {
5926
7003
  ]
5927
7004
  }
5928
7005
  },
5929
- 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']
5930
7233
  } as const;
5931
7234
 
5932
- export const $BalanceByCurrencyDto = {
7235
+ export const $UpdatePlatformDto = {
5933
7236
  type: 'object',
5934
7237
  properties: {
5935
- currency: {
7238
+ name: {
5936
7239
  type: 'string',
5937
- description: 'ISO 4217 currency code',
5938
- example: 'CNY'
7240
+ description: 'Platform name',
7241
+ example: 'Binance'
5939
7242
  },
5940
- balance: {
7243
+ canonical: {
5941
7244
  type: 'string',
5942
- description: 'Balance amount',
5943
- 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'
5944
7283
  }
5945
- },
5946
- required: ['currency', 'balance']
7284
+ }
5947
7285
  } as const;
5948
7286
 
5949
7287
  export const $NetWorthByCurrencyDto = {
@@ -6015,28 +7353,6 @@ export const $ConvertedNetWorthDto = {
6015
7353
  ]
6016
7354
  } as const;
6017
7355
 
6018
- export const $ExchangeRateWarningDto = {
6019
- type: 'object',
6020
- properties: {
6021
- type: {
6022
- type: 'string',
6023
- description: 'Warning type',
6024
- example: 'MISSING_EXCHANGE_RATE'
6025
- },
6026
- currency: {
6027
- type: 'string',
6028
- description: 'Currency without exchange rate',
6029
- example: 'EUR'
6030
- },
6031
- totalAmount: {
6032
- type: 'string',
6033
- description: 'Total amount affected',
6034
- example: '1000.00'
6035
- }
6036
- },
6037
- required: ['type', 'currency', 'totalAmount']
6038
- } as const;
6039
-
6040
7356
  export const $NetWorthResponseDto = {
6041
7357
  type: 'object',
6042
7358
  properties: {
@@ -6122,7 +7438,7 @@ export const $AccountItemDto = {
6122
7438
  name: {
6123
7439
  type: 'string',
6124
7440
  description: 'Full account name',
6125
- example: 'Assets:Bank:CMB:Savings'
7441
+ example: 'Assets:CN:CMB:Savings'
6126
7442
  },
6127
7443
  displayName: {
6128
7444
  type: 'string',
@@ -6138,6 +7454,12 @@ export const $AccountItemDto = {
6138
7454
  type: 'string',
6139
7455
  description: 'Currency code',
6140
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'
6141
7463
  }
6142
7464
  },
6143
7465
  required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -6164,11 +7486,66 @@ export const $PlatformGroupDto = {
6164
7486
  },
6165
7487
  totalBalance: {
6166
7488
  type: 'string',
6167
- 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)',
6168
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'
6169
7546
  }
6170
7547
  },
6171
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
7548
+ required: ['type', 'currency', 'accounts', 'totalAmount']
6172
7549
  } as const;
6173
7550
 
6174
7551
  export const $AccountsSummaryDto = {
@@ -6181,9 +7558,21 @@ export const $AccountsSummaryDto = {
6181
7558
  totalPlatforms: {
6182
7559
  type: 'number',
6183
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
+ }
6184
7573
  }
6185
7574
  },
6186
- required: ['totalAccounts', 'totalPlatforms']
7575
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
6187
7576
  } as const;
6188
7577
 
6189
7578
  export const $AccountsResponseDto = {
@@ -6218,7 +7607,7 @@ export const $AccountItemWithAssetClassDto = {
6218
7607
  name: {
6219
7608
  type: 'string',
6220
7609
  description: 'Full account name',
6221
- example: 'Assets:Bank:CMB:Savings'
7610
+ example: 'Assets:CN:CMB:Savings'
6222
7611
  },
6223
7612
  displayName: {
6224
7613
  type: 'string',
@@ -6235,6 +7624,12 @@ export const $AccountItemWithAssetClassDto = {
6235
7624
  description: 'Currency code',
6236
7625
  example: 'CNY'
6237
7626
  },
7627
+ convertedBalance: {
7628
+ type: 'string',
7629
+ description:
7630
+ 'FX-converted balance in base currency; omitted when not convertible',
7631
+ example: '50000.00'
7632
+ },
6238
7633
  assetClass: {
6239
7634
  type: 'string',
6240
7635
  description: 'Asset class',
@@ -6314,35 +7709,6 @@ export const $AssetClassGroupDto = {
6314
7709
  required: ['assetClass', 'accounts', 'balanceByCurrency']
6315
7710
  } as const;
6316
7711
 
6317
- export const $AccountExchangeRateWarningDto = {
6318
- type: 'object',
6319
- properties: {
6320
- type: {
6321
- type: 'string',
6322
- description: 'Warning type',
6323
- example: 'MISSING_EXCHANGE_RATE'
6324
- },
6325
- currency: {
6326
- type: 'string',
6327
- description: 'Currency without exchange rate',
6328
- example: 'USD'
6329
- },
6330
- accounts: {
6331
- description: 'Affected account paths',
6332
- type: 'array',
6333
- items: {
6334
- type: 'string'
6335
- }
6336
- },
6337
- totalAmount: {
6338
- type: 'string',
6339
- description: 'Total amount in this currency',
6340
- example: '5000.00'
6341
- }
6342
- },
6343
- required: ['type', 'currency', 'accounts', 'totalAmount']
6344
- } as const;
6345
-
6346
7712
  export const $AssetClassSummaryDto = {
6347
7713
  type: 'object',
6348
7714
  properties: {
@@ -6416,7 +7782,7 @@ export const $HoldingAssetClassAccountSliceDto = {
6416
7782
  accountPath: {
6417
7783
  type: 'string',
6418
7784
  description: 'Full account path',
6419
- example: 'Assets:US:Investments:Brokerage'
7785
+ example: 'Assets:US:Fidelity:Brokerage'
6420
7786
  },
6421
7787
  accountCurrency: {
6422
7788
  type: 'string',
@@ -6588,38 +7954,133 @@ export const $CashFlowResponseDto = {
6588
7954
  description: 'Base currency code',
6589
7955
  example: 'CNY'
6590
7956
  },
6591
- byCurrency: {
6592
- description: 'Cash flow grouped by original currency',
6593
- allOf: [
6594
- {
6595
- $ref: '#/components/schemas/CashFlowByCurrencyDto'
6596
- }
6597
- ]
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
+ }
6598
8066
  },
6599
- converted: {
6600
- description: 'Converted values in base currency',
8067
+ summary: {
8068
+ description: 'Summary statistics',
6601
8069
  allOf: [
6602
8070
  {
6603
- $ref: '#/components/schemas/ConvertedCashFlowDto'
8071
+ $ref: '#/components/schemas/ExpensesByCategorySummaryDto'
6604
8072
  }
6605
8073
  ]
6606
8074
  },
6607
8075
  warnings: {
6608
- description: 'Exchange rate warnings',
8076
+ description: 'Exchange rate warnings (e.g. missing rate for a currency)',
6609
8077
  type: 'array',
6610
8078
  items: {
6611
8079
  $ref: '#/components/schemas/ExchangeRateWarningDto'
6612
8080
  }
6613
8081
  }
6614
8082
  },
6615
- required: [
6616
- 'period',
6617
- 'income',
6618
- 'expense',
6619
- 'netSavings',
6620
- 'savingsRate',
6621
- 'currency'
6622
- ]
8083
+ required: ['period', 'baseCurrency', 'groups', 'summary']
6623
8084
  } as const;
6624
8085
 
6625
8086
  export const $MonetaryDto = {
@@ -6836,409 +8297,243 @@ export const $HoldingPnlRowDto = {
6836
8297
  },
6837
8298
  required: [
6838
8299
  'accountId',
6839
- 'accountPath',
6840
- 'symbol',
6841
- 'chartToken',
6842
- 'assetClass',
6843
- 'units'
6844
- ]
6845
- } as const;
6846
-
6847
- export const $HoldingPnlWarningDto = {
6848
- type: 'object',
6849
- properties: {
6850
- type: {
6851
- type: 'string',
6852
- description: 'Warning type',
6853
- example: 'MISSING_COST_FX_RATE',
6854
- enum: [
6855
- 'MISSING_COST_FX_RATE',
6856
- 'MISSING_MARKET_FX_RATE',
6857
- 'MISSING_SALE_PRICE',
6858
- 'MISSING_REALIZED_FX_RATE',
6859
- 'OVERSOLD_LOTS',
6860
- 'NO_PRICE',
6861
- 'MIXED_COST_CURRENCY'
6862
- ]
6863
- },
6864
- symbol: {
6865
- type: 'object',
6866
- nullable: true
6867
- },
6868
- accountId: {
6869
- type: 'object',
6870
- nullable: true
6871
- },
6872
- currency: {
6873
- type: 'object',
6874
- nullable: true
6875
- }
6876
- },
6877
- required: ['type']
6878
- } as const;
6879
-
6880
- export const $HoldingPnlResponseDto = {
6881
- type: 'object',
6882
- properties: {
6883
- asOfDate: {
6884
- type: 'string',
6885
- example: '2026-07-08'
6886
- },
6887
- baseCurrency: {
6888
- type: 'string',
6889
- example: 'CNY'
6890
- },
6891
- method: {
6892
- type: 'string',
6893
- description:
6894
- 'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
6895
- enum: ['average', 'FIFO'],
6896
- example: 'average'
6897
- },
6898
- rows: {
6899
- type: 'array',
6900
- items: {
6901
- $ref: '#/components/schemas/HoldingPnlRowDto'
6902
- }
6903
- },
6904
- warnings: {
6905
- type: 'array',
6906
- items: {
6907
- $ref: '#/components/schemas/HoldingPnlWarningDto'
6908
- }
6909
- }
6910
- },
6911
- required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
6912
- } as const;
6913
-
6914
- export const $CreateBeanPriceDto = {
6915
- type: 'object',
6916
- properties: {
6917
- currency: {
6918
- type: 'string',
6919
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6920
- example: 'USD'
6921
- },
6922
- quoteCurrency: {
6923
- type: 'string',
6924
- description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
6925
- example: 'CNY'
6926
- },
6927
- amount: {
6928
- type: 'number',
6929
- description:
6930
- 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
6931
- example: 175.5,
6932
- minimum: 0
6933
- },
6934
- date: {
6935
- type: 'string',
6936
- description: 'Price date (ISO 8601 format)',
6937
- example: '2024-11-05'
6938
- },
6939
- metadata: {
6940
- type: 'object',
6941
- description:
6942
- 'Metadata (validated by Zod schema, max field lengths enforced)',
6943
- example: {
6944
- source: 'MANUAL',
6945
- note: 'Bank valuation report',
6946
- confidence: 0.95
6947
- }
6948
- }
6949
- },
6950
- required: ['currency', 'quoteCurrency', 'amount', 'date']
6951
- } as const;
6952
-
6953
- export const $PriceResponseDto = {
6954
- type: 'object',
6955
- properties: {
6956
- id: {
6957
- type: 'string',
6958
- description: 'Unique identifier',
6959
- example: 'uuid-123-456'
6960
- },
6961
- userId: {
6962
- type: 'string',
6963
- description: 'User ID (owner of the price)',
6964
- example: 'user-123'
6965
- },
6966
- currency: {
6967
- type: 'string',
6968
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
6969
- example: 'BTC'
6970
- },
6971
- quoteCurrency: {
6972
- type: 'string',
6973
- description: 'Quote currency (pricing currency, e.g., USD, CNY)',
6974
- example: 'USD'
6975
- },
6976
- amount: {
6977
- type: 'number',
6978
- description:
6979
- 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
6980
- example: 50000
6981
- },
6982
- date: {
6983
- type: 'string',
6984
- description:
6985
- 'Price date (ISO 8601 format). Represents the date this price was valid.',
6986
- example: '2024-01-01',
6987
- format: 'date'
6988
- },
6989
- meta: {
6990
- type: 'object',
6991
- description:
6992
- 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
6993
- example: {
6994
- source: 'MANUAL',
6995
- note: 'User-defined price',
6996
- confidence: 1
6997
- }
6998
- },
6999
- createdAt: {
7000
- format: 'date-time',
7001
- type: 'string',
7002
- description: 'Creation timestamp',
7003
- example: '2024-11-03T10:00:00Z'
7004
- },
7005
- updatedAt: {
7006
- format: 'date-time',
7007
- type: 'string',
7008
- description: 'Last update timestamp',
7009
- example: '2024-11-03T10:00:00Z'
7010
- }
7011
- },
7012
- required: [
7013
- 'id',
7014
- 'userId',
7015
- 'currency',
7016
- 'quoteCurrency',
7017
- 'amount',
7018
- 'date',
7019
- 'meta',
7020
- 'createdAt',
7021
- 'updatedAt'
7022
- ]
7023
- } as const;
7024
-
7025
- export const $PriceListResponseDto = {
7026
- type: 'object',
7027
- properties: {
7028
- items: {
7029
- description: 'List of prices',
7030
- type: 'array',
7031
- items: {
7032
- $ref: '#/components/schemas/PriceResponseDto'
7033
- }
7034
- },
7035
- total: {
7036
- type: 'number',
7037
- description: 'Total number of prices',
7038
- example: 42
7039
- }
7040
- },
7041
- required: ['items', 'total']
7042
- } as const;
7043
-
7044
- export const $UpdateBeanPriceDto = {
7045
- type: 'object',
7046
- properties: {
7047
- currency: {
7048
- type: 'string',
7049
- description: 'Currency being priced'
7050
- },
7051
- quoteCurrency: {
7052
- type: 'string',
7053
- description: 'Quote currency (pricing currency)'
7054
- },
7055
- amount: {
7056
- type: 'number',
7057
- description: 'Price amount (MUST be >= 0 per Beancount spec)',
7058
- minimum: 0
7059
- },
7060
- date: {
7061
- type: 'string',
7062
- description: 'Price date (ISO 8601 format)'
7063
- },
7064
- metadata: {
7065
- type: 'object',
7066
- description: 'Metadata'
7067
- }
7068
- }
8300
+ 'accountPath',
8301
+ 'symbol',
8302
+ 'chartToken',
8303
+ 'assetClass',
8304
+ 'units'
8305
+ ]
7069
8306
  } as const;
7070
8307
 
7071
- export const $CurrencyBalanceDto = {
8308
+ export const $HoldingPnlWarningDto = {
7072
8309
  type: 'object',
7073
8310
  properties: {
7074
- currency: {
8311
+ type: {
7075
8312
  type: 'string',
7076
- description: 'ISO 4217 currency code',
7077
- 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
+ ]
7078
8324
  },
7079
- balance: {
7080
- type: 'string',
7081
- description: 'Balance amount',
7082
- 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
7083
8336
  }
7084
8337
  },
7085
- required: ['currency', 'balance']
8338
+ required: ['type']
7086
8339
  } as const;
7087
8340
 
7088
- export const $TimeSeriesPointDto = {
8341
+ export const $HoldingPnlResponseDto = {
7089
8342
  type: 'object',
7090
8343
  properties: {
7091
- date: {
8344
+ asOfDate: {
7092
8345
  type: 'string',
7093
- description: 'Date in YYYY-MM-DD format',
7094
- example: '2024-06-15'
8346
+ example: '2026-07-08'
7095
8347
  },
7096
- value: {
8348
+ baseCurrency: {
7097
8349
  type: 'string',
7098
- description: 'Value at this date (in base currency)',
7099
- example: '500000.00'
8350
+ example: 'CNY'
7100
8351
  },
7101
- change: {
7102
- type: 'object',
7103
- description: 'Change from previous point',
7104
- 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'
7105
8358
  },
7106
- byCurrency: {
7107
- description: 'Multi-currency breakdown for this point',
8359
+ rows: {
7108
8360
  type: 'array',
7109
8361
  items: {
7110
- $ref: '#/components/schemas/CurrencyBalanceDto'
8362
+ $ref: '#/components/schemas/HoldingPnlRowDto'
8363
+ }
8364
+ },
8365
+ warnings: {
8366
+ type: 'array',
8367
+ items: {
8368
+ $ref: '#/components/schemas/HoldingPnlWarningDto'
7111
8369
  }
7112
8370
  }
7113
8371
  },
7114
- required: ['date', 'value']
8372
+ required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
7115
8373
  } as const;
7116
8374
 
7117
- export const $TrendSummaryDto = {
8375
+ export const $AnonymousLoginDto = {
7118
8376
  type: 'object',
7119
8377
  properties: {
7120
- startValue: {
7121
- type: 'string',
7122
- description: 'Value at start of period',
7123
- example: '450000.00'
7124
- },
7125
- endValue: {
7126
- type: 'string',
7127
- description: 'Value at end of period',
7128
- example: '500000.00'
7129
- },
7130
- totalChange: {
7131
- type: 'string',
7132
- description: 'Total change over period',
7133
- example: '50000.00'
7134
- },
7135
- totalChangePercentage: {
8378
+ accessToken: {
7136
8379
  type: 'string',
7137
- description: 'Total change percentage',
7138
- example: '+11.11%'
8380
+ description: 'Access token for anonymous login'
7139
8381
  }
7140
8382
  },
7141
- required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
8383
+ required: ['accessToken']
7142
8384
  } as const;
7143
8385
 
7144
- export const $MultiCurrencyPointDto = {
8386
+ export const $AnonymousLoginResponseDto = {
7145
8387
  type: 'object',
7146
8388
  properties: {
7147
- date: {
8389
+ authToken: {
7148
8390
  type: 'string',
7149
- description: 'Date in YYYY-MM-DD format',
7150
- example: '2024-06-15'
7151
- },
7152
- byCurrency: {
7153
- description: 'Balances by currency',
7154
- type: 'array',
7155
- items: {
7156
- $ref: '#/components/schemas/CurrencyBalanceDto'
7157
- }
8391
+ description: 'JWT auth token',
8392
+ example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
7158
8393
  }
7159
8394
  },
7160
- required: ['date', 'byCurrency']
8395
+ required: ['authToken']
7161
8396
  } as const;
7162
8397
 
7163
- export const $PortfolioTrendsResponseDto = {
8398
+ export const $SymbolSearchResultDto = {
7164
8399
  type: 'object',
7165
8400
  properties: {
7166
- series: {
7167
- description: 'Time series data points',
7168
- type: 'array',
7169
- items: {
7170
- $ref: '#/components/schemas/TimeSeriesPointDto'
7171
- }
8401
+ symbol: {
8402
+ type: 'string',
8403
+ example: 'AAPL'
7172
8404
  },
7173
- summary: {
7174
- description: 'Period summary',
7175
- allOf: [
7176
- {
7177
- $ref: '#/components/schemas/TrendSummaryDto'
7178
- }
7179
- ]
8405
+ name: {
8406
+ type: 'object',
8407
+ example: 'Apple Inc.',
8408
+ nullable: true
7180
8409
  },
7181
- period: {
7182
- type: 'string',
7183
- description: 'Period requested',
7184
- example: '6m'
8410
+ exchange: {
8411
+ type: 'object',
8412
+ example: 'US',
8413
+ nullable: true
7185
8414
  },
7186
- granularity: {
7187
- type: 'string',
7188
- description: 'Data granularity',
7189
- example: 'month'
8415
+ assetType: {
8416
+ type: 'object',
8417
+ description: 'OpenBB asset_type (e.g. stock, etf)',
8418
+ example: 'stock',
8419
+ nullable: true
7190
8420
  },
7191
- currency: {
7192
- type: 'string',
7193
- description: 'Base currency for converted values',
7194
- example: 'CNY'
8421
+ assetClass: {
8422
+ type: 'object',
8423
+ description: 'IGN asset class (region.types.ts ASSET_CLASSES)',
8424
+ example: 'EQUITY',
8425
+ nullable: true
7195
8426
  },
7196
- byCurrency: {
7197
- description:
7198
- 'Multi-currency time series (each point has currency breakdown)',
7199
- type: 'array',
7200
- items: {
7201
- $ref: '#/components/schemas/MultiCurrencyPointDto'
7202
- }
8427
+ assetSubClass: {
8428
+ type: 'object',
8429
+ description: 'IGN asset sub-class (region.types.ts ASSET_SUB_CLASSES)',
8430
+ example: 'STOCK',
8431
+ nullable: true
7203
8432
  },
7204
- warnings: {
7205
- description: 'Exchange rate warnings',
7206
- type: 'array',
7207
- items: {
7208
- $ref: '#/components/schemas/ExchangeRateWarningDto'
7209
- }
8433
+ currency: {
8434
+ type: 'object',
8435
+ description: 'Trading currency (extra_data or inferred from exchange)',
8436
+ example: 'USD',
8437
+ nullable: true
7210
8438
  }
7211
8439
  },
7212
- required: ['series', 'summary', 'period', 'granularity', 'currency']
7213
- } as const;
7214
-
7215
- export const $GenerateSnapshotBody = {
7216
- type: 'object',
7217
- properties: {}
7218
- } as const;
7219
-
7220
- export const $GenerateSnapshotResponse = {
7221
- type: 'object',
7222
- properties: {}
7223
- } as const;
7224
-
7225
- export const $BackfillSnapshotsBody = {
7226
- type: 'object',
7227
- properties: {}
7228
- } as const;
7229
-
7230
- export const $BackfillSnapshotsResponse = {
7231
- type: 'object',
7232
- properties: {}
8440
+ required: ['symbol']
7233
8441
  } as const;
7234
8442
 
7235
- export const $AnonymousLoginDto = {
8443
+ export const $SymbolQuoteDto = {
7236
8444
  type: 'object',
7237
8445
  properties: {
7238
- accessToken: {
8446
+ symbol: {
7239
8447
  type: 'string',
7240
- 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
7241
8537
  }
7242
- },
7243
- required: ['accessToken']
8538
+ }
7244
8539
  } as const;