@firela/api-types 0.0.0-canary.45a6cc23 → 0.0.0-canary.505aa62c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,18 +6,12 @@ export const $CreateAccountDto = {
6
6
  path: {
7
7
  type: 'string',
8
8
  description: 'Account path (hierarchical, colon-separated)',
9
- example: 'Assets:CN:Bank:ICBC:Checking'
10
- },
11
- displayName: {
12
- type: 'string',
13
- description:
14
- 'Display name to distinguish accounts at the same path (default: "")',
15
- example: '工资卡'
9
+ example: 'Assets:CN:ICBC:Checking'
16
10
  },
17
11
  openDate: {
18
12
  format: 'date-time',
19
13
  type: 'string',
20
- description: 'Account open date',
14
+ description: 'Account open date (server defaults to today)',
21
15
  example: '2024-01-01'
22
16
  },
23
17
  currencies: {
@@ -45,26 +39,22 @@ export const $CreateAccountDto = {
45
39
  templatePath: {
46
40
  type: 'string',
47
41
  description: 'Reference to account-standards template path',
48
- example: 'Assets:CN:Bank:ICBC:Checking'
42
+ example: 'Assets:CN:Checking'
49
43
  },
50
44
  isCustom: {
51
45
  type: 'boolean',
52
46
  description: 'Whether this is a custom (user-created) account',
53
47
  default: false
54
48
  },
55
- i18nKey: {
56
- type: 'string',
57
- description: 'i18n key for display name (overrides template)',
58
- example: 'account.custom.mybank'
59
- },
60
49
  icon: {
61
50
  type: 'string',
62
51
  description: 'Icon identifier (overrides template)',
63
52
  example: 'bank-custom'
64
53
  },
65
- openMeta: {
54
+ openDirectiveMeta: {
66
55
  type: 'object',
67
- description: 'Additional metadata',
56
+ description:
57
+ 'Open directive metadata (NOT an opening-balance amount — use the opening-balance endpoint)',
68
58
  example: {
69
59
  branch: 'Downtown',
70
60
  accountNumber: '1234'
@@ -76,7 +66,7 @@ export const $CreateAccountDto = {
76
66
  example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
77
67
  }
78
68
  },
79
- required: ['path', 'openDate']
69
+ required: ['path']
80
70
  } as const;
81
71
 
82
72
  export const $AccountResponseDto = {
@@ -90,13 +80,7 @@ export const $AccountResponseDto = {
90
80
  path: {
91
81
  type: 'string',
92
82
  description: 'Account path (hierarchical, colon-separated)',
93
- example: 'Assets:CN:Bank:ICBC:Checking'
94
- },
95
- displayName: {
96
- type: 'string',
97
- description:
98
- 'Display name distinguishing multiple accounts at the same path',
99
- example: '工资卡'
83
+ example: 'Assets:CN:ICBC:Checking'
100
84
  },
101
85
  type: {
102
86
  type: 'string',
@@ -145,26 +129,26 @@ export const $AccountResponseDto = {
145
129
  templatePath: {
146
130
  type: 'string',
147
131
  description: 'Template path reference',
148
- example: 'Assets:CN:Bank:ICBC:Checking'
132
+ example: 'Assets:CN:Checking'
149
133
  },
150
134
  isCustom: {
151
135
  type: 'boolean',
152
136
  description: 'Whether this is a custom (user-created) account',
153
137
  example: false
154
138
  },
155
- i18nKey: {
139
+ displayName: {
156
140
  type: 'string',
157
- description: 'i18n key for display name',
158
- example: 'account.assets.cn.bank.icbc.checking'
141
+ description: 'Localized display name (ADR-0114, read-time projection)',
142
+ example: 'Checking'
159
143
  },
160
144
  icon: {
161
145
  type: 'string',
162
146
  description: 'Icon identifier',
163
147
  example: 'bank-icbc'
164
148
  },
165
- openMeta: {
149
+ openDirectiveMeta: {
166
150
  type: 'object',
167
- description: 'Account metadata',
151
+ description: 'Open directive metadata (ADR-0115 Decision 9)',
168
152
  example: {
169
153
  branch: 'Downtown'
170
154
  }
@@ -192,7 +176,6 @@ export const $AccountResponseDto = {
192
176
  required: [
193
177
  'id',
194
178
  'path',
195
- 'displayName',
196
179
  'type',
197
180
  'status',
198
181
  'openDate',
@@ -225,11 +208,6 @@ export const $AccountListResponseDto = {
225
208
  export const $UpdateAccountDto = {
226
209
  type: 'object',
227
210
  properties: {
228
- displayName: {
229
- type: 'string',
230
- description: 'Display name to distinguish accounts at the same path',
231
- example: '招行工资卡'
232
- },
233
211
  currencies: {
234
212
  description: 'Allowed currencies (null = no restriction)',
235
213
  example: ['CNY', 'USD'],
@@ -251,19 +229,15 @@ export const $UpdateAccountDto = {
251
229
  'NONE'
252
230
  ]
253
231
  },
254
- i18nKey: {
255
- type: 'string',
256
- description: 'i18n key for display name',
257
- example: 'account.custom.mybank'
258
- },
259
232
  icon: {
260
233
  type: 'string',
261
234
  description: 'Icon identifier',
262
235
  example: 'bank-custom'
263
236
  },
264
- openMeta: {
237
+ openDirectiveMeta: {
265
238
  type: 'object',
266
- description: 'Additional metadata (merged with existing)',
239
+ description:
240
+ 'Open directive metadata (merged with existing; NOT an opening-balance amount)',
267
241
  example: {
268
242
  branch: 'Uptown'
269
243
  }
@@ -310,13 +284,47 @@ export const $ReopenAccountDto = {
310
284
  }
311
285
  } as const;
312
286
 
287
+ export const $CreateOpeningBalanceDto = {
288
+ type: 'object',
289
+ properties: {
290
+ amount: {
291
+ type: 'number',
292
+ description: 'Opening balance amount (non-negative)',
293
+ example: 1000
294
+ },
295
+ currency: {
296
+ type: 'string',
297
+ description: 'Currency code',
298
+ example: 'CNY'
299
+ },
300
+ date: {
301
+ format: 'date-time',
302
+ type: 'string',
303
+ description: 'Opening-balance date (defaults to now)',
304
+ example: '2024-01-01'
305
+ }
306
+ },
307
+ required: ['amount', 'currency']
308
+ } as const;
309
+
310
+ export const $OpeningBalanceResultDto = {
311
+ type: 'object',
312
+ properties: {
313
+ transactionId: {
314
+ type: 'string',
315
+ description: 'Created opening-balance transaction id.'
316
+ }
317
+ },
318
+ required: ['transactionId']
319
+ } as const;
320
+
313
321
  export const $AccountStandardResponseDto = {
314
322
  type: 'object',
315
323
  properties: {
316
324
  path: {
317
325
  type: 'string',
318
326
  description: 'Account path (hierarchical, colon-separated)',
319
- example: 'Assets:CN:Bank:ICBC:Checking'
327
+ example: 'Assets:CN:Checking'
320
328
  },
321
329
  type: {
322
330
  type: 'string',
@@ -324,11 +332,6 @@ export const $AccountStandardResponseDto = {
324
332
  enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
325
333
  example: 'Assets'
326
334
  },
327
- i18nKey: {
328
- type: 'string',
329
- description: 'i18n key for localized display name',
330
- example: 'account.assets.cn.bank.icbc.checking'
331
- },
332
335
  name: {
333
336
  type: 'string',
334
337
  description: 'Short localized display name',
@@ -353,7 +356,7 @@ export const $AccountStandardResponseDto = {
353
356
  example: 'bank-icbc'
354
357
  }
355
358
  },
356
- required: ['path', 'type', 'i18nKey', 'description', 'tags', 'icon']
359
+ required: ['path', 'type', 'description', 'tags', 'icon']
357
360
  } as const;
358
361
 
359
362
  export const $AccountStandardListResponseDto = {
@@ -383,18 +386,13 @@ export const $AccountStandardListResponseDto = {
383
386
  export const $TemplateMetadataDto = {
384
387
  type: 'object',
385
388
  properties: {
386
- extendable: {
387
- type: 'boolean',
388
- description: 'Whether this path can be extended',
389
- example: true
390
- },
391
389
  rootType: {
392
390
  type: 'string',
393
391
  description: 'Root account type',
394
392
  example: 'Assets'
395
393
  }
396
394
  },
397
- required: ['extendable', 'rootType']
395
+ required: ['rootType']
398
396
  } as const;
399
397
 
400
398
  export const $TemplateMetadataResponseDto = {
@@ -533,7 +531,7 @@ export const $CreatePostingDto = {
533
531
  type: 'string',
534
532
  description:
535
533
  'Account name in Beancount format (must start with uppercase, colon-separated)',
536
- example: 'Assets:Bank:Checking'
534
+ example: 'Assets:Checking'
537
535
  },
538
536
  units: {
539
537
  type: 'string',
@@ -692,7 +690,7 @@ export const $PostingResponseDto = {
692
690
  account: {
693
691
  type: 'string',
694
692
  description: 'Account name',
695
- example: 'Assets:Bank:Checking'
693
+ example: 'Assets:Checking'
696
694
  },
697
695
  units: {
698
696
  type: 'string',
@@ -1058,7 +1056,7 @@ export const $PostingDetailDto = {
1058
1056
  account: {
1059
1057
  type: 'string',
1060
1058
  description: 'Fully-qualified Beancount account path',
1061
- example: 'Assets:Bank:Checking'
1059
+ example: 'Assets:Checking'
1062
1060
  },
1063
1061
  units: {
1064
1062
  type: 'string',
@@ -1247,6 +1245,77 @@ export const $TransactionDetailDto = {
1247
1245
  ]
1248
1246
  } as const;
1249
1247
 
1248
+ export const $BalanceByCurrencyDto = {
1249
+ type: 'object',
1250
+ properties: {
1251
+ currency: {
1252
+ type: 'string',
1253
+ description: 'ISO 4217 currency code',
1254
+ example: 'CNY'
1255
+ },
1256
+ balance: {
1257
+ type: 'string',
1258
+ description: 'Balance amount',
1259
+ example: '50000.00'
1260
+ }
1261
+ },
1262
+ required: ['currency', 'balance']
1263
+ } as const;
1264
+
1265
+ export const $ExchangeRateWarningDto = {
1266
+ type: 'object',
1267
+ properties: {
1268
+ type: {
1269
+ type: 'string',
1270
+ description: 'Warning type',
1271
+ example: 'MISSING_EXCHANGE_RATE'
1272
+ },
1273
+ currency: {
1274
+ type: 'string',
1275
+ description: 'Currency without exchange rate',
1276
+ example: 'EUR'
1277
+ },
1278
+ totalAmount: {
1279
+ type: 'string',
1280
+ description: 'Total amount affected',
1281
+ example: '1000.00'
1282
+ }
1283
+ },
1284
+ required: ['type', 'currency', 'totalAmount']
1285
+ } as const;
1286
+
1287
+ export const $TransactionListSummaryDto = {
1288
+ type: 'object',
1289
+ properties: {
1290
+ totalAmount: {
1291
+ type: 'string',
1292
+ description:
1293
+ 'Partial converted total in base currency (rated currencies only, raw Beancount sign). When warnings is non-empty this excludes currencies missing an FX rate; may be "0.00" if ALL non-base currencies lack a rate. Converted at the dateTo (or current) available rate.',
1294
+ example: '-6000.00'
1295
+ },
1296
+ currency: {
1297
+ type: 'string',
1298
+ description: 'Base currency (ISO 4217)',
1299
+ example: 'CNY'
1300
+ },
1301
+ balanceByCurrency: {
1302
+ description: 'Raw (unconverted) balance per currency',
1303
+ type: 'array',
1304
+ items: {
1305
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
1306
+ }
1307
+ },
1308
+ warnings: {
1309
+ description: 'Currencies missing an FX rate (omitted when empty)',
1310
+ type: 'array',
1311
+ items: {
1312
+ $ref: '#/components/schemas/ExchangeRateWarningDto'
1313
+ }
1314
+ }
1315
+ },
1316
+ required: ['totalAmount', 'currency', 'balanceByCurrency']
1317
+ } as const;
1318
+
1250
1319
  export const $TransactionListResponseDto = {
1251
1320
  type: 'object',
1252
1321
  properties: {
@@ -1271,6 +1340,15 @@ export const $TransactionListResponseDto = {
1271
1340
  type: 'number',
1272
1341
  description: 'Number of items skipped',
1273
1342
  example: 0
1343
+ },
1344
+ summary: {
1345
+ description:
1346
+ '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.',
1347
+ allOf: [
1348
+ {
1349
+ $ref: '#/components/schemas/TransactionListSummaryDto'
1350
+ }
1351
+ ]
1274
1352
  }
1275
1353
  },
1276
1354
  required: ['data', 'total', 'limit', 'offset']
@@ -1370,7 +1448,7 @@ export const $BalanceResponseDto = {
1370
1448
  account: {
1371
1449
  type: 'string',
1372
1450
  description: 'Account name',
1373
- example: 'Assets:Bank:Checking'
1451
+ example: 'Assets:Checking'
1374
1452
  },
1375
1453
  balance: {
1376
1454
  type: 'string',
@@ -1397,7 +1475,7 @@ export const $MultiCurrencyBalanceResponseDto = {
1397
1475
  account: {
1398
1476
  type: 'string',
1399
1477
  description: 'Account name',
1400
- example: 'Assets:Bank:Checking'
1478
+ example: 'Assets:Checking'
1401
1479
  },
1402
1480
  balances: {
1403
1481
  type: 'object',
@@ -1453,7 +1531,7 @@ export const $TransactionSummaryDto = {
1453
1531
  accountName: {
1454
1532
  type: 'string',
1455
1533
  description: 'Source account name (first posting)',
1456
- example: 'Assets:Bank:Checking'
1534
+ example: 'Assets:Checking'
1457
1535
  },
1458
1536
  sourceType: {
1459
1537
  type: 'string',
@@ -2745,127 +2823,284 @@ export const $UpdateCommodityDto = {
2745
2823
  }
2746
2824
  } as const;
2747
2825
 
2748
- export const $CreateRecurringRuleDto = {
2826
+ export const $CreateBeanPriceDto = {
2749
2827
  type: 'object',
2750
2828
  properties: {
2751
- name: {
2752
- type: 'string',
2753
- description: 'Rule name (unique per user)',
2754
- maxLength: 100
2755
- },
2756
- icon: {
2757
- type: 'string',
2758
- description: 'Icon emoji',
2759
- maxLength: 10
2760
- },
2761
- frequency: {
2762
- type: 'string',
2763
- description: 'Recurring frequency',
2764
- enum: [
2765
- 'WEEKLY',
2766
- 'BIWEEKLY',
2767
- 'MONTHLY',
2768
- 'BIMONTHLY',
2769
- 'QUARTERLY',
2770
- 'YEARLY',
2771
- 'CUSTOM'
2772
- ]
2773
- },
2774
- expectedAmount: {
2775
- type: 'number',
2776
- description: 'Expected amount (positive number)',
2777
- minimum: 0
2778
- },
2779
- expectedDay: {
2780
- type: 'number',
2781
- description: 'Expected day of month (1-31)',
2782
- minimum: 1,
2783
- maximum: 31
2784
- },
2785
- customIntervalDays: {
2786
- type: 'number',
2787
- description: 'Custom interval in days (required for CUSTOM frequency)',
2788
- minimum: 1
2789
- },
2790
2829
  currency: {
2791
2830
  type: 'string',
2792
- description: 'Currency code',
2793
- default: 'CNY',
2794
- maxLength: 10
2831
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2832
+ example: 'USD'
2795
2833
  },
2796
- matchPayeePattern: {
2834
+ quoteCurrency: {
2797
2835
  type: 'string',
2798
- description: 'Payee matching pattern (supports wildcards)',
2799
- maxLength: 200
2836
+ description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
2837
+ example: 'CNY'
2800
2838
  },
2801
- matchAmountTolerance: {
2839
+ amount: {
2802
2840
  type: 'number',
2803
- description: 'Amount tolerance percentage (0-1)',
2804
- default: 0.075,
2805
- minimum: 0,
2806
- maximum: 1
2807
- },
2808
- defaultExpenseAccount: {
2809
- type: 'string',
2810
- description: 'Default expense account for auto-create',
2811
- maxLength: 200
2812
- },
2813
- defaultPaymentAccount: {
2814
- type: 'string',
2815
- description: 'Default payment account for auto-create',
2816
- maxLength: 200
2817
- },
2818
- defaultPayee: {
2819
- type: 'string',
2820
- description: 'Default payee for auto-create',
2821
- maxLength: 200
2822
- },
2823
- autoCreate: {
2824
- type: 'boolean',
2825
- description: 'Auto-create transaction when expected date arrives',
2826
- default: false
2841
+ description:
2842
+ 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
2843
+ example: 175.5,
2844
+ minimum: 0
2827
2845
  },
2828
- startDate: {
2846
+ date: {
2829
2847
  type: 'string',
2830
- description: 'Rule start date (ISO format)'
2848
+ description: 'Price date (ISO 8601 format)',
2849
+ example: '2024-11-05'
2831
2850
  },
2832
- endDate: {
2833
- type: 'string',
2834
- description: 'Rule end date (ISO format)'
2851
+ metadata: {
2852
+ type: 'object',
2853
+ description:
2854
+ 'Metadata (validated by Zod schema, max field lengths enforced)',
2855
+ example: {
2856
+ source: 'MANUAL',
2857
+ note: 'Bank valuation report',
2858
+ confidence: 0.95
2859
+ }
2835
2860
  }
2836
2861
  },
2837
- required: [
2838
- 'name',
2839
- 'frequency',
2840
- 'expectedAmount',
2841
- 'currency',
2842
- 'matchAmountTolerance',
2843
- 'autoCreate'
2844
- ]
2862
+ required: ['currency', 'quoteCurrency', 'amount', 'date']
2845
2863
  } as const;
2846
2864
 
2847
- export const $RecurringRuleResponseDto = {
2865
+ export const $PriceResponseDto = {
2848
2866
  type: 'object',
2849
2867
  properties: {
2850
2868
  id: {
2851
2869
  type: 'string',
2852
- description: 'Rule ID'
2870
+ description: 'Unique identifier',
2871
+ example: 'uuid-123-456'
2853
2872
  },
2854
2873
  userId: {
2855
2874
  type: 'string',
2856
- description: 'User ID'
2875
+ description: 'User ID (owner of the price)',
2876
+ example: 'user-123'
2857
2877
  },
2858
- name: {
2878
+ currency: {
2859
2879
  type: 'string',
2860
- description: 'Rule name'
2861
- },
2862
- icon: {
2863
- type: 'object',
2864
- description: 'Icon emoji'
2880
+ description: 'Currency being priced (e.g., USD, AAPL, BTC)',
2881
+ example: 'BTC'
2865
2882
  },
2866
- frequency: {
2883
+ quoteCurrency: {
2867
2884
  type: 'string',
2868
- description: 'Recurring frequency'
2885
+ description: 'Quote currency (pricing currency, e.g., USD, CNY)',
2886
+ example: 'USD'
2887
+ },
2888
+ amount: {
2889
+ type: 'number',
2890
+ description:
2891
+ 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
2892
+ example: 50000
2893
+ },
2894
+ date: {
2895
+ type: 'string',
2896
+ description:
2897
+ 'Price date (ISO 8601 format). Represents the date this price was valid.',
2898
+ example: '2024-01-01',
2899
+ format: 'date'
2900
+ },
2901
+ meta: {
2902
+ type: 'object',
2903
+ description:
2904
+ 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
2905
+ example: {
2906
+ source: 'MANUAL',
2907
+ note: 'User-defined price',
2908
+ confidence: 1
2909
+ }
2910
+ },
2911
+ createdAt: {
2912
+ format: 'date-time',
2913
+ type: 'string',
2914
+ description: 'Creation timestamp',
2915
+ example: '2024-11-03T10:00:00Z'
2916
+ },
2917
+ updatedAt: {
2918
+ format: 'date-time',
2919
+ type: 'string',
2920
+ description: 'Last update timestamp',
2921
+ example: '2024-11-03T10:00:00Z'
2922
+ }
2923
+ },
2924
+ required: [
2925
+ 'id',
2926
+ 'userId',
2927
+ 'currency',
2928
+ 'quoteCurrency',
2929
+ 'amount',
2930
+ 'date',
2931
+ 'meta',
2932
+ 'createdAt',
2933
+ 'updatedAt'
2934
+ ]
2935
+ } as const;
2936
+
2937
+ export const $PriceListResponseDto = {
2938
+ type: 'object',
2939
+ properties: {
2940
+ items: {
2941
+ description: 'List of prices',
2942
+ type: 'array',
2943
+ items: {
2944
+ $ref: '#/components/schemas/PriceResponseDto'
2945
+ }
2946
+ },
2947
+ total: {
2948
+ type: 'number',
2949
+ description: 'Total number of prices',
2950
+ example: 42
2951
+ }
2952
+ },
2953
+ required: ['items', 'total']
2954
+ } as const;
2955
+
2956
+ export const $UpdateBeanPriceDto = {
2957
+ type: 'object',
2958
+ properties: {
2959
+ currency: {
2960
+ type: 'string',
2961
+ description: 'Currency being priced'
2962
+ },
2963
+ quoteCurrency: {
2964
+ type: 'string',
2965
+ description: 'Quote currency (pricing currency)'
2966
+ },
2967
+ amount: {
2968
+ type: 'number',
2969
+ description: 'Price amount (MUST be >= 0 per Beancount spec)',
2970
+ minimum: 0
2971
+ },
2972
+ date: {
2973
+ type: 'string',
2974
+ description: 'Price date (ISO 8601 format)'
2975
+ },
2976
+ metadata: {
2977
+ type: 'object',
2978
+ description: 'Metadata'
2979
+ }
2980
+ }
2981
+ } as const;
2982
+
2983
+ export const $CreateRecurringRuleDto = {
2984
+ type: 'object',
2985
+ properties: {
2986
+ name: {
2987
+ type: 'string',
2988
+ description: 'Rule name (unique per user)',
2989
+ maxLength: 100
2990
+ },
2991
+ icon: {
2992
+ type: 'string',
2993
+ description: 'Icon emoji',
2994
+ maxLength: 10
2995
+ },
2996
+ frequency: {
2997
+ type: 'string',
2998
+ description: 'Recurring frequency',
2999
+ enum: [
3000
+ 'WEEKLY',
3001
+ 'BIWEEKLY',
3002
+ 'MONTHLY',
3003
+ 'BIMONTHLY',
3004
+ 'QUARTERLY',
3005
+ 'YEARLY',
3006
+ 'CUSTOM'
3007
+ ]
3008
+ },
3009
+ expectedAmount: {
3010
+ type: 'number',
3011
+ description: 'Expected amount (positive number)',
3012
+ minimum: 0
3013
+ },
3014
+ expectedDay: {
3015
+ type: 'number',
3016
+ description: 'Expected day of month (1-31)',
3017
+ minimum: 1,
3018
+ maximum: 31
3019
+ },
3020
+ customIntervalDays: {
3021
+ type: 'number',
3022
+ description: 'Custom interval in days (required for CUSTOM frequency)',
3023
+ minimum: 1
3024
+ },
3025
+ currency: {
3026
+ type: 'string',
3027
+ description: 'Currency code',
3028
+ default: 'CNY',
3029
+ maxLength: 10
3030
+ },
3031
+ matchPayeePattern: {
3032
+ type: 'string',
3033
+ description: 'Payee matching pattern (supports wildcards)',
3034
+ maxLength: 200
3035
+ },
3036
+ matchAmountTolerance: {
3037
+ type: 'number',
3038
+ description: 'Amount tolerance percentage (0-1)',
3039
+ default: 0.075,
3040
+ minimum: 0,
3041
+ maximum: 1
3042
+ },
3043
+ defaultExpenseAccount: {
3044
+ type: 'string',
3045
+ description: 'Default expense account for auto-create',
3046
+ maxLength: 200
3047
+ },
3048
+ defaultPaymentAccount: {
3049
+ type: 'string',
3050
+ description: 'Default payment account for auto-create',
3051
+ maxLength: 200
3052
+ },
3053
+ defaultPayee: {
3054
+ type: 'string',
3055
+ description: 'Default payee for auto-create',
3056
+ maxLength: 200
3057
+ },
3058
+ autoCreate: {
3059
+ type: 'boolean',
3060
+ description: 'Auto-create transaction when expected date arrives',
3061
+ default: false
3062
+ },
3063
+ startDate: {
3064
+ type: 'string',
3065
+ description: 'Rule start date (ISO format)'
3066
+ },
3067
+ endDate: {
3068
+ type: 'string',
3069
+ description: 'Rule end date (ISO format)'
3070
+ }
3071
+ },
3072
+ required: [
3073
+ 'name',
3074
+ 'frequency',
3075
+ 'expectedAmount',
3076
+ 'currency',
3077
+ 'matchAmountTolerance',
3078
+ 'autoCreate'
3079
+ ]
3080
+ } as const;
3081
+
3082
+ export const $RecurringRuleResponseDto = {
3083
+ type: 'object',
3084
+ properties: {
3085
+ id: {
3086
+ type: 'string',
3087
+ description: 'Rule ID'
3088
+ },
3089
+ userId: {
3090
+ type: 'string',
3091
+ description: 'User ID'
3092
+ },
3093
+ name: {
3094
+ type: 'string',
3095
+ description: 'Rule name'
3096
+ },
3097
+ icon: {
3098
+ type: 'object',
3099
+ description: 'Icon emoji'
3100
+ },
3101
+ frequency: {
3102
+ type: 'string',
3103
+ description: 'Recurring frequency'
2869
3104
  },
2870
3105
  expectedAmount: {
2871
3106
  type: 'number',
@@ -4450,41 +4685,292 @@ export const $UpdateBeanEventDto = {
4450
4685
  }
4451
4686
  } as const;
4452
4687
 
4453
- export const $FileImportDto = {
4688
+ export const $OnboardingAccountDto = {
4454
4689
  type: 'object',
4455
4690
  properties: {
4456
- file: {
4691
+ path: {
4457
4692
  type: 'string',
4458
- format: 'binary',
4459
- description: 'Bill file to import (CSV, PDF, OFX, etc.)',
4460
- example: 'alipay.csv'
4461
- }
4462
- },
4463
- required: ['file']
4464
- } as const;
4465
-
4466
- export const $ImportErrorDto = {
4467
- type: 'object',
4468
- properties: {
4469
- index: {
4470
- type: 'number',
4471
- description: 'Index of failed transaction in the file',
4472
- example: 5
4693
+ description:
4694
+ 'Account path (Assets/Liabilities only; format validated by the account service)',
4695
+ example: 'Assets:Checking'
4473
4696
  },
4474
- error: {
4697
+ currency: {
4475
4698
  type: 'string',
4476
- description: 'Error message',
4477
- example: 'Transaction does not balance: -100 USD != 0'
4699
+ description: 'ISO 4217 currency code (3 letters)',
4700
+ example: 'USD'
4701
+ },
4702
+ openingBalance: {
4703
+ type: 'string',
4704
+ description:
4705
+ 'Opening balance as a non-negative Decimal string (e.g. "1000.00")',
4706
+ example: '1000.00'
4707
+ },
4708
+ platformId: {
4709
+ type: 'string',
4710
+ description:
4711
+ 'Platform ID to bind the account to (references Platform.id); omit for unbound',
4712
+ example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
4478
4713
  }
4479
4714
  },
4480
- required: ['index', 'error']
4715
+ required: ['path', 'currency']
4481
4716
  } as const;
4482
4717
 
4483
- export const $ReviewItemPreviewDto = {
4718
+ export const $OnboardingDto = {
4484
4719
  type: 'object',
4485
4720
  properties: {
4486
- index: {
4487
- type: 'number',
4721
+ accounts: {
4722
+ description: 'Asset/Liability accounts to register with opening balances',
4723
+ type: 'array',
4724
+ items: {
4725
+ $ref: '#/components/schemas/OnboardingAccountDto'
4726
+ }
4727
+ },
4728
+ skipAssetRegistration: {
4729
+ type: 'boolean',
4730
+ description:
4731
+ 'Skip asset registration; only bootstrap the core account set',
4732
+ default: false
4733
+ }
4734
+ }
4735
+ } as const;
4736
+
4737
+ export const $ActualBalanceDto = {
4738
+ type: 'object',
4739
+ properties: {
4740
+ amount: {
4741
+ type: 'string',
4742
+ description:
4743
+ 'Actual balance amount as a decimal string (preserves precision for tolerance inference).',
4744
+ example: '1234.56'
4745
+ },
4746
+ ccy: {
4747
+ type: 'string',
4748
+ description: 'Currency code (ISO 4217 or commodity ticker).',
4749
+ example: 'CNY'
4750
+ }
4751
+ },
4752
+ required: ['amount', 'ccy']
4753
+ } as const;
4754
+
4755
+ export const $ComputeReconciliationDto = {
4756
+ type: 'object',
4757
+ properties: {
4758
+ accountId: {
4759
+ type: 'string',
4760
+ description: 'BeanAccount id to reconcile.'
4761
+ },
4762
+ asOfDate: {
4763
+ type: 'string',
4764
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
4765
+ example: '2026-07-24'
4766
+ },
4767
+ actualBalance: {
4768
+ description: 'Actual balance from the external statement.',
4769
+ allOf: [
4770
+ {
4771
+ $ref: '#/components/schemas/ActualBalanceDto'
4772
+ }
4773
+ ]
4774
+ }
4775
+ },
4776
+ required: ['accountId', 'asOfDate', 'actualBalance']
4777
+ } as const;
4778
+
4779
+ export const $ReconciliationComputeResultDto = {
4780
+ type: 'object',
4781
+ properties: {
4782
+ accountId: {
4783
+ type: 'string'
4784
+ },
4785
+ asOfDate: {
4786
+ type: 'string'
4787
+ },
4788
+ bookBalance: {
4789
+ type: 'string',
4790
+ description: 'System-computed book balance (decimal string).'
4791
+ },
4792
+ actualBalance: {
4793
+ type: 'string',
4794
+ description: 'User-entered actual balance (decimal string).'
4795
+ },
4796
+ currency: {
4797
+ type: 'string'
4798
+ },
4799
+ diff: {
4800
+ type: 'string',
4801
+ description: 'Diff = book − actual (decimal string).'
4802
+ },
4803
+ tolerance: {
4804
+ type: 'string',
4805
+ description: 'Applied tolerance (decimal string).'
4806
+ },
4807
+ withinTolerance: {
4808
+ type: 'boolean',
4809
+ description: 'true when |diff| ≤ tolerance.'
4810
+ },
4811
+ suggestedAction: {
4812
+ type: 'string',
4813
+ enum: ['assert', 'pad'],
4814
+ description:
4815
+ 'Suggested next action: assert when within tolerance, pad otherwise.'
4816
+ }
4817
+ },
4818
+ required: [
4819
+ 'accountId',
4820
+ 'asOfDate',
4821
+ 'bookBalance',
4822
+ 'actualBalance',
4823
+ 'currency',
4824
+ 'diff',
4825
+ 'tolerance',
4826
+ 'withinTolerance',
4827
+ 'suggestedAction'
4828
+ ]
4829
+ } as const;
4830
+
4831
+ export const $AssertReconciliationDto = {
4832
+ type: 'object',
4833
+ properties: {
4834
+ accountId: {
4835
+ type: 'string',
4836
+ description: 'BeanAccount id to reconcile.'
4837
+ },
4838
+ asOfDate: {
4839
+ type: 'string',
4840
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
4841
+ example: '2026-07-24'
4842
+ },
4843
+ actualBalance: {
4844
+ description: 'Actual balance from the external statement.',
4845
+ allOf: [
4846
+ {
4847
+ $ref: '#/components/schemas/ActualBalanceDto'
4848
+ }
4849
+ ]
4850
+ },
4851
+ tolerance: {
4852
+ type: 'string',
4853
+ description:
4854
+ 'Optional explicit tolerance override. Omit to infer from amount precision (Beancount default).',
4855
+ example: '0.01'
4856
+ }
4857
+ },
4858
+ required: ['accountId', 'asOfDate', 'actualBalance']
4859
+ } as const;
4860
+
4861
+ export const $ReconciliationRecordDto = {
4862
+ type: 'object',
4863
+ properties: {
4864
+ id: {
4865
+ type: 'string'
4866
+ },
4867
+ accountId: {
4868
+ type: 'string'
4869
+ },
4870
+ date: {
4871
+ type: 'string'
4872
+ },
4873
+ amount: {
4874
+ type: 'string',
4875
+ description: 'Asserted (actual) amount.'
4876
+ },
4877
+ currency: {
4878
+ type: 'string'
4879
+ },
4880
+ tolerance: {
4881
+ type: 'string'
4882
+ },
4883
+ diffAmount: {
4884
+ type: 'string',
4885
+ description: 'book − actual.'
4886
+ },
4887
+ diffCurrency: {
4888
+ type: 'string'
4889
+ },
4890
+ createdAt: {
4891
+ type: 'string'
4892
+ }
4893
+ },
4894
+ required: ['id', 'accountId', 'date', 'amount', 'currency', 'createdAt']
4895
+ } as const;
4896
+
4897
+ export const $PadReconciliationDto = {
4898
+ type: 'object',
4899
+ properties: {
4900
+ accountId: {
4901
+ type: 'string',
4902
+ description: 'BeanAccount id to reconcile.'
4903
+ },
4904
+ asOfDate: {
4905
+ type: 'string',
4906
+ description: 'Assertion date (ISO 8601, e.g. "2026-07-24").',
4907
+ example: '2026-07-24'
4908
+ },
4909
+ actualBalance: {
4910
+ description: 'Actual balance from the external statement.',
4911
+ allOf: [
4912
+ {
4913
+ $ref: '#/components/schemas/ActualBalanceDto'
4914
+ }
4915
+ ]
4916
+ },
4917
+ sourceAccount: {
4918
+ type: 'string',
4919
+ description:
4920
+ 'Pad source account. Defaults to Equity:Opening-Balances (official Beancount convention).',
4921
+ example: 'Equity:Opening-Balances',
4922
+ default: 'Equity:Opening-Balances'
4923
+ }
4924
+ },
4925
+ required: ['accountId', 'asOfDate', 'actualBalance']
4926
+ } as const;
4927
+
4928
+ export const $PadResultDto = {
4929
+ type: 'object',
4930
+ properties: {
4931
+ transactionId: {
4932
+ type: 'string',
4933
+ description: 'Created pad adjusting transaction id.'
4934
+ }
4935
+ },
4936
+ required: ['transactionId']
4937
+ } as const;
4938
+
4939
+ export const $FileImportDto = {
4940
+ type: 'object',
4941
+ properties: {
4942
+ file: {
4943
+ type: 'string',
4944
+ format: 'binary',
4945
+ description: 'Bill file to import (CSV, PDF, OFX, etc.)',
4946
+ example: 'alipay.csv'
4947
+ }
4948
+ },
4949
+ required: ['file']
4950
+ } as const;
4951
+
4952
+ export const $ImportErrorDto = {
4953
+ type: 'object',
4954
+ properties: {
4955
+ index: {
4956
+ type: 'number',
4957
+ description: 'Index of failed transaction in the file',
4958
+ example: 5
4959
+ },
4960
+ error: {
4961
+ type: 'string',
4962
+ description: 'Error message',
4963
+ example: 'Transaction does not balance: -100 USD != 0'
4964
+ }
4965
+ },
4966
+ required: ['index', 'error']
4967
+ } as const;
4968
+
4969
+ export const $ReviewItemPreviewDto = {
4970
+ type: 'object',
4971
+ properties: {
4972
+ index: {
4973
+ type: 'number',
4488
4974
  description: 'Index in the import batch (for tracking)',
4489
4975
  example: 0
4490
4976
  },
@@ -4616,7 +5102,7 @@ export const $IdentifyResultDto = {
4616
5102
  account: {
4617
5103
  type: 'string',
4618
5104
  description: 'Default account used by this importer',
4619
- example: 'Assets:Alipay:Balance'
5105
+ example: 'Assets:CN:Alipay:Balance'
4620
5106
  },
4621
5107
  message: {
4622
5108
  type: 'string',
@@ -4633,7 +5119,7 @@ export const $MapperDefaultsDto = {
4633
5119
  sourceAccount: {
4634
5120
  type: 'string',
4635
5121
  description: 'Source account for transactions (Beancount format)',
4636
- example: 'Assets:Alipay:Balance'
5122
+ example: 'Assets:CN:Alipay:Balance'
4637
5123
  },
4638
5124
  currency: {
4639
5125
  type: 'string',
@@ -4670,7 +5156,7 @@ export const $MapperDefaultsDto = {
4670
5156
  description:
4671
5157
  '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
5158
  example: {
4673
- HuaBei: 'Liabilities:Alipay:Huabei',
5159
+ HuaBei: 'Liabilities:CN:CreditLine',
4674
5160
  CreditCard: 'Liabilities:CreditCard'
4675
5161
  }
4676
5162
  }
@@ -4802,7 +5288,7 @@ export const $UpdateMapperDefaultsDto = {
4802
5288
  sourceAccount: {
4803
5289
  type: 'string',
4804
5290
  description: 'Source account for transactions (Beancount format)',
4805
- example: 'Assets:Alipay:Balance',
5291
+ example: 'Assets:CN:Alipay:Balance',
4806
5292
  pattern: '^[A-Z][a-zA-Z0-9-]*:[a-zA-Z0-9-:]+$'
4807
5293
  },
4808
5294
  currency: {
@@ -4830,7 +5316,7 @@ export const $UpdateMapperDefaultsDto = {
4830
5316
  description:
4831
5317
  '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
5318
  example: {
4833
- HuaBei: 'Liabilities:Alipay:Huabei',
5319
+ HuaBei: 'Liabilities:CN:CreditLine',
4834
5320
  CreditCard: 'Liabilities:CreditCard'
4835
5321
  }
4836
5322
  }
@@ -4865,119 +5351,13 @@ export const $UpdateImporterConfigDto = {
4865
5351
  }
4866
5352
  } as const;
4867
5353
 
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
5354
  export const $ProviderSyncConfigDto = {
4975
5355
  type: 'object',
4976
5356
  properties: {
4977
5357
  sourceAccount: {
4978
5358
  type: 'string',
4979
5359
  description: 'Source account for the first posting',
4980
- example: 'Assets:Bank:Chase'
5360
+ example: 'Assets:US:Chase:Checking'
4981
5361
  },
4982
5362
  defaultCurrency: {
4983
5363
  type: 'string',
@@ -4998,6 +5378,12 @@ export const $ProviderSyncConfigDto = {
4998
5378
  type: 'boolean',
4999
5379
  description: 'Filter pending transactions',
5000
5380
  default: true
5381
+ },
5382
+ externalAccountId: {
5383
+ type: 'string',
5384
+ description:
5385
+ 'External account ID for per-batch providers (e.g. GoCardless). Overrides sourceAccount when an ExternalAccountLink mapping exists.',
5386
+ example: 'acc_gocardless_001'
5001
5387
  }
5002
5388
  },
5003
5389
  required: [
@@ -5117,6 +5503,94 @@ export const $SupportedProvidersResponseDto = {
5117
5503
  required: ['providers']
5118
5504
  } as const;
5119
5505
 
5506
+ export const $CreateExternalAccountLinkDto = {
5507
+ type: 'object',
5508
+ properties: {
5509
+ provider: {
5510
+ type: 'string',
5511
+ enum: [
5512
+ 'plaid',
5513
+ 'teller',
5514
+ 'truelayer',
5515
+ 'gocardless',
5516
+ 'simplefin',
5517
+ 'yodlee',
5518
+ 'beancount-direct',
5519
+ 'parsed-bill'
5520
+ ],
5521
+ example: 'plaid',
5522
+ description: 'Open Banking provider (whitelist)'
5523
+ },
5524
+ externalAccountId: {
5525
+ type: 'string',
5526
+ example: 'acc-plaid-001',
5527
+ description: 'External account ID from the provider'
5528
+ },
5529
+ beanAccountId: {
5530
+ type: 'string',
5531
+ example: '550e8400-e29b-41d4-a716-446655440000',
5532
+ description: 'Target BeanAccount ID (must belong to the JWT user)'
5533
+ }
5534
+ },
5535
+ required: ['provider', 'externalAccountId', 'beanAccountId']
5536
+ } as const;
5537
+
5538
+ export const $ExternalAccountLinkResponseDto = {
5539
+ type: 'object',
5540
+ properties: {
5541
+ id: {
5542
+ type: 'string'
5543
+ },
5544
+ provider: {
5545
+ type: 'string'
5546
+ },
5547
+ externalAccountId: {
5548
+ type: 'string'
5549
+ },
5550
+ beanAccountId: {
5551
+ type: 'string'
5552
+ },
5553
+ isActive: {
5554
+ type: 'boolean'
5555
+ },
5556
+ createdAt: {
5557
+ type: 'string'
5558
+ },
5559
+ updatedAt: {
5560
+ type: 'string'
5561
+ }
5562
+ },
5563
+ required: [
5564
+ 'id',
5565
+ 'provider',
5566
+ 'externalAccountId',
5567
+ 'beanAccountId',
5568
+ 'isActive',
5569
+ 'createdAt',
5570
+ 'updatedAt'
5571
+ ]
5572
+ } as const;
5573
+
5574
+ export const $ExternalAccountLinkListResponseDto = {
5575
+ type: 'object',
5576
+ properties: {
5577
+ items: {
5578
+ type: 'array',
5579
+ items: {
5580
+ $ref: '#/components/schemas/ExternalAccountLinkResponseDto'
5581
+ }
5582
+ },
5583
+ total: {
5584
+ type: 'number'
5585
+ },
5586
+ provider: {
5587
+ type: 'string',
5588
+ description: 'Filter by provider (query param)'
5589
+ }
5590
+ },
5591
+ required: ['items', 'total']
5592
+ } as const;
5593
+
5120
5594
  export const $ParserTelemetryReportDto = {
5121
5595
  type: 'object',
5122
5596
  properties: {}
@@ -5666,7 +6140,7 @@ export const $NlpSuggestedAccountDto = {
5666
6140
  account: {
5667
6141
  type: 'string',
5668
6142
  description: 'Suggested account path',
5669
- example: 'Assets:Bank:Checking'
6143
+ example: 'Assets:Checking'
5670
6144
  },
5671
6145
  confidence: {
5672
6146
  type: 'number',
@@ -5707,7 +6181,7 @@ export const $NlpDefaultAccountsDto = {
5707
6181
  asset: {
5708
6182
  type: 'string',
5709
6183
  description: 'Default asset account',
5710
- example: 'Assets:Bank:Checking'
6184
+ example: 'Assets:Checking'
5711
6185
  },
5712
6186
  expense: {
5713
6187
  type: 'string',
@@ -5929,21 +6403,110 @@ export const $NlpResponseDto = {
5929
6403
  required: ['status', 'action']
5930
6404
  } as const;
5931
6405
 
5932
- export const $BalanceByCurrencyDto = {
6406
+ export const $CreatePlatformDto = {
5933
6407
  type: 'object',
5934
6408
  properties: {
5935
- currency: {
6409
+ name: {
5936
6410
  type: 'string',
5937
- description: 'ISO 4217 currency code',
5938
- example: 'CNY'
6411
+ description: 'Platform name',
6412
+ example: 'Binance'
5939
6413
  },
5940
- balance: {
6414
+ canonical: {
5941
6415
  type: 'string',
5942
- description: 'Balance amount',
5943
- example: '50000.00'
6416
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
6417
+ example: 'binance'
6418
+ },
6419
+ aliases: {
6420
+ description: 'Platform aliases (multi-language names for lookup)',
6421
+ example: ['Binance', 'Binance Exchange', 'BNB'],
6422
+ type: 'array',
6423
+ items: {
6424
+ type: 'string'
6425
+ }
6426
+ },
6427
+ url: {
6428
+ type: 'string',
6429
+ description: 'Platform URL',
6430
+ example: 'https://www.binance.com'
6431
+ },
6432
+ type: {
6433
+ type: 'string',
6434
+ description: 'Platform type',
6435
+ enum: [
6436
+ 'BANK',
6437
+ 'BROKERAGE',
6438
+ 'CRYPTO_EXCHANGE',
6439
+ 'PAYMENT',
6440
+ 'INVESTMENT',
6441
+ 'INSURANCE',
6442
+ 'OTHER'
6443
+ ],
6444
+ example: 'CRYPTO_EXCHANGE'
6445
+ },
6446
+ logoUrl: {
6447
+ type: 'string',
6448
+ description: 'Platform logo URL',
6449
+ example: 'https://example.com/logos/binance.png'
6450
+ },
6451
+ isActive: {
6452
+ type: 'boolean',
6453
+ description: 'Whether the platform is active',
6454
+ default: true
5944
6455
  }
5945
6456
  },
5946
- required: ['currency', 'balance']
6457
+ required: ['name', 'canonical', 'aliases', 'url', 'type']
6458
+ } as const;
6459
+
6460
+ export const $UpdatePlatformDto = {
6461
+ type: 'object',
6462
+ properties: {
6463
+ name: {
6464
+ type: 'string',
6465
+ description: 'Platform name',
6466
+ example: 'Binance'
6467
+ },
6468
+ canonical: {
6469
+ type: 'string',
6470
+ description: 'Platform canonical identifier (lowercase, kebab-case)',
6471
+ example: 'binance'
6472
+ },
6473
+ aliases: {
6474
+ description: 'Platform aliases (multi-language names for lookup)',
6475
+ example: ['Binance', 'Binance Exchange', 'BNB'],
6476
+ type: 'array',
6477
+ items: {
6478
+ type: 'string'
6479
+ }
6480
+ },
6481
+ url: {
6482
+ type: 'string',
6483
+ description: 'Platform URL',
6484
+ example: 'https://www.binance.com'
6485
+ },
6486
+ type: {
6487
+ type: 'string',
6488
+ description: 'Platform type',
6489
+ enum: [
6490
+ 'BANK',
6491
+ 'BROKERAGE',
6492
+ 'CRYPTO_EXCHANGE',
6493
+ 'PAYMENT',
6494
+ 'INVESTMENT',
6495
+ 'INSURANCE',
6496
+ 'OTHER'
6497
+ ],
6498
+ example: 'CRYPTO_EXCHANGE'
6499
+ },
6500
+ logoUrl: {
6501
+ type: 'string',
6502
+ description: 'Platform logo URL',
6503
+ example: 'https://example.com/logos/binance.png'
6504
+ },
6505
+ isActive: {
6506
+ type: 'boolean',
6507
+ description: 'Whether the platform is active'
6508
+ }
6509
+ }
5947
6510
  } as const;
5948
6511
 
5949
6512
  export const $NetWorthByCurrencyDto = {
@@ -6012,29 +6575,7 @@ export const $ConvertedNetWorthDto = {
6012
6575
  'assets',
6013
6576
  'liabilities',
6014
6577
  'exchangeRates'
6015
- ]
6016
- } as const;
6017
-
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']
6578
+ ]
6038
6579
  } as const;
6039
6580
 
6040
6581
  export const $NetWorthResponseDto = {
@@ -6122,7 +6663,7 @@ export const $AccountItemDto = {
6122
6663
  name: {
6123
6664
  type: 'string',
6124
6665
  description: 'Full account name',
6125
- example: 'Assets:Bank:CMB:Savings'
6666
+ example: 'Assets:CN:CMB:Savings'
6126
6667
  },
6127
6668
  displayName: {
6128
6669
  type: 'string',
@@ -6138,6 +6679,12 @@ export const $AccountItemDto = {
6138
6679
  type: 'string',
6139
6680
  description: 'Currency code',
6140
6681
  example: 'CNY'
6682
+ },
6683
+ convertedBalance: {
6684
+ type: 'string',
6685
+ description:
6686
+ 'FX-converted balance in base currency; omitted when not convertible',
6687
+ example: '50000.00'
6141
6688
  }
6142
6689
  },
6143
6690
  required: ['id', 'name', 'displayName', 'balance', 'currency']
@@ -6164,11 +6711,66 @@ export const $PlatformGroupDto = {
6164
6711
  },
6165
6712
  totalBalance: {
6166
6713
  type: 'string',
6167
- description: 'Total balance across all accounts in platform',
6714
+ description: 'FX-converted total balance in base currency',
6715
+ example: '100000.00'
6716
+ },
6717
+ balanceByCurrency: {
6718
+ description: 'Raw (unconverted) balances grouped by currency',
6719
+ type: 'array',
6720
+ items: {
6721
+ $ref: '#/components/schemas/BalanceByCurrencyDto'
6722
+ }
6723
+ },
6724
+ convertedBalance: {
6725
+ type: 'string',
6726
+ description:
6727
+ 'Converted balance in base currency (omitted when no currency is convertible)',
6168
6728
  example: '100000.00'
6729
+ },
6730
+ sharePct: {
6731
+ type: 'number',
6732
+ description:
6733
+ 'Share of the grand converted total (0-100); 0 when grand total is 0',
6734
+ example: 42.5
6735
+ }
6736
+ },
6737
+ required: [
6738
+ 'platformId',
6739
+ 'platformName',
6740
+ 'accounts',
6741
+ 'totalBalance',
6742
+ 'balanceByCurrency',
6743
+ 'sharePct'
6744
+ ]
6745
+ } as const;
6746
+
6747
+ export const $AccountExchangeRateWarningDto = {
6748
+ type: 'object',
6749
+ properties: {
6750
+ type: {
6751
+ type: 'string',
6752
+ description: 'Warning type',
6753
+ example: 'MISSING_EXCHANGE_RATE'
6754
+ },
6755
+ currency: {
6756
+ type: 'string',
6757
+ description: 'Currency without exchange rate',
6758
+ example: 'USD'
6759
+ },
6760
+ accounts: {
6761
+ description: 'Affected account paths',
6762
+ type: 'array',
6763
+ items: {
6764
+ type: 'string'
6765
+ }
6766
+ },
6767
+ totalAmount: {
6768
+ type: 'string',
6769
+ description: 'Total amount in this currency',
6770
+ example: '5000.00'
6169
6771
  }
6170
6772
  },
6171
- required: ['platformId', 'platformName', 'accounts', 'totalBalance']
6773
+ required: ['type', 'currency', 'accounts', 'totalAmount']
6172
6774
  } as const;
6173
6775
 
6174
6776
  export const $AccountsSummaryDto = {
@@ -6181,9 +6783,21 @@ export const $AccountsSummaryDto = {
6181
6783
  totalPlatforms: {
6182
6784
  type: 'number',
6183
6785
  description: 'Total number of platforms'
6786
+ },
6787
+ baseCurrency: {
6788
+ type: 'string',
6789
+ description: 'Base currency for conversion',
6790
+ example: 'CNY'
6791
+ },
6792
+ warnings: {
6793
+ description: 'Per-account exchange rate warnings',
6794
+ type: 'array',
6795
+ items: {
6796
+ $ref: '#/components/schemas/AccountExchangeRateWarningDto'
6797
+ }
6184
6798
  }
6185
6799
  },
6186
- required: ['totalAccounts', 'totalPlatforms']
6800
+ required: ['totalAccounts', 'totalPlatforms', 'baseCurrency']
6187
6801
  } as const;
6188
6802
 
6189
6803
  export const $AccountsResponseDto = {
@@ -6218,7 +6832,7 @@ export const $AccountItemWithAssetClassDto = {
6218
6832
  name: {
6219
6833
  type: 'string',
6220
6834
  description: 'Full account name',
6221
- example: 'Assets:Bank:CMB:Savings'
6835
+ example: 'Assets:CN:CMB:Savings'
6222
6836
  },
6223
6837
  displayName: {
6224
6838
  type: 'string',
@@ -6235,6 +6849,12 @@ export const $AccountItemWithAssetClassDto = {
6235
6849
  description: 'Currency code',
6236
6850
  example: 'CNY'
6237
6851
  },
6852
+ convertedBalance: {
6853
+ type: 'string',
6854
+ description:
6855
+ 'FX-converted balance in base currency; omitted when not convertible',
6856
+ example: '50000.00'
6857
+ },
6238
6858
  assetClass: {
6239
6859
  type: 'string',
6240
6860
  description: 'Asset class',
@@ -6314,35 +6934,6 @@ export const $AssetClassGroupDto = {
6314
6934
  required: ['assetClass', 'accounts', 'balanceByCurrency']
6315
6935
  } as const;
6316
6936
 
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
6937
  export const $AssetClassSummaryDto = {
6347
6938
  type: 'object',
6348
6939
  properties: {
@@ -6416,7 +7007,7 @@ export const $HoldingAssetClassAccountSliceDto = {
6416
7007
  accountPath: {
6417
7008
  type: 'string',
6418
7009
  description: 'Full account path',
6419
- example: 'Assets:US:Investments:Brokerage'
7010
+ example: 'Assets:US:Fidelity:Brokerage'
6420
7011
  },
6421
7012
  accountCurrency: {
6422
7013
  type: 'string',
@@ -6633,7 +7224,8 @@ export const $CategoryGroupDto = {
6633
7224
  },
6634
7225
  totalExpense: {
6635
7226
  type: 'string',
6636
- description: 'Converted total expense in base currency',
7227
+ description:
7228
+ 'Converted total for this category in base currency (expense amount when flow=expense, income amount when flow=income)',
6637
7229
  example: '1200.00'
6638
7230
  },
6639
7231
  sharePct: {
@@ -6664,7 +7256,7 @@ export const $ExpensesByCategorySummaryDto = {
6664
7256
  totalExpense: {
6665
7257
  type: 'string',
6666
7258
  description:
6667
- 'Total expense across all categories (converted; convertible categories only)',
7259
+ 'Total across all categories, converted (convertible categories only); expense totals when flow=expense, income totals when flow=income',
6668
7260
  example: '5000.00'
6669
7261
  },
6670
7262
  categoryCount: {
@@ -7005,163 +7597,6 @@ export const $HoldingPnlResponseDto = {
7005
7597
  required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
7006
7598
  } as const;
7007
7599
 
7008
- export const $CreateBeanPriceDto = {
7009
- type: 'object',
7010
- properties: {
7011
- currency: {
7012
- type: 'string',
7013
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
7014
- example: 'USD'
7015
- },
7016
- quoteCurrency: {
7017
- type: 'string',
7018
- description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
7019
- example: 'CNY'
7020
- },
7021
- amount: {
7022
- type: 'number',
7023
- description:
7024
- 'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
7025
- example: 175.5,
7026
- minimum: 0
7027
- },
7028
- date: {
7029
- type: 'string',
7030
- description: 'Price date (ISO 8601 format)',
7031
- example: '2024-11-05'
7032
- },
7033
- metadata: {
7034
- type: 'object',
7035
- description:
7036
- 'Metadata (validated by Zod schema, max field lengths enforced)',
7037
- example: {
7038
- source: 'MANUAL',
7039
- note: 'Bank valuation report',
7040
- confidence: 0.95
7041
- }
7042
- }
7043
- },
7044
- required: ['currency', 'quoteCurrency', 'amount', 'date']
7045
- } as const;
7046
-
7047
- export const $PriceResponseDto = {
7048
- type: 'object',
7049
- properties: {
7050
- id: {
7051
- type: 'string',
7052
- description: 'Unique identifier',
7053
- example: 'uuid-123-456'
7054
- },
7055
- userId: {
7056
- type: 'string',
7057
- description: 'User ID (owner of the price)',
7058
- example: 'user-123'
7059
- },
7060
- currency: {
7061
- type: 'string',
7062
- description: 'Currency being priced (e.g., USD, AAPL, BTC)',
7063
- example: 'BTC'
7064
- },
7065
- quoteCurrency: {
7066
- type: 'string',
7067
- description: 'Quote currency (pricing currency, e.g., USD, CNY)',
7068
- example: 'USD'
7069
- },
7070
- amount: {
7071
- type: 'number',
7072
- description:
7073
- 'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
7074
- example: 50000
7075
- },
7076
- date: {
7077
- type: 'string',
7078
- description:
7079
- 'Price date (ISO 8601 format). Represents the date this price was valid.',
7080
- example: '2024-01-01',
7081
- format: 'date'
7082
- },
7083
- meta: {
7084
- type: 'object',
7085
- description:
7086
- 'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
7087
- example: {
7088
- source: 'MANUAL',
7089
- note: 'User-defined price',
7090
- confidence: 1
7091
- }
7092
- },
7093
- createdAt: {
7094
- format: 'date-time',
7095
- type: 'string',
7096
- description: 'Creation timestamp',
7097
- example: '2024-11-03T10:00:00Z'
7098
- },
7099
- updatedAt: {
7100
- format: 'date-time',
7101
- type: 'string',
7102
- description: 'Last update timestamp',
7103
- example: '2024-11-03T10:00:00Z'
7104
- }
7105
- },
7106
- required: [
7107
- 'id',
7108
- 'userId',
7109
- 'currency',
7110
- 'quoteCurrency',
7111
- 'amount',
7112
- 'date',
7113
- 'meta',
7114
- 'createdAt',
7115
- 'updatedAt'
7116
- ]
7117
- } as const;
7118
-
7119
- export const $PriceListResponseDto = {
7120
- type: 'object',
7121
- properties: {
7122
- items: {
7123
- description: 'List of prices',
7124
- type: 'array',
7125
- items: {
7126
- $ref: '#/components/schemas/PriceResponseDto'
7127
- }
7128
- },
7129
- total: {
7130
- type: 'number',
7131
- description: 'Total number of prices',
7132
- example: 42
7133
- }
7134
- },
7135
- required: ['items', 'total']
7136
- } as const;
7137
-
7138
- export const $UpdateBeanPriceDto = {
7139
- type: 'object',
7140
- properties: {
7141
- currency: {
7142
- type: 'string',
7143
- description: 'Currency being priced'
7144
- },
7145
- quoteCurrency: {
7146
- type: 'string',
7147
- description: 'Quote currency (pricing currency)'
7148
- },
7149
- amount: {
7150
- type: 'number',
7151
- description: 'Price amount (MUST be >= 0 per Beancount spec)',
7152
- minimum: 0
7153
- },
7154
- date: {
7155
- type: 'string',
7156
- description: 'Price date (ISO 8601 format)'
7157
- },
7158
- metadata: {
7159
- type: 'object',
7160
- description: 'Metadata'
7161
- }
7162
- }
7163
- } as const;
7164
-
7165
7600
  export const $CurrencyBalanceDto = {
7166
7601
  type: 'object',
7167
7602
  properties: {