Support for balance forecast

[redford-jones]

Describe the feature

It would be useful to have the balance forecast data available in this integration. Currently I can see this data either using balance forecast page on my account dashboard or via the GraphQL livePaymentAdequacy object.

Expected behaviour

Inclusion of data as per the following query:

query BalanceForecast($accountNumber: String!) {
  livePaymentAdequacy(accountNumber: $accountNumber) {
    estimatedConsumption {
      sourceName
      usage
    }
    recommendedPayment {
      adjustment
      ongoing
      total
    }
    currentBalance
    targetBalance
    reviewedOn
  }
}

Which produces the following example data:

{
  "data": {
    "livePaymentAdequacy": {
      "estimatedConsumption": [
        {
          "sourceName": "Gas",
          "usage": [
            6974,
            6295,
            5616,
            3940,
            2446,
            1359,
            1087,
            1042,
            1495,
            3306,
            5163,
            6567
          ]
        },
        {
          "sourceName": "Electricity",
          "usage": [
            11930,
            10656,
            10540,
            9382,
            8803,
            7876,
            7992,
            8108,
            8339,
            9729,
            10540,
            11930
          ]
        }
      ],
      "recommendedPayment": {
        "adjustment": -2161,
        "ongoing": 13426,
        "total": 11265
      },
      "currentBalance": 58241,
      "targetBalance": 32298,
      "reviewedOn": "2023-11-22" 
}

Use Case

Monitoring actual usage versus estimated usage would enable the generation of alerts when monthly payments and account balances begin to deviate beyond a set threshold. This would, in turn, enable us to make adjustments to monthly direct debits as needed.

Confirmation

• By submitting this feature request, you agree that you have read the documentation and confirmed it does not already exist
• I am willing/able to help contribute to the solution of this feature

[BottlecapDave]

Hello and thanks for the feature request. I'm currently reworking on how data is retrieved based on some requests by OE along with some other features so I don't have time to implement this at the moment. If you would like it sooner and wish to add the feature yourself, I'm more than happy to accept a PR under the following acceptance criteria, but would hold off until #597 is complete.

1. Data coordinator which retrieves this data. Should follow pattern of other coordinators, but only pull new data every hour. This should raise an event (octopus_energy_electricity_consumption_estimates and octopus_energy_gas_consumption_estimates) when data is updated which includes all related retrieved estimated usages and the id of the related account (see saving session). I'm assuming each item in the array represents the month for the current year? If so, the data should be returned as an array of objects with the properties date (1st of month/year with a time of midnight) and estimate_in_kwh.
2. Sensors (disabled by default) that shows this months estimate. Ids should be in the form octopus_energy_{{ACOUNT_ID}}_electricity_this_month_estimated_consumption and octopus_energy_{{ACOUNT_ID}}_gas_this_month_estimated_consumption. The state calculation (e.g. find the current months data) should be extracted to a function and unit tested.
3. Sensor (disabled by default) that shows next months estimate. Ids should be in the form octopus_energy_{{ACOUNT_ID}}_electricity_next_month_estimated_consumption and octopus_energy_{{ACOUNT_ID}}_gas_next_month_estimated_consumption. The state calculation (e.g. find the next months data) should be extracted to a function and unit tested. This could share the same function with the above sensors.
4. Event entity (disabled by default) that listens for the raised events and exposes the related data. This is so people can plot on a graph if they want. Ids should be in the form octopus_energy_{{ACOUNT_ID}}_electricity_consumption_estimates and octopus_energy_{{ACOUNT_ID}}_gas_consumption_estimates
5. Each entity should only be available if a valid meter exists for that energy source (e.g. if no gas meters exist with a valid tariff then octopus_energy_{{ACOUNT_ID}}_gas_this_month_estimated_consumption should not be available.
6. Api client function should have an integration test. This should be loose, but just test that data is returned in the right shape.
7. Coordinator should be unit tested (see other coordinators for what is expected)
8. Update docs

[redford-jones]

Thanks for the update @BottlecapDave. I have some time off over Christmas, so will try to put some time aside to implement it before the new year.