Support credit report liability streams in list_recurring

[krisrowe]

Problem

list_recurring only returns merchant-based recurring streams. Monarch also has credit report liability streams that include credit cards, mortgages, HELOCs, and installment loans sourced from credit bureau data (via Spinwheel). These don't appear in our tool output but show in the Monarch UI.

Liability stream data available via two queries

Common_GetRecurringStreams (catalog)

Returns one entry per stream including liabilities. Liability streams have:

• recurringType — "credit_card" for cards, "expense" for mortgages/HELOCs
• creditReportLiabilityAccount.status — OPEN, CLOSED
• creditReportLiabilityAccount.accountType — MORTGAGE, REVOLVING, CREDIT_LINE, INSTALLMENT
• creditReportLiabilityAccount.reportedDate — last credit bureau report date
• creditReportLiabilityAccount.account.id — linked Monarch account ID
• creditReportLiabilityAccount.account.currentBalance / displayBalance
• merchant is null — these are not merchant-based
• amount is null — no fixed amount on the stream itself

Common_GetAggregatedRecurringItems (monthly view — richer data)

This is the query the Monarch UI uses for the recurring calendar. When called with a single month date range (e.g., startDate: "2026-04-01", endDate: "2026-04-30"), liability streams include:

liabilityStatement {
    id
    minimumPaymentAmount      # e.g., 64.0 for a credit card, 1431.0 for a mortgage
    paymentsInformation {
        status                # "paid", "unpaid", "partially_paid"
        remainingBalance      # balance remaining after payments
        transactions {        # actual payment details
            id
            amount            # payment amount
            date              # payment date
            category { id name }
        }
    }
}

Also includes per-item:

• isLate — whether the payment is overdue
• isCompleted — whether the obligation is satisfied for the period
• amount — the statement balance (populated for liabilities, unlike catalog query)

Confirmed behavior from live API analysis

Credit cards: Show with recurringType: "credit_card", statement balance as amount, minimum payment, and paid/unpaid/partially_paid status. Due dates derived from lastStatement.dueDate. Zero-balance cards auto-complete with pmtStatus: "paid", minimumPaymentAmount: 0.0.

Mortgages and HELOCs: Show with recurringType: "expense", minimum payment equal to the mortgage payment amount, pmtStatus: "unpaid"/"paid".

Partial payment tracking: For accounts where minimum was paid but balance remains, status shows "partially_paid" with actual payment transactions listed (amounts and dates).

Example from live data — credit card with partial payments:

status: "partially_paid"
remainingBalance: -10754.0
payments:
  $110.0 on 2026-03-15
  $110.0 on 2026-03-14

Note: The Common_GetRecurringStreams catalog query originally appeared to lack payment fields like minimumPayment and dueDate (they returned 400 when queried directly on creditReportLiabilityAccount). These fields are actually available through the liabilityStatement join in the aggregated query, not on the stream itself.

Stream types from recurringType

• expense — merchant-based charges AND mortgage/HELOC liabilities
• income — incoming payments (payroll, rent, child support)
• credit_card — credit card liabilities from credit report

Acceptance criteria

1. Liability streams appear in list_recurring output alongside merchant-based streams
2. Each liability stream includes: account name, balance, minimum payment, due date, paid/unpaid status
3. For the current month, payment details are available (amounts, dates, remaining balance)
4. Zero-balance cards show as completed/paid
5. isLate flag is surfaced for overdue payments
6. Liability streams are distinguishable from merchant streams (via recurring_type or similar field)

Implementation

The aggregated query (Common_GetAggregatedRecurringItems) is the recommended primary source per #5. If #5 is implemented as described (switching list_recurring to use the aggregated query), liability streams will be included automatically. This issue tracks the acceptance criteria and ensures liability-specific fields are properly surfaced and tested.

Related

• Recurring stream retrieval misses liability streams, newly created merchants, and pending items — switch to aggregated query #5 — Query migration for list_recurring (implementation vehicle for this issue)
• Merchant logo management and split-merchant workflow documentation #3 — Parent tracking issue
• bills-agent — needs liability data for credit card payment verification and promo financing tracking