Add credit card management features

[SolusCado]

PR Description

Add Credit Card Management Features

This PR enhances the YNAB Home Assistant integration with comprehensive credit card management capabilities, including sensors for monitoring credit utilization and available credit, plus editable number entities for managing credit limits, APR rates, and payment due dates.

New Features

Sensors:

• Total Credit Limit - Sum of all credit card limits
• Total Credit Utilization - Overall utilization percentage across all cards
• Total Available Credit - Combined available credit across all cards
• Individual card sensors:
  • {Card Name} Utilization - Per-card utilization %
  • {Card Name} Available Credit - Per-card available credit

Number Entities (Configurable):

• {Card Name} Credit Limit - Editable credit limit
• {Card Name} APR - Annual percentage rate (0-40%)
• {Card Name} Due Day - Monthly payment due date (1-28)

Key Changes

• Added number.py with credit card number entities
• Enhanced coordinator.py with persistent storage for user values
• Updated sensor.py with credit card monitoring sensors
• Modified manifest.json to include number platform
• Added data persistence for credit limits, APR, and due days

Configuration

After installation, credit card accounts are automatically detected. Configure limits/APR/due days through the number entities in HA. Sensors update based on YNAB data.

Data Storage

User-configured values (limits, APR, due days) are stored in HA's config storage and persist across restarts.

Compatibility

• Requires YNAB accounts marked as "Credit Card" type
• Backward compatible with existing installations
• No breaking changes to existing functionality

Testing

Tested with multiple credit card accounts, various currencies, and HA restart scenarios. All sensors and number entities function correctly.

[DeLuca21]

Thanks for the PR, the CC features look good.

But this branch looks to be based on an older version of main and right now it removes some newer changes already merged, including the Ready to Assign fix and some more recent updates.

Can you update your branch with the latest main and push the PR again?

[SolusCado]

I’ve rebased credit-card-management onto the latest main and pushed updates (including the Ready to Assign fix). Could you please re-check?

[DeLuca21]

Thanks, but I think something still went wrong with the rebase/update.

The PR is still removing some newer changes already in main, so I can’t merge it as-is.
I can still see it removing the recent monthly summary changes, description_placeholders, and the CZK / NIS currency updates.

Can you please check your branch again against current main and push an updated version?

[SolusCado]

Sorry; can you check one more time?

[DeLuca21]

Thanks for the update, this looks a lot better now and the PR seems to be down to the Credit Card related changes only.

I do not use credit cards in YNAB myself, so while the changes look reasonable from the diff, I am not fully sure if this is the best general approach for how credit accounts should be handled.

A few things I wanted to get your feedback on before I test it:

• due day is limited to 1–28, so I was not sure if that was intentional or if 29/30/31 should also be supported
• APR / due day / credit limit seem to apply to slightly different account types, so I wanted to confirm that is deliberate
• utilization / available credit look to be credit card only, so I wanted to check if that is expected too

It may suit your own setup already, but I just want to make sure it also lines up with how YNAB generally handles these accounts and how most users would expect them to work.

I am going to pull this locally and test the changes over the next couple of days before I merge it.

[SolusCado]

I limited the due day to 1-28 because many/most credit card companies wouldn't have a due date after the 28th, since it would then change on February. I at least have never seen it as an option.

From what I can tell with my own account data, the different fields are setup to only apply to appropriate account types (both loans and credit cards have an APR, but only credit cards have credit limits, etc.)

And yes; utilization/available credit are credit card specific.

I've tested this across all the different accounts I know of within YNAB.

[DeLuca21]

Thanks, that makes sense.

I will pull it locally and test it on my side over the next couple of days before I merge it.

[DeLuca21]

Thanks for working on credit-related features. Persisting a few HA-only fields is reasonable because the YNAB API does not expose credit limit, APR, or payment due day on the normal Account object the way it does balances.

I do not think this should merge as-is. The current shape fights how this integration is structured and will confuse people who rely on the config flow.

How this integration is usually structured

• Accounts: one sensor per selected account, with attributes for that account’s metadata.
• Categories: same for selected categories.
• Extras: budget-wide summary and API / diagnostic info, not a dumping ground for account-level features.

What is hard to accept in the current PR

Duplicate account surface
Credit metrics and config sit on separate per-account devices while the same accounts already exist under Accounts. One YNAB account should not be split across two “classes” in Home Assistant.

Extras pollution + always-on entities
Three always-on credit total sensors on Extras blur what Extras is for (month summary, API status) and shows credit UI even when a budget is not really using credit.

Fights the existing pattern
Per-account reads like utilization belong on YNABAccountSensor attributes, not extra entities. Budget-wide rollups, if we keep them, belong on the existing Extras summary sensor as attributes, not three new entities. Ideally those rollup attribute keys should not exist at all when no credit-type account is selected (implementation detail we can verify, but that is the behavior I want).

Config flow and cleanup
Credit-specific surfaces must follow selected accounts the same way account sensors do. Optional things like a Credit settings device for HA-only edits should only exist when a selected credit-type account exists, and must be removed/cleaned up when selection changes so nothing orphaned or unavailable contradicts the config.

Suggested direction

• Refactor: drop the parallel per-account credit device model and the three unconditional Extras sensors.
• Put per-account read-only credit output on YNABAccountSensor attributes, but only for credit-style account types (credit card, line of credit, etc.). A normal checking account should not suddenly grow APR / due date / credit-only fields that do not apply.
• Put budget rollups on the Extras summary entity as attributes, gated so they only appear when relevant, or omit rollups entirely if gating is too awkward.
• Keep HA-only edits behind options, services, or one gated Credit settings device (below Accounts/Categories, above Extras), with proper teardown.

If you want to iterate toward that shape, I am happy to help review a follow-up that keeps the useful persistence bits but matches the existing layout and the config flow. If anything in the above is unclear, say what you prefer and we can align on it before you spend more time on it.

[SolusCado]

Thanks for the thorough review and for taking time to lay out the preferred structure.

I want to push back on a few points so my intent is clear:

Per-account device structure
This is a deliberate design choice, not an accidental parallel surface.
The goal is to manage each credit account as a first-class HA object (including account-specific controls and telemetry), rather than routing all credit behavior through a shared Extras surface. From a UX perspective, splitting account-level behavior away from the account itself is harder to reason about for users who actively manage multiple credit lines.

“Extras pollution” concern
I agree Extras should not become a dumping ground, but I see total credit metrics as budget-level summary data, similar in spirit to other monthly summary outputs. They are also practical dashboard entities on their own (for example, debt/utilization gauges) without requiring attribute extraction helpers.

Applicability for non-credit users
I agree these should not show when irrelevant. I’m happy to gate them so they are only created when selected credit-type accounts exist, and disabled/absent otherwise.

Duplicate account surface
What I’ve observed is that duplicate-looking surfaces primarily occur on upgrade/migration paths to preserve existing entities. On clean setup, I do not see the same duplication behavior.
If needed, I can tighten migration/cleanup behavior to avoid orphaned surfaces when selections change.

I’m completely open to hardening the config-flow alignment and teardown behavior, but I’d like to preserve the core model of account-centric credit management instead of moving everything into account attributes + Extras attributes only.

If that architectural direction is still a hard no for this repo, I understand and can maintain this branch separately. But if there’s room for compromise, I can submit a follow-up that keeps the account-centric model while adding stricter gating/cleanup so the UX stays clean for non-credit setups.

[DeLuca21]

Thanks for the follow-up. I think we are aligned on the hygiene side overall.

Selection, gating, and cleanup

• Credit surfaces should only appear when they are relevant.
• They should respect selected accounts the same way the rest of the integration does.
• When selections or options change, we should tear down entities and devices cleanly so nothing is orphaned or contradictory.

API alignment (briefly)

• YNAB still models credit cards as normal Account objects with the same core balance fields as other accounts, mainly differentiated by type.
• I want Home Assistant to follow that mental model: one selected YNAB account maps to one primary account entity, with credit-specific readouts on that entity as attributes where applicable, not a parallel device tree that looks like a second account system.

HA-only configuration (limit, APR, due day)

• It is reasonable to persist these locally since YNAB does not expose them like balances.
• Those controls should obey the same config-flow lifecycle as everything else.
• If we need a clearer UI home, I am open to one optional “Credit” device per config entry, not one device per credit line.

Extras / budget-wide rollups

• I do not want three separate credit rollup sensors on Extras.
• If we want it separate from the existing monthly summary for clarity, one dedicated sensor is fine. I still do not want a trio of sibling entities.
• A single Credit summary-style sensor with attributes for the rollups is the right shape, and those attributes should be gated when there is nothing meaningful to show.

If this upstream direction is not what you want for your own install

• You are welcome to maintain a fork with your preferred layout.

What I am planning on my side

• I still intend to ship similar credit functionality here in this structure so it stays consistent with the rest of the integration.
• If you are comfortable with it, I may reuse parts of your implementation where it saves time. I will add attribution wherever I reasonably can.

[SolusCado]

Since each credit account has a different due date, interest rate, and credit limit, how exactly do you envision that being setup? A single credit 'device', with different entries for each credit account? That could make for a long and confusing list on a single device (particularly since they are HA-native inputs, and there are 3 per account).

[github-actions]

This pull request has been marked as stale due to inactivity. It will be closed in 7 days unless there is activity.

[DeLuca21]

Sorry for the slow reply here, I’ve been pretty busy and this sat longer than I meant it to.

I’ve tested the PR, and I do agree that both approaches have trade-offs and can get messy in different ways. Before deciding on the final structure, I’d like to try a few alternate methods and see if there’s a cleaner way to handle it.

In the meantime, feel free to keep using your own version if it works well for your setup. If I find a method I’m happier with, I’ll release it as a beta so you can test it and see what you think.

If I can’t find a cleaner solution, I’ll come back and revisit this approach rather than ruling it out completely.

I’ll keep the PR open for now so the stale bot doesn’t close it. Thanks again for the work on this.

[SolusCado]

🙂 Sounds reasonable. I'll keep an eye out for alternative approaches.