feat(api): expose balance history (#1641)

* feat(api): expose balance history

* fix(api): address balance history review

* fix(api): address balance history review

* fix(api): tighten balance history docs

* fix(exports): preserve balance chronology

* fix(api): guard nullable balance account type

* test(api): align balances api key helper

* fix(api): use shared pagination clamp

* test(export): set explicit balance flows factor

docs/api/openapi.yaml

@@ -460,6 +460,146 @@ components:
         updated_at:
           type: string
           format: date-time
+    Balance:
+      type: object
+      required:
+      - id
+      - date
+      - currency
+      - flows_factor
+      - balance
+      - balance_cents
+      - start_balance
+      - start_balance_cents
+      - end_balance
+      - end_balance_cents
+      - account
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        date:
+          type: string
+          format: date
+        currency:
+          type: string
+        flows_factor:
+          type: number
+          format: float
+        balance:
+          type: string
+        balance_cents:
+          type: integer
+          description: Balance in currency minor units
+        cash_balance:
+          type: string
+          nullable: true
+        cash_balance_cents:
+          type: integer
+          nullable: true
+          description: Cash balance in currency minor units
+        start_cash_balance:
+          type: string
+        start_cash_balance_cents:
+          type: integer
+          description: Starting cash balance in currency minor units
+        start_non_cash_balance:
+          type: string
+        start_non_cash_balance_cents:
+          type: integer
+          description: Starting non-cash balance in currency minor units
+        start_balance:
+          type: string
+        start_balance_cents:
+          type: integer
+          description: Starting total balance in currency minor units
+        cash_inflows:
+          type: string
+        cash_inflows_cents:
+          type: integer
+          description: Cash inflows in currency minor units
+        cash_outflows:
+          type: string
+        cash_outflows_cents:
+          type: integer
+          description: Cash outflows in currency minor units
+        non_cash_inflows:
+          type: string
+        non_cash_inflows_cents:
+          type: integer
+          description: Non-cash inflows in currency minor units
+        non_cash_outflows:
+          type: string
+        non_cash_outflows_cents:
+          type: integer
+          description: Non-cash outflows in currency minor units
+        net_market_flows:
+          type: string
+        net_market_flows_cents:
+          type: integer
+          description: Net market flows in currency minor units
+        cash_adjustments:
+          type: string
+        cash_adjustments_cents:
+          type: integer
+          description: Cash adjustments in currency minor units
+        non_cash_adjustments:
+          type: string
+        non_cash_adjustments_cents:
+          type: integer
+          description: Non-cash adjustments in currency minor units
+        end_cash_balance:
+          type: string
+        end_cash_balance_cents:
+          type: integer
+          description: Ending cash balance in currency minor units
+        end_non_cash_balance:
+          type: string
+        end_non_cash_balance_cents:
+          type: integer
+          description: Ending non-cash balance in currency minor units
+        end_balance:
+          type: string
+        end_balance_cents:
+          type: integer
+          description: Ending total balance in currency minor units
+        account:
+          "$ref": "#/components/schemas/BalanceAccount"
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    BalanceAccount:
+      type: object
+      required:
+      - id
+      - name
+      - account_type
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        account_type:
+          type: string
+          nullable: true
+    BalanceCollection:
+      type: object
+      required:
+      - balances
+      - pagination
+      properties:
+        balances:
+          type: array
+          items:
+            "$ref": "#/components/schemas/Balance"
+        pagination:
+          "$ref": "#/components/schemas/Pagination"
     Category:
       type: object
       required:
@@ -2522,6 +2662,118 @@ paths:
             application/json:
               schema:
                 "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/balances":
+    get:
+      summary: List balance history records
+      tags:
+      - Balances
+      security:
+      - apiKeyAuth: []
+      parameters:
+      - name: page
+        in: query
+        required: false
+        description: 'Page number (default: 1)'
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        required: false
+        description: 'Items per page (default: 25, max: 100)'
+        schema:
+          type: integer
+      - name: account_id
+        in: query
+        required: false
+        description: Filter by account ID
+        schema:
+          type: string
+          format: uuid
+      - name: currency
+        in: query
+        required: false
+        description: Filter by currency code
+        schema:
+          type: string
+      - name: start_date
+        in: query
+        required: false
+        description: Filter balances from this date
+        schema:
+          type: string
+          format: date
+      - name: end_date
+        in: query
+        required: false
+        description: Filter balances until this date
+        schema:
+          type: string
+          format: date
+      responses:
+        '200':
+          description: balances listed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/BalanceCollection"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: insufficient scope
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '422':
+          description: invalid filter
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/balances/{id}":
+    parameters:
+    - name: id
+      in: path
+      required: true
+      description: Balance ID
+      schema:
+        type: string
+        format: uuid
+    get:
+      summary: Retrieve a balance history record
+      tags:
+      - Balances
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: balance retrieved
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Balance"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: insufficient scope
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '404':
+          description: balance not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v1/categories":
     get:
       summary: List categories