@spec balance_postings(ExLedger.Parser.Core.transaction()) ::
  ExLedger.Parser.Core.transaction()

@spec balance_postings([ExLedger.Parser.Core.posting()]) :: [
  ExLedger.Parser.Core.posting()
]

Balances postings by calculating the missing amount.

Only balances among regular postings - virtual unbalanced postings are excluded.

@spec parse_amount(String.t()) ::
  {:ok, ExLedger.Parser.Core.amount()} | {:error, :invalid_amount}

Parses an amount string like $4.50 or -$20.00.

@spec parse_date(String.t()) :: {:ok, Date.t()} | {:error, :invalid_date_format}

Parses a date string in YYYY/MM/DD format.

@spec parse_note(String.t()) ::
  {:ok,
   {:tag, String.t()}
   | {:metadata, String.t(), String.t()}
   | {:comment, String.t()}}
  | {:error, :invalid_note}

Parses a note/comment line and determines its type.

@spec parse_posting(String.t()) :: {:ok, map()} | {:error, :invalid_posting}

Parses a posting line.

@spec parse_transaction(String.t()) ::
  {:ok, ExLedger.Parser.Core.transaction()}
  | {:error, ExLedger.Parser.Core.parse_error()}

Parses a single transaction from a string.

Returns {:ok, transaction} or {:error, reason}.

@spec validate_transaction(ExLedger.Parser.Core.transaction()) ::
  :ok
  | {:error,
     :multiple_nil_amounts | :multi_currency_missing_amount | :unbalanced}

Validates that a transaction is balanced (all postings sum to zero).

Virtual postings are handled specially:

• Virtual unbalanced (parentheses): excluded from balance validation
• Virtual balanced (brackets): must balance among themselves
• Regular postings: must balance among themselves