@firela/api-types 0.0.0-canary.074c27d4 → 0.0.0-canary.09a8ff4c

package/src/generated/schemas.gen.ts

@@ -466,6 +466,66 @@ export const $RegionsMetadataResponseDto = {
   required: ['regions']
 } as const;
 
+export const $CostSpecDto = {
+  type: 'object',
+  properties: {
+    mode: {
+      type: 'string',
+      enum: ['per-unit', 'total', 'date', 'label', 'auto'],
+      description: 'Cost specification mode (mirrors engine CostSpec)'
+    },
+    numberPerUnit: {
+      type: 'string',
+      description: 'Per-unit cost (required when mode is "per-unit")',
+      example: '240'
+    },
+    totalNumber: {
+      type: 'string',
+      description: 'Total cost for all units (required when mode is "total")',
+      example: '12000'
+    },
+    currency: {
+      type: 'string',
+      description: 'Cost currency (required in all modes)',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description:
+        'Lot acquisition date, ISO 8601 (required when mode is "date")',
+      example: '2024-01-15'
+    },
+    label: {
+      type: 'string',
+      description:
+        'Lot label (required when mode is "label"; optional tag in buy modes)'
+    },
+    merge: {
+      type: 'boolean',
+      description: 'Merge lots for AVERAGE booking (mode: auto)'
+    }
+  },
+  required: ['mode', 'currency']
+} as const;
+
+export const $AmountDto = {
+  type: 'object',
+  properties: {
+    number: {
+      type: 'string',
+      description:
+        'Amount as decimal string (max 15 integer + 15 decimal digits)',
+      example: '170.50'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency/commodity code',
+      example: 'USD'
+    }
+  },
+  required: ['number', 'currency']
+} as const;
+
 export const $CreatePostingDto = {
   type: 'object',
   properties: {
@@ -495,6 +555,33 @@ export const $CreatePostingDto = {
       example: {
         'tax-lot': 'Q1-2024'
       }
+    },
+    cost: {
+      description:
+        'Cost basis (Beancount `{...}`). Maps to engine costSpec. Required for commodity holdings so they carry a monetary weight that can balance.',
+      example: {
+        mode: 'per-unit',
+        numberPerUnit: '240',
+        currency: 'USD'
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostSpecDto'
+        }
+      ]
+    },
+    price: {
+      description:
+        'Price annotation (Beancount `@...`). Maps to engine price. Used for valuation; cost takes priority for balance weight.',
+      example: {
+        number: '170',
+        currency: 'USD'
+      },
+      allOf: [
+        {
+          $ref: '#/components/schemas/AmountDto'
+        }
+      ]
     }
   },
   required: ['account']
@@ -573,6 +660,32 @@ export const $CreateTransactionDto = {
   required: ['date', 'narration', 'postings']
 } as const;
 
+export const $CostDetailDto = {
+  type: 'object',
+  properties: {
+    number: {
+      type: 'string',
+      description: 'Per-unit cost basis (mirrors engine Cost.number)',
+      example: '240'
+    },
+    currency: {
+      type: 'string',
+      description: 'Cost currency',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description: 'Lot acquisition date (ISO yyyy-mm-dd)',
+      example: '2024-01-15'
+    },
+    label: {
+      type: 'string',
+      description: 'Lot label',
+      example: 'lot-2024-01'
+    }
+  }
+} as const;
+
 export const $PostingResponseDto = {
   type: 'object',
   properties: {
@@ -591,6 +704,15 @@ export const $PostingResponseDto = {
       type: 'string',
       description: 'Currency',
       example: 'USD'
+    },
+    cost: {
+      description:
+        'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostDetailDto'
+        }
+      ]
     }
   },
   required: ['account']
@@ -964,6 +1086,15 @@ export const $PostingDetailDto = {
       description: 'Cost date',
       example: '2024-01-15'
     },
+    cost: {
+      description:
+        'Booking-resolved cost (mirrors engine Cost). Undefined when the posting has no cost basis.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CostDetailDto'
+        }
+      ]
+    },
     priceAmount: {
       type: 'string',
       description: 'Price amount',
@@ -1724,7 +1855,8 @@ export const $ResolveResultDto = {
     },
     resolutionId: {
       type: 'string',
-      description: 'Resolution ID for undo'
+      description:
+        'Resolution ID for undo. Absent when the resolver rejected the decision (review stayed PENDING).'
     },
     canUndo: {
       type: 'boolean',
@@ -1742,7 +1874,7 @@ export const $ResolveResultDto = {
       example: 'rule_01HXK5V8N2M3P4Q5R6S7T8U9V0'
     }
   },
-  required: ['success', 'resolutionId', 'canUndo', 'undoDeadline']
+  required: ['success']
 } as const;
 
 export const $UndoResultDto = {
@@ -4180,6 +4312,144 @@ export const $UpdatePropertyDto = {
   required: ['value']
 } as const;
 
+export const $CreateBeanEventDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)',
+      example: '2024-03-15'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (e.g., "employer", "location", "marital-status") — user-defined, no enum constraint at engine layer',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Product-side metadata (lives in BeanEvent.meta JSON, never in engine Event fields)',
+      example: {
+        note: 'Promotion'
+      }
+    }
+  },
+  required: ['date', 'type', 'description']
+} as const;
+
+export const $EventResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the life event)',
+      example: 'user-123'
+    },
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601 format)',
+      example: '2024-03-15',
+      format: 'date'
+    },
+    type: {
+      type: 'string',
+      description:
+        'Life event type (user-defined, e.g., "employer", "location")',
+      example: 'employer'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. May be an empty string (a valid value distinct from absence).',
+      example: 'Acme Corp'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)',
+      example: {
+        note: 'Promotion'
+      }
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-03-15T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description:
+        'Last update timestamp. Also emitted as the ETag response header for If-Match optimistic concurrency.',
+      example: '2024-03-15T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'date',
+    'type',
+    'description',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $EventListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of life events',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/EventResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of life events matching the query',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateBeanEventDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Life event date (ISO 8601)'
+    },
+    type: {
+      type: 'string',
+      description: 'Life event type (user-defined)'
+    },
+    description: {
+      type: 'string',
+      description:
+        'Life event description. Empty string is a VALID value (distinct from absence).'
+    },
+    meta: {
+      type: 'object',
+      description: 'Product-side metadata (free-form JSON)'
+    }
+  }
+} as const;
+
 export const $FileImportDto = {
   type: 'object',
   properties: {
@@ -4852,6 +5122,11 @@ export const $ParserTelemetryReportDto = {
   properties: {}
 } as const;
 
+export const $UncoveredFormatMissDto = {
+  type: 'object',
+  properties: {}
+} as const;
+
 export const $ProcessNlpDto = {
   type: 'object',
   properties: {
@@ -5979,6 +6254,12 @@ export const $AccountItemWithAssetClassDto = {
       type: 'string',
       description: 'Risk level',
       example: 'LOW'
+    },
+    source: {
+      type: 'string',
+      description:
+        'ADR-0105 classification provenance (holding level always; account level only on FALLBACK)',
+      enum: ['USER_META', 'FIAT_CURRENCY', 'OPENBB_MAPPING', 'FALLBACK']
     }
   },
   required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
@@ -6084,6 +6365,11 @@ export const $AssetClassSummaryDto = {
       items: {
         $ref: '#/components/schemas/AccountExchangeRateWarningDto'
       }
+    },
+    fallback: {
+      type: 'object',
+      description:
+        'ADR-0105 §4 fallback provenance stats (holding level only). valueRatio is the grey-area share of total converted value; count is the number of source=FALLBACK holdings.'
     }
   },
   required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
@@ -6106,47 +6392,143 @@ export const $AssetClassAccountsResponseDto = {
           $ref: '#/components/schemas/AssetClassSummaryDto'
         }
       ]
+    },
+    uncategorized: {
+      description:
+        'ADR-0105 §6 holding-level grey-area bucket (source=FALLBACK holdings peeled out of groups). Present only for groupBy=holdingAssetClass when FALLBACK holdings exist.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassGroupDto'
+        }
+      ]
     }
   },
   required: ['groups', 'summary']
 } as const;
 
-export const $CashFlowByCurrencyDto = {
+export const $HoldingAssetClassAccountSliceDto = {
   type: 'object',
   properties: {
-    income: {
-      description: 'Income by currency',
-      type: 'array',
-      items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
-      }
+    accountId: {
+      type: 'string',
+      description: 'Account ID'
     },
-    expense: {
-      description: 'Expense by currency',
+    accountPath: {
+      type: 'string',
+      description: 'Full account path',
+      example: 'Assets:US:Investments:Brokerage'
+    },
+    accountCurrency: {
+      type: 'string',
+      description:
+        'Currency of the holding with the largest converted base value; undefined when no holding is convertible',
+      example: 'USD'
+    },
+    marketValueBase: {
+      type: 'string',
+      description:
+        "Account's market value in base currency (Σ converted holdings; grey bucket included)",
+      example: '50000.00'
+    },
+    shareOfTotalPct: {
+      type: 'number',
+      description:
+        'Share of the global total (0-100). 0 when globalTotal is zero (no NaN/Infinity).',
+      example: 42.5
+    },
+    groups: {
+      description: 'Per-account asset-class breakdown',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
+        $ref: '#/components/schemas/AssetClassGroupDto'
       }
     },
-    netSavings: {
-      description: 'Net savings by currency',
+    uncategorized: {
+      description:
+        'Per-account grey bucket (source=FALLBACK holdings, incl. broker cash)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassGroupDto'
+        }
+      ]
+    },
+    holdings: {
+      description:
+        'Every holding row for this account (account ID in each row’s `id` field)',
       type: 'array',
       items: {
-        $ref: '#/components/schemas/BalanceByCurrencyDto'
+        $ref: '#/components/schemas/AccountItemWithAssetClassDto'
       }
     }
   },
-  required: ['income', 'expense', 'netSavings']
+  required: [
+    'accountId',
+    'accountPath',
+    'marketValueBase',
+    'shareOfTotalPct',
+    'groups',
+    'holdings'
+  ]
 } as const;
 
-export const $ConvertedCashFlowDto = {
+export const $HoldingAssetClassCrossAccountResponseDto = {
   type: 'object',
   properties: {
-    baseCurrency: {
-      type: 'string',
-      description: 'Base currency for conversion',
-      example: 'CNY'
-    },
+    global: {
+      description: 'Merged cross-account holding aggregation',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassAccountsResponseDto'
+        }
+      ]
+    },
+    byAccount: {
+      description: 'Per-account slices',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/HoldingAssetClassAccountSliceDto'
+      }
+    }
+  },
+  required: ['global', 'byAccount']
+} as const;
+
+export const $CashFlowByCurrencyDto = {
+  type: 'object',
+  properties: {
+    income: {
+      description: 'Income by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    expense: {
+      description: 'Expense by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    netSavings: {
+      description: 'Net savings by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    }
+  },
+  required: ['income', 'expense', 'netSavings']
+} as const;
+
+export const $ConvertedCashFlowDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
     income: {
       type: 'string',
       description: 'Converted income',
@@ -6240,6 +6622,452 @@ export const $CashFlowResponseDto = {
   ]
 } as const;
 
+export const $MonetaryDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'string',
+      description: 'Amount (Decimal string)',
+      example: '3000'
+    },
+    currency: {
+      type: 'string',
+      description: 'ISO 4217 currency',
+      example: 'USD'
+    },
+    baseCcyEquivalent: {
+      type: 'object',
+      description: 'Converted to user base currency (Decimal string)',
+      example: '21600',
+      nullable: true
+    }
+  },
+  required: ['amount', 'currency']
+} as const;
+
+export const $CurrentPriceDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'string',
+      description: 'Price amount (Decimal string)',
+      example: '250'
+    },
+    currency: {
+      type: 'string',
+      description: 'Price currency (ISO 4217)',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description: 'Price date (ISO 8601)',
+      example: '2024-06-01'
+    },
+    source: {
+      type: 'string',
+      description: 'Price source',
+      example: 'USER_OVERRIDE',
+      enum: ['USER_OVERRIDE', 'OPENBB_EQUITY', 'OPENBB_CURRENCY']
+    }
+  },
+  required: ['amount', 'currency', 'date', 'source']
+} as const;
+
+export const $FxRateDto = {
+  type: 'object',
+  properties: {
+    from: {
+      type: 'string',
+      example: 'USD'
+    },
+    to: {
+      type: 'string',
+      example: 'CNY'
+    },
+    rate: {
+      type: 'string',
+      description: 'FX rate (Decimal string)',
+      example: '7.2'
+    },
+    date: {
+      type: 'string',
+      description: 'Rate date (ISO 8601)',
+      example: '2024-01-15'
+    }
+  },
+  required: ['from', 'to', 'rate', 'date']
+} as const;
+
+export const $HoldingPnlRowDto = {
+  type: 'object',
+  properties: {
+    accountId: {
+      type: 'string',
+      description: 'Account UUID',
+      example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+    },
+    accountPath: {
+      type: 'string',
+      description: 'Full account path',
+      example: 'Assets:US:Broker:AAPL'
+    },
+    accountCcy: {
+      type: 'object',
+      description: 'Account settlement currency (ISO 4217), from cost currency',
+      nullable: true,
+      example: 'USD'
+    },
+    brokerType: {
+      type: 'object',
+      description: 'Broker type derived from Platform.type',
+      nullable: true,
+      example: 'broker'
+    },
+    symbol: {
+      type: 'string',
+      description: 'Commodity symbol',
+      example: 'AAPL'
+    },
+    chartToken: {
+      type: 'string',
+      description: 'Chart segment token (libs/common resolver)',
+      example: 'equity',
+      enum: ['equity', 'fund', 'bond', 'cash', 'other']
+    },
+    assetClass: {
+      type: 'string',
+      example: 'EQUITY'
+    },
+    assetSubClass: {
+      type: 'object',
+      nullable: true,
+      example: 'STOCK'
+    },
+    units: {
+      type: 'string',
+      description: 'Net held units (Decimal string)',
+      example: '12'
+    },
+    averageCostPerUnit: {
+      description:
+        'Average cost per unit; null when cost currency conflicts or no cost',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    costBasis: {
+      description: 'Cost basis of held units',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    marketValue: {
+      description: 'Market value at asOf price',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    },
+    currentPrice: {
+      description: 'Price used for market value',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/CurrentPriceDto'
+        }
+      ]
+    },
+    unrealizedPnlBase: {
+      type: 'object',
+      description:
+        'Unrealized P&L in base currency (Decimal string); null when any FX/price missing',
+      nullable: true,
+      example: '6000'
+    },
+    unrealizedPnlPct: {
+      type: 'object',
+      description: 'Unrealized P&L % (Decimal string)',
+      nullable: true,
+      example: '25'
+    },
+    costFxRate: {
+      description: 'Historical FX rate applied to cost basis',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/FxRateDto'
+        }
+      ]
+    },
+    marketFxRate: {
+      description: 'FX rate applied to market value',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/FxRateDto'
+        }
+      ]
+    },
+    pctOfInvestedAssets: {
+      type: 'object',
+      description:
+        'Share of invested assets % (Decimal string); only for invested chartTokens',
+      nullable: true,
+      example: '40'
+    },
+    realizedPnl: {
+      description:
+        'Cumulative realized P&L on sold lots (asOf-date cutoff); null when the method has no applicable sells, a sell lacks a price, or any required FX rate is missing (never-mix). When a sell spans multiple currencies (cross-currency sale), amount and currency reflect the base currency; baseCcyEquivalent is always the authoritative dual-FX figure',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/MonetaryDto'
+        }
+      ]
+    }
+  },
+  required: [
+    'accountId',
+    'accountPath',
+    'symbol',
+    'chartToken',
+    'assetClass',
+    'units'
+  ]
+} as const;
+
+export const $HoldingPnlWarningDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_COST_FX_RATE',
+      enum: [
+        'MISSING_COST_FX_RATE',
+        'MISSING_MARKET_FX_RATE',
+        'MISSING_SALE_PRICE',
+        'MISSING_REALIZED_FX_RATE',
+        'OVERSOLD_LOTS',
+        'NO_PRICE',
+        'MIXED_COST_CURRENCY'
+      ]
+    },
+    symbol: {
+      type: 'object',
+      nullable: true
+    },
+    accountId: {
+      type: 'object',
+      nullable: true
+    },
+    currency: {
+      type: 'object',
+      nullable: true
+    }
+  },
+  required: ['type']
+} as const;
+
+export const $HoldingPnlResponseDto = {
+  type: 'object',
+  properties: {
+    asOfDate: {
+      type: 'string',
+      example: '2026-07-08'
+    },
+    baseCurrency: {
+      type: 'string',
+      example: 'CNY'
+    },
+    method: {
+      type: 'string',
+      description:
+        'Realized-P&L lot-matching method (FIFO or average). Unrealized cost basis remains average regardless of this value (#473).',
+      enum: ['average', 'FIFO'],
+      example: 'average'
+    },
+    rows: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/HoldingPnlRowDto'
+      }
+    },
+    warnings: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/HoldingPnlWarningDto'
+      }
+    }
+  },
+  required: ['asOfDate', 'baseCurrency', 'method', 'rows', 'warnings']
+} as const;
+
+export const $CreateBeanPriceDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'USD'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency, e.g., CNY, EUR)',
+      example: 'CNY'
+    },
+    amount: {
+      type: 'number',
+      description:
+        'Price amount (MUST be >= 0 per Beancount spec, supports up to 15 decimal places). Zero allowed for conversion entries, negative strictly prohibited.',
+      example: 175.5,
+      minimum: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Price date (ISO 8601 format)',
+      example: '2024-11-05'
+    },
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (validated by Zod schema, max field lengths enforced)',
+      example: {
+        source: 'MANUAL',
+        note: 'Bank valuation report',
+        confidence: 0.95
+      }
+    }
+  },
+  required: ['currency', 'quoteCurrency', 'amount', 'date']
+} as const;
+
+export const $PriceResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of the price)',
+      example: 'user-123'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency being priced (e.g., USD, AAPL, BTC)',
+      example: 'BTC'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency, e.g., USD, CNY)',
+      example: 'USD'
+    },
+    amount: {
+      type: 'number',
+      description:
+        'Price amount (corresponds to Beancount Amount.number). Supports up to 15 decimal places.',
+      example: 50000
+    },
+    date: {
+      type: 'string',
+      description:
+        'Price date (ISO 8601 format). Represents the date this price was valid.',
+      example: '2024-01-01',
+      format: 'date'
+    },
+    meta: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Contains source, confidence, note, etc.',
+      example: {
+        source: 'MANUAL',
+        note: 'User-defined price',
+        confidence: 1
+      }
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-11-03T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2024-11-03T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'currency',
+    'quoteCurrency',
+    'amount',
+    'date',
+    'meta',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $PriceListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of prices',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PriceResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of prices',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateBeanPriceDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'Currency being priced'
+    },
+    quoteCurrency: {
+      type: 'string',
+      description: 'Quote currency (pricing currency)'
+    },
+    amount: {
+      type: 'number',
+      description: 'Price amount (MUST be >= 0 per Beancount spec)',
+      minimum: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Price date (ISO 8601 format)'
+    },
+    metadata: {
+      type: 'object',
+      description: 'Metadata'
+    }
+  }
+} as const;
+
 export const $CurrencyBalanceDto = {
   type: 'object',
   properties: {
@@ -6384,6 +7212,111 @@ export const $PortfolioTrendsResponseDto = {
   required: ['series', 'summary', 'period', 'granularity', 'currency']
 } as const;
 
+export const $CashFlowPointDto = {
+  type: 'object',
+  properties: {
+    month: {
+      type: 'string',
+      description: 'Month key (YYYY-MM)',
+      example: '2024-03'
+    },
+    income: {
+      type: 'string',
+      description: 'Income in base currency (absolute, converted)',
+      example: '10000.00'
+    },
+    expense: {
+      type: 'string',
+      description: 'Expense in base currency (absolute, converted)',
+      example: '5000.00'
+    },
+    netSavings: {
+      type: 'string',
+      description: 'netSavings = income − expense (savings positive)',
+      example: '5000.00'
+    }
+  },
+  required: ['month', 'income', 'expense', 'netSavings']
+} as const;
+
+export const $CashFlowTrendSummaryDto = {
+  type: 'object',
+  properties: {
+    totalIncome: {
+      type: 'string',
+      description: 'Total income across the period',
+      example: '60000.00'
+    },
+    totalExpense: {
+      type: 'string',
+      description: 'Total expense across the period',
+      example: '30000.00'
+    },
+    totalNetSavings: {
+      type: 'string',
+      description: 'income − expense across the period',
+      example: '30000.00'
+    },
+    averageMonthlyNetSavings: {
+      type: 'string',
+      description:
+        'totalNetSavings divided by the window length (N months, incl. zero-filled)',
+      example: '5000.00'
+    }
+  },
+  required: [
+    'totalIncome',
+    'totalExpense',
+    'totalNetSavings',
+    'averageMonthlyNetSavings'
+  ]
+} as const;
+
+export const $CashFlowTrendsResponseDto = {
+  type: 'object',
+  properties: {
+    series: {
+      description:
+        'Monthly cash-flow series (fixed N-month window, zero-filled)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CashFlowPointDto'
+      }
+    },
+    summary: {
+      description: 'Period totals',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CashFlowTrendSummaryDto'
+        }
+      ]
+    },
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '6m'
+    },
+    granularity: {
+      type: 'string',
+      description: 'Data granularity (v1 returns month buckets)',
+      example: 'month'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Exchange rate warnings (e.g. missing rate for a currency)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['series', 'summary', 'period', 'granularity', 'currency']
+} as const;
+
 export const $GenerateSnapshotBody = {
   type: 'object',
   properties: {}